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.
Open your terminal and execute:
if the CMake version is lower than 3.1, please upgrade.
You should use out-of-source builds, this means you need to create a different directory than cocos2d-x to execute the
Step by Step
cd cocos2d-x mkdir linux-build && cd linux-build cmake .. make
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
cmake --build . to compile, or open Cocos2d-x.sln in Explorer to use the generated 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_TOOLCHAIN_FILE=../cmake/ios.toolchain.cmake open Cocos2d-x.xcodeproj
The default build is for running on actual iOS hardware, if you want to run in the simulator, please add
-DIOS_PLATFORM=SIMULATOR for architecture i386 or
-DIOS_PLATFORM=SIMULATOR64 for x86_64.
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=ndk-build
If you want to add cmake build arguments, please add it at external Native Build block of app/build.gradle file.
Prebuilt libraries feature
To solve long compilation times of the engine source code one can use prebuilt libraries. Using this feature you only need build engine sources once for a specific environment or again when the engine version changes and you wish to utilize the new version.
This is an example of building c++ libs once, and use them in different c++ projects.
cocos new -l cpp -p my.pack.app1 test_app1 mkdir app1_build && cd app1_build cmake ../test_app1 -DGEN_COCOS_PREBUILT=ON make prebuilt
GEN_COCOS_PREBUILT and use instead
USE_COCOS_PREBUILT to use prebuilt in the same project
cmake ../test_app1 -DGEN_COCOS_PREBUILT=OFF -DUSE_COCOS_PREBUILT=ON make TemplateCpp open bin/TemplateCpp.app
-DUSE_COCOS_PREBUILT=ON to use prebuilt libs in another cmake build.
cocos new -l cpp -p my.pack.app2 test_app2 mkdir app2_build && cd app2_build cmake ../test_app2 -DUSE_COCOS_PREBUILT=ON make TemplateCpp open bin/TemplateCpp.app
Any other cpp project can use prebuilt in this way
When using the prebuilt libraries on Android there is a small difference as CMake can't find system environment when built using Gradle. You need to supply a path as the location of prebuilt libs.
CMake Common Build Options
-G, generate native build project you specified, for example
-GXcodegenerate Xcode project files.
-GVisual Studio 15 2017generate Visual Studio 2017 project, the default toolset is v141, add
-Toption to specify toolset, like this
CMAKE_BUILD_TYPE, specify the build mode, Debug or Release
-DCMAKE_BUILD_TYPE=Releaseto generate the Release mode project, the default build mode is Debug
-Hspecify the CMake project Home directory,
-Bspecify CMake-generated project binary directory. for example
-H..\cocos2d-x -Bmsvc_buildthe generated native project's location will be
--build <dir>, build a CMake-generated project binary tree, for example
cmake --build ./msvc_build, cmake will sellect corresponding build tools.
GEN_COCOS_PREBUILT, control the project have the feature to generate pre-build libraries or not. Default value is
-DGEN_COCOS_PREBUILT=ON, will add target prebuilt, build this target will generate prebuilt libraries
USE_COCOS_PREBUILT, control the project have the feature to use pre-build libraries or not. Default value is
-DUSE_COCOS_PREBUILT=ON, will disable libraries target, and make app target use prebuilt libraries
COCOS_PREBUILT_ROOT, a path means the prebuilt libraries root location, it's not optional for Android Project on Android Studio, optional for other supported platforms. the default value is $cocos2dx_root/prebuilt if the cmake can access to cocos2d-x environment variable. for example
arguments "-DCOCOS_PREBUILT_ROOT=/Users/laptop/cocos-prebuilt"set this value on cmake block of build.gradle file.
Any options in SelectModule.cmake can be set manually. Do it if you know what you're doing.