[in-progress] CMake support all platform for cocos2d-x


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 Before Once, Ubuntu 16.04
Android Done Recently Once, Need Further 18154 18646 300
macOS Done Twice, Need Further 18646
iOS Done Once, using iOS Simulator 18646
Windows Almost Done Once, only msvc 18683
Xcode Done Once, using Xcode 9.2 18646
VS Almost Done Once, using VS2017 on Win10 18683
Prebuilt Support To Do To Do

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

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
CocosUsePrebuiltLibs the old method of using the third library might improved
SelectModule set the default behavior of build module, many opitions
SetCompilerOptions set compiler options depend on different platform and opitions need divide?

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