axmol/cmake

CMake Guide

CMake is an open-source, cross-platform family of tools designed to build, test and package software. CMake is used to control the software compilation process using simple platform and compiler independent configuration files, and generates native makefiles and workspaces that can be used in the compiler environment of your choice.

Requirement

1. Open your terminal and execute:

cmake --version

if the CMake version is lower than 3.6, please upgrade.

2. You should use out-of-source builds, this means you need to create a different directory than cocos2d-x to execute the cmake command.

Step by Step

Linux

cd cocos2d-x
mkdir linux-build && cd linux-build
cmake ..
make

Execute make help to see all build targets, make <target> build specified target

Generate Visual Studio projects

cd cocos2d-x
mkdir win32-build && cd win32-build
cmake .. -G"Visual Studio 15 2017" -Tv141

Execute cmake --build . to compile,

cmake --build . --config Debug
cmake --build . --config Release

or open Cocos2d-x.sln in Explorer to use the generated project.

If can't found MSVCR110.dll issue occurs to you, please install this Visual C++ Runtime Libraries, when runing the cpp-tests project

Generate macOS Project

cd cocos2d-x
mkdir mac-build && cd mac-build
cmake .. -GXcode
open Cocos2d-x.xcodeproj

Generate iOS Project

cd cocos2d-x
mkdir ios-build && cd ios-build
cmake .. -GXcode -DCMAKE_SYSTEM_NAME=iOS -DCMAKE_OSX_SYSROOT=iphoneos
open Cocos2d-x.xcodeproj

The parameter -DCMAKE_OSX_SYSROOT=iphoneos is optional, it generates a build for running on the iOS device. If you want to run in the simulator, please add -DCMAKE_OSX_SYSROOT=iphonesimulator, but remember you can't run a metal-support app in the simulator until Xcode 11 and MacOS 10.15.

if you want to sign iOS app in CMake, you will need to fill development team ID into set_xcode_property(${APP_NAME} DEVELOPMENT_TEAM ""), or select to sign in Xcode after project files generated.

Android Studio

We use the Gradle for Android applications, and Gradle use cmake to build the native code, see gradle.properties: PROP_NDK_MODE, it controls how native builds work.

# android native code build type
# none, native code will never be compiled.
# cmake, native code will be compiled by CMakeLists.txt
# ndk-build, native code will be compiled by Android.mk
PROP_BUILD_TYPE=cmake

If you want to add cmake build arguments, please add it at external Native Build block of app/build.gradle file.

Build Options

CMake Common Build Options

1. -G, generate native build project you specified, for example

   • -GXcode generate Xcode project files.
   • -GVisual Studio 15 2017 generate Visual Studio 2017 project, the default toolset is v141, add -T option to specify toolset, like this -Tv140

2. CMAKE_BUILD_TYPE, specify the build mode, Debug or Release

   • -DCMAKE_BUILD_TYPE=Release to generate the Release mode project, the default build mode is Debug

3. -H -B, -H specify the CMake project Home directory, -B specify CMake-generated project binary directory. for example

   • -H..\cocos2d-x -Bmsvc_build the generated native project's location will be msvc_build directory.

4. --build <dir>, build a CMake-generated project binary tree, for example

   • cmake --build ./msvc_build, cmake will sellect corresponding build tools.

Tips

1. Use cmake .. to refersh resources and code files, after you modify Resources or CMakeLists.txt.
2. Don't need CMAKE_BUILD_TYPE options when -G Xcode or Visual Studio, CMake scripts will generate both configurations, so you can switch Debug and Release in IDE.

Useful Links

• CMake Official website: cmake.org

• CMake Documentation: cmake.org/documentation

• CMake FAQ: Wiki/CMake_FAQ