CMake support all platform build & prebuilt libs for cocos2d-x

CMake support all platform build & prebuilt libs for cocos2d-x
0.0 0


I am working on the CMake build system for cocos2d-x, this is some introduction about what have done and what need to be done.


Our final target is CMake support all platforms and could generate Xcode and VS project. This is the pieces of our final target and the process below.

Target Develop Test Pull Request
Linux Done Once, Ubuntu 16.04
Android Done Once, Need Further 18154 18646 300
macOS Done Twice, Need Further 18646
iOS Done Once, using iOS Simulator 18646
Windows Done Once, only msvc 18683
Xcode Done Once, using Xcode 9.2 18646
VS Done Once, using VS2017 on Win10 18683
Prebuilt Support Done Test once in every platform above 18683

Target is the CMake build aim for every one platform, Develop is used to describe the develop process, and the Test stand for test process, I think we can’t merge it into main branch if we didn’t have full test.

Current Situation

  1. As we all known, the build system of cocos2d-x is quite different on different platform, CMake build for linux, Xcode project for macOS, VS project for Windows, and ndk Build for Android Native. It’s complex to maintain, and not friendly to use for cross-platform developers

  2. The official team only keep the CMake build on linux, meanwhile many developers push it support other platforms from time to time, recently developer newnon does a lot of works to push it support Android. see PR V3 android cmake support #18154 and Android cmake build support #300

  3. Following the method of newnon, the CMake support for Android Native Build is almost done, and some build error on macOS have been fixed, see PR [in-progress] V3 android cmake support, add mac support

  4. Done for every platforms, but still need improvement

Plan Next

In a word, works on the targets one by one. I will update the targets table when one of the targets is finished, and I hope you join in this great work, do some works marked To Do, or do further test, that is meaningful.

Struct Ideas

introduce the realization of CMake now, some important CMake files and Moduals

CMake File Directory Meanings
root/ build Cocos2d-x project include all engine library and all tests
root/cocos/ build engine core library, build js/lua library if needed
test project/ build test project and engine library needed
template project/ build the project of cocos new, it’s really like the test project

CMake Module Meanings Comments
CocosBuildSet the common part of every project need, such as set cmake_policy
SelectModule set the default behavior of build module, many opitions
SetCompilerOptions set compiler options depend on different platform and opitions

root in the CMake File Directory stand for the cocos2d-x engine directory


Thats all nice.

Why this is not n1 method actually.

  • easy to use.
  • super fast to compile every time.
  • super rasy to update.
  • if source code needed - easy to add source files into project.

Really no drawbacks. Who really goes to source code and change there anything?
I’m developing games and only a coupe of times I need to check source, just to find information not listen in the docs.


thanks for you reply, every one who contribute to cocos2d-x need change source code, include warm community developers and cocos2d team. so we need to finish CMake on every platforms, and then add the way of CMake prebuilt.


I mean when you develop game.
You just work with your game code and you don’t need to have attached into your project a heavy sources of the engine, it’s in 99%.


Which configuration should the prebuilt lib are using? Release or Debug? I would like to have debug for debug and release for release. If you have just one configuration, you have mixed code.

And as others said before, if you don’t change branches, the cocos code isn’t recompiled on every build, only the changed files. So I don’t see a big advantages in creating prebuilt libs for my workflow. This is also true for third party libs (which are in prebuilt libs, but I want them as sources). - I wish I would have the complete engine as source code and could compile it completely by myself.

PS: Even Unreal is installing the sources by default.


I can understand both needed, some developers only want the binary engine, they doesn’t care the internal realization of engine, develop game just need the interface. In other side, some developers like the all sources code, they like to search the internal, find the defect of engine, even custom the engine.

we hope make both side satisfied finally, supply a easy way to prebuilt engine library, and give the way to using third library source code. I think CMake have a great advantage to help us achieve this goal. meanwhile, cocos2d-x is a cross-platform engine, but the older CMake is only support Linux, Rome was not built in a day, we can’t finish this work in a week, so I think the first step is expanding the CMake to support all plarforms, after that prebuilt engine library, then third library source code.


We should worry about making everything work with CMake before focusing on Prebuild Libs. It’s not worth it to make it now only to change it significantly later.

Also, Idk about everyone else environment, but when I build on android the first in a project, I never rebuild unless I edit some of the internal code, Which is also extremely rare.

Anyways, @drelaptop Great job and keep up the good work!


For iOS in Xcode it will rebuild every time when you archiving build or ofc after cleaning project.
With prebuilts it’s all eliminated forever. Save a lot of time. I can’t even imaging development without them.


True, but at the expense of the whole reason for this project, it’s open source! Prebuilts are a very optional piece and are a “Nice to have” but not a “Need to have”, at least not at this moment

Also, We need to consider that time and effort it will take to make this consistent on ALL platforms. The cocos staff probably not focusing on it since they don’t have the bandwidth too. Remember this is open source we are talking about.

Once CMake integration is finished and there is a unified, cross-plaform system in place, Then prebuilts become important, because at least then, we can be sure that it’ll be done the right way and won’t change much VS. making a quick and dirty way that will be unreliable, hard to maintain because of the different platforms, break easy and untimely change in the future, meaning we’ll be wasting time trying to do it now.

Wouldn’t you agree?


I don’t understand what stoping you from downloading and opening cocos2d-x.project and check all sources you need. Or prebuilts will remove source code from github for some reason?


