CMake 指南

CMake 指南

CMake 是一个开源的跨平台构建工具，Cocos2d-x 是一个开源的跨平台游戏引擎，两者十分契合。

Cocos2d-x 决定自 3.17 版本开始，支持 CMake 的全平台构建。支持的平台包括 Android (NDK)、iOS、macOS、Linux、Windows（VC++ compiler），同时支持通过 CMake 将引擎部分进行预编译，并在新的构建过程中重用预编译的引擎库。

基本概念

在使用 CMake 构建工程之前，最好能对软件构建中一些基本的概念有初步的了解，比如什么是编译，链接，打包。了解这些对后续使用 CMake 有很大的帮助。

此处只解释一下：外部构建（Out-of-source Build），在从源码生成最终的二进制可执行文件的过程中，会生成大量的中间文件，中间文件和源码在同一个目录内时会使源码目录混乱不堪，使用外部构建，即将所有生成的中间文件都放在一个非源码目录中，这样无论构建多少次，源码目录始终干净如新。

常用构建选项

CMake 通用

-G，通过 CMake 生成特定 IDE 的项目配置文件。这个操作依赖 IDE，即无法在一个没安装 Xcode 的 macOS 上通过 CMake 生成对应的工程文件。
- -GXcode 生成 Xcode 工程文件
- -GVisual Studio 15 2017 生成 Visual Studio 2017 工程文件
CMAKE_BUILD_TYPE, 指定构建模式，比如 Debug 还是 Release，默认值 Debug。
- -DCMAKE_BUILD_TYPE=Release 指定以 Release 模式生成工程。
-H -B，-H 用来指定一个源码目录，指定的目录必须含有一个 CMakeLists.txt 文件，-B 用来指定 CMake 生成的中间文件的存放目录。
- -H..\cocos2d-x -Bmsvc_build 指定要构建工程的工程路径是上一级目录的 cocos2d-x 子目录，指定 CMake 生成的文件存放在 msvc_build 目录。
—build
执行构建过程，同时指定曾使用 CMake 命令生成的构建文件所在目录。

cmake —build ./msvc_build 在执行这个构建过程时，CMake 会自动选择对应的构建工具。
Cocos2d-x 特有

以下 Cocos2d-x 特有的选项和使用预编译库有关。

GEN_COCOS_PREBUILT 控制构建过程是否生成预编译库，默认行为是不生成，开启选项将会增加一个构建目标：prebuilt，执行这个构建目标时，将会编译引擎部分的代码，并将生成的库文件，拷贝至存放预编译库的目录，默认将库拷贝至引擎目录的 prebuilt 子目录。
- -DGEN_COCOS_PREBUILT=ON 将会增加一个构建目录：prebuilt，用于执行库的生成，拷贝。
USE_COCOS_PREBUILT 控制生成的构建工程是否使用预编译库，默认行为是不使用，开启选项将会自动查找使用预编译库，关闭库相关的构建目标，默认在引擎目录的 prebuilt 子目录查找预编译库。
- -DUSE_COCOS_PREBUILT=ON 将会自动使用预编译库，关于库相关的 target。
COCOS_PREBUILT_ROOT 指定预编译库存放的目录，是一个可选选项，对于在 Android 平台中使用预编译库是一个必选选项，因为正常情况下，Android Studio 在进行 CMake 构建过程时，无法获取到环境变量，导致找不到引擎根目录。
- -DCOCOS_PREBUILT_ROOT=/Users/laptop/cocos-prebuilt 设置存放预编译库的目录
  各平台构建示例

Linux

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

在执行 make -j 4 命令之前，可以执行 make help 查看所有的构建目标，使用 make <target> 构建一个特定的目标。

macOS

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

在 macOS 上使用 cmake .. -GXcode 将会默认生成 macOS 的工程。iOS 工程和 macOS 工程并不能同时生成到一个 XCode 工程中。

iOS

cd cocos2d-x
mkdir ios-build && cd ios-build
cmake .. -GXcode -DCMAKE_TOOLCHAIN_FILE=../cmake/ios.toolchain.cmake
open Cocos2d-x.xcodeproj

默认构建的是为运行在 iOS 设备的工程，如果想构建运行在模拟器的工程，请加参数 -DIOS_PLATFORM=SIMULATOR 或 -DIOS_PLATFORM=SIMULATOR64。

Android

默认工程配置在 Android 上使用旧有的 ndk-build 构建 C++ 部分，开启 CMake 构建，请先更改 Gradle 配置中的 PROP_NDK_MODE 属性为 cmake，再同步 Gradle 配置，同步完成后，可以看到外部构建脚本从 Android.mk 变为了 CMakeLists.txt。

# 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

如果需要在 Android Studio 中使用预编译库，需特别设置预编译库存放的目录，请参考关于预编译库的介绍，以及 build.gradle 中的注释。

Windows

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

以上命令使用 CMake 生成 Cocos2d-x 测试项目的 Visual Studio 2017 工程。生成后，在文件浏览器中找到 cocos2d-x/win32-build 目录，双击打开 Cocos2d-x.sln。设置 cpp-tests 为启动项目，即可正常编译运行。

另一种方式，由于 Visual Studio 2017 已经直接支持 CMake 工程，可以直接使用。详细请参考 CMake 支持。

预编译库示例

使用引擎的预编译库，可以避免再次编译引擎代码，将引擎部分的代码编译时间缩减为零！从而有效的降低项目的构建时间。以下示例为使用一个 C++ 工程生成预编译库，并在其它 C++ 工程中使用。

开启 GEN_COCOS_PREBUILT 选项，生成预编译库

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 选项，开启 USE_COCOS_PREBUILT 选项，在本项目中使用预编译库

cmake ../test_app1 -DGEN_COCOS_PREBUILT=OFF -DUSE_COCOS_PREBUILT=ON
make TemplateCpp
open bin/TemplateCpp.app

直接开启 USE_COCOS_PREBUILT 选项，在一个新的项目中使用生成的预编译库

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