2019-11-23 20:27:39 +08:00
# 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:
```sh
cmake --version
```
2021-04-22 22:01:47 +08:00
if the CMake version is lower than 3.14, please upgrade.
2019-11-23 20:27:39 +08:00
2022-08-08 18:02:17 +08:00
2. You should use **out-of-source** builds, this means you need to create a different directory than **axys** to execute the `cmake` command.
2019-11-23 20:27:39 +08:00
## Step by Step
### Linux
```sh
2022-08-08 18:02:17 +08:00
cd axys
2019-11-23 20:27:39 +08:00
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
```sh
2022-08-08 18:02:17 +08:00
cd axys
2021-04-22 22:01:47 +08:00
mkdir win32-build
cmake -B win32-build -G"Visual Studio 16 2019"
# build
cmake --build win32-build --config Debug
2019-11-23 20:27:39 +08:00
```
2022-08-08 18:02:17 +08:00
or open **axys.sln** in Explorer to use the generated project.
2019-11-23 20:27:39 +08:00
### Generate macOS Project
```sh
2022-08-08 18:02:17 +08:00
cd axys
2021-04-22 22:01:47 +08:00
mkdir mac-build
cmake -B mac-build -GXcode
2022-08-08 18:02:17 +08:00
open mac-build/axys.xcodeproj
2019-11-23 20:27:39 +08:00
```
### Generate iOS Project
```sh
2022-08-08 18:02:17 +08:00
cd axys
2021-04-22 22:01:47 +08:00
mkdir ios-build
2022-09-05 14:13:52 +08:00
cmake -B ios-build -GXcode -DCMAKE_TOOLCHAIN_FILE=$AX_ROOT/cmake/ios.toolchain.cmake -DPLATFORM=OS64
2022-08-08 18:02:17 +08:00
open ios-build/axys.xcodeproj
2019-11-23 20:27:39 +08:00
```
#### How do I customize the generated Xcode project?
2022-08-08 18:02:17 +08:00
Xcode project settings that you want to affect both the app project and the axys library project should be passed on the command
2019-11-23 20:27:39 +08:00
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:
![Find Xcode Build Setting ](images/Xcode_Find_Setting_Name.png )
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
2022-08-08 18:02:17 +08:00
As explained above, pass this on the command line so both the app the axys are built using the same version:
2019-11-23 20:27:39 +08:00
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 ](https://developer.apple.com/account/resources/certificates/list ) 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` :
![Xcode General Page ](images/Xcode_General_Page.png )
### Android Studio
2022-08-08 18:02:17 +08:00
We use the Gradle for Android applications, and Gradle use cmake to build the native code, see [gradle.properties ](https://github.com/axys1/axys/blob/84be684e3858393a6f3efc50e3f95d4e0ac92a20/tests/cpp-empty-test/proj.android/gradle.properties#L38 ): `PROP_NDK_MODE` , it controls how native builds work.
2019-11-23 20:27:39 +08:00
```sh
# 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
```
2022-08-08 18:02:17 +08:00
If you want to add cmake build arguments, please add it at [external Native Build ](https://github.com/axys1/axys/blob/84be684e3858393a6f3efc50e3f95d4e0ac92a20/tests/cpp-empty-test/proj.android/app/build.gradle#L25 ) block of __app/build.gradle__ file.
2019-11-23 20:27:39 +08:00
## Build Options
### CMake Common Build Options
1. __ `-G` __, generate native build project you specified, for example
* `-GXcode` generate Xcode project files.
2020-10-22 17:58:21 +08:00
* `-GVisual Studio 16 2019` generate Visual Studio 2019 project, the default toolset is v141, add `-T` option to specify toolset, like this `-Tv142`
2019-11-23 20:27:39 +08:00
1. __ `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
1. __ `-H -B` __, `-H` specify the CMake project Home directory, `-B` specify CMake-generated project binary directory. for example
2022-08-08 18:02:17 +08:00
* `-H..\axys -Bmsvc_build` the generated native project's location will be `msvc_build` directory.
2019-11-23 20:27:39 +08:00
1. __ `--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` .
1. 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 ](https://cmake.org/ )
* CMake Documentation: [cmake.org/documentation ](https://cmake.org/documentation/ )
* CMake FAQ: [Wiki/CMake_FAQ ](https://cmake.org/Wiki/CMake_FAQ )