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.14, please upgrade.

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

Step by Step

Linux

cd engine-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 engine-x
mkdir win32-build
cmake -B win32-build -G"Visual Studio 16 2019"
# build
cmake --build win32-build --config Debug

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

Generate macOS Project

cd engine-x
mkdir mac-build
cmake -B mac-build -GXcode
open mac-build/engine-x.xcodeproj

Generate iOS Project

cd engine-x
mkdir ios-build
cmake -B ios-build -GXcode -DCMAKE_TOOLCHAIN_FILE=cmake/ios.mini.cmake
open ios-build/engine-x.xcodeproj

How do I customize the generated Xcode project?

Xcode project settings that you want to affect both the app project and the engine-x library project should be passed on the command line when invoking cmake.

Xcode project settings that you want to affect the app project only shoudl be put into the its CMakeLists.txt file.

Any Xcode Build Setting can be changed by setting CMAKE_XCODE_ATTRIBUTE_XXX where XXX is the name found within the Xcode Build Settings page of the target. The following image shows the name of the iOS Deployment Target:

Cocos also provides the function set_xcode_property() to make this easier to set from within a CMakeLists.txt file, where only the XXX part needed to be specified:

set_xcode_property(${APP_NAME} XXX "Value")

Deployment Target

As explained above, pass this on the command line so both the app the engine-x are built using the same version:

For iOS pass -DCMAKE_XCODE_ATTRIBUTE_IPHONEOS_DEPLOYMENT_TARGET=version, where version is 9.0, 10.0, etc.

For macOS pass -DCMAKE_XCODE_ATTRIBUTE_MACOSX_DEPLOYMENT_TARGET=version, where version is 10.12, 10.13, etc.

Code Signing Development Team

This should be set in the app CMakeLists.txt file. You only need to set the "Development Team" as Xcode will automatically manage the other settings (certificate type, etc.). However the value you set is the 10-digit serial number following the development team name, which you can see in the top-right of the Apple Developer Certificates page.

Set it like this:

set_xcode_property(${APP_NAME} DEVELOPMENT_TEAM "GRLXXXX2K9")

Bundle Identifier, Version numbers and Device Support

All this information is held in the Info.plist file that is part of the app's source files and is therefore not generated by cmake. Therefore you can update these values from the General page of the Xcode target and the values will be preserved the next time you regenerate the project from cmake:

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 16 2019 generate Visual Studio 2019 project, the default toolset is v141, add -T option to specify toolset, like this -Tv142

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..\engine-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