@mozartalouis I quite agree with you, you exactly said the truth. AFAIK, cocos team also want to unify the build system, and make it easy to use for all developers. but it’s not a core feature for a open source engine, we can’t cover the bandwidth before, as you said it’s “Nice to have”,

In fact, I am a new member of cocos team, @zhangxm suggest me to charge this work, and push it finished. even though I am not a expert CMake worker, I think I can do this work well, and finish it months later.


@mozartalouis yep, prebuilts supporting is in a low priority.


Now, Most of cocos2d-x could build and run well on macOS and iOS, and can generate Xcode project.
this is the part manual, those works have been merged into v3 branch

using CMake in macOS terminal

cmake -H$COCOS_TEMPLATES_ROOT/.. -Bbuild_cocos2dx
cd build_cocos2dx
make all -j 4

Generate Xcode Project for macOS platform

cmake -H$COCOS_TEMPLATES_ROOT/.. -Bbuild_mac -GXcode
cd build_mac
open Cocos2d-x.xcodeproj

cmake --build <dir> = Build a CMake-generated project binary tree. use this command to build in terminal directly

Generate Xcode Project for iOS platform

cd any_dir_you_want
cd build_ios_sim64
open Cocos2d-x.xcodeproj

cmake --build <dir> = Build a CMake-generated project binary tree. use this command to build in terminal directly


  1. Lua template project run failed on macOS, for it need simulator and the simulator not have any CMake files, I think it’s not hurry, so I plan to put it after others works done
  2. the Images.xcassets and LaunchScreen.storyboard didn’t work for iOS project generated by CMake, it need to solve later


cmake support MSVC


PR 18683, Not Merged

cmake -H"..\cocos2d-x\" -Bmsvc_build -G"Visual Studio 15 2017" -DCMAKE_BUILD_TYPE=Debug
cmake -H"..\cocos2d-x\" -Bmsvc_build -G"Visual Studio 15 2017" -DCMAKE_BUILD_TYPE=Release

For now, we can use command like above to generate Visual Studio project, and then open the Cocos2d-x.sln in msvc_build folder, every project in Cocos2d-x.sln works well. I test this in Visual Studio 2017 on Windows 10.


  1. lua template project not add in Cocos2d-x.sln, it need to be done next
  2. Debug and Release mode all tested pass, remember that -DCMAKE_BUILD_TYPE=Debug not DEBUG or debug
  3. compile options and link options might not perfect, If you have suggestions when you test, please tell me, I will quite appreciate


  1. improve the cmake scripts, make it readable and expandable
  2. finish cmake support Lua template project on win32/mac
  3. further tests, for example debug mode and release mode in every platforms

Multithreaded compile on Windows

Feature: prebuilt support finished in PR 18683 @KAMIKAZE

generate and use prebuilt is simple, you only need add 2 or 3 cmake variable.

add "-DGEN_COCOS_PREBUILT=ON" and "-DUSE_COCOS_PREBUILT=OFF" // will add target prebuilt, build the target will generate prebuilt libs
add "-DGEN_COCOS_PREBUILT=OFF" and "-DUSE_COCOS_PREBUILT=ON"  //not include libs target and prebuilt target, directly use the prebuilt libs in prebuilt directory
//add "COCOS_PREBUILT_ROOT" to set prebuilt libs directory, the default prebuilt directory is `cocos2d-x-root/prebuilt`, cmake get the path by `$ENV{COCOS_TEMPLATES_ROOT}/../prebuilt`, but when using cmake in android studio, it can't get environment variable `COCOS_TEMPLATES_ROOT`, so you should set the prebuilt directory manually. the corresponding cmake variable is `COCOS_PREBUILT_ROOT`

Attention: the default prebuilt behavior is GEN_COCOS_PREBUILT and USE_COCOS_PREBUILT both OFF, and don’t set both cmake variable ON please


Hey, thanks for the update.
Q: can iOS and macOS targets be in one project as currently? It’s so convenient to switch between targets in one project.

Currently I’m working with custom cocos2d-x, because of SBX. So merging this is not so fast. When I get updated version I will check this as soon as I can.


As far as I know, we can’t archive this by cmake logic.

the similar question occurred to me is generate Debug and Release project at the same time, it’s convenient only change Debug/Release button to switch build mode on Visual Studio. but I didn’t find the resolution for now.

another issue, cmake always generate info.plist when generated Xcode project, it’s bad friendly to package iOS or macOS app.


@drelaptop Hmm… now I’m thinking about these drawbacks, probably for iOS and macOS it’s can be like optional to use cmake… Currently, developing for iOS and macOS is a pleasure, as usually, no problems and all fast and convenient. So now as I see, using cmake give some awkward problems actually… Probably it;s better to use native Xcode for iOS and macOS as currently, because it’s best ever option and easy to use… Afterwards, with cmake we will able to use native like Xcode project(with iOS&macOS targets inside) ?

upd. I can test this only after 3.17 release and only after some time… because I’m using SBX which is using non official cocos2d-x by newnon. Currently I’m trying to build it using ndk, but it’s not works for my game…

Pre-built libs for android not compiles(as usually :) ), how to build using option with full source code of cocos2d-x and Android Studio?

With cmake you develop in Xcode.
Option -GXcode generate Xcode project files (and there is -GVisual Studio 15 2017).


Repeat: iOS and macOS targets in one project.