Linux Installation and Setup

Prerequisites

A supported environment. See Installation Prerequisites

Ubuntu versions

We support Ubuntu 12.10+, however, newer versions of Ubuntu have changed and the steps to install Cocos2d-x and required dependencies are a bit different. This requires some manual effort and this doc will outline what is required.

Dependencies that you need

Cocos2d-x requires a number of dependencies be installed on your system. Please perform the following steps:

Update operating system components

  sudo apt-get update
  sudo apt-get upgrade

Install Dependencies (Ubuntu 16.x only)

Install dependencies

// Ubuntu 16.x
sudo apt-get install python2 git curl g++ libgdk-pixbuf2.0-dev python-pip cmake libx11-dev libxmu-dev libglu1-mesa-dev libgl2ps-dev libxi-dev libzip-dev libpng-dev libcurl4-gnutls-dev libfontconfig1-dev libsqlite3-dev libglew-dev libssl-dev libgtk-3-dev libglfw3 libglfw3-dev xorg-dev

Install Dependencies (Ubuntu 17.x only)

Add a repo to /etc/apt/sources.list

deb //cz.archive.ubuntu.com/ubuntu xenial main

Install Dependencies

sudo apt-get install python2.7 git curl g++ libgdk-pixbuf2.0-dev python-pip cmake libx11-dev libxmu-dev libglu1-mesa-dev libgl2ps-dev libxi-dev libzip-dev libpng-dev libcurl4-gnutls-dev libfontconfig1-dev libsqlite3-dev libglew-dev libssl-dev libgtk-3-dev libglfw3 libglfw3-dev xorg-dev

Install Dependencies (Ubuntu 18.x only)

Install dependencies.

sudo apt-get install python-minimal git curl g++ libgdk-pixbuf2.0-dev python-pip cmake libx11-dev libxmu-dev libglu1-mesa-dev libgl2ps-dev libxi-dev libzip-dev libpng-dev libcurl4-gnutls-dev libfontconfig1-dev libsqlite3-dev libglew-dev libssl-dev libgtk-3-dev libglfw3 libglfw3-dev xorg-dev

Install Dependencies (Ubuntu 20.x only)

Install dependencies.

sudo apt-get install python2-minimal git curl g++ libgdk-pixbuf2.0-dev cmake libx11-dev libxmu-dev libglu1-mesa-dev libgl2ps-dev libxi-dev libzip-dev libpng-dev libcurl4-gnutls-dev libfontconfig1-dev libsqlite3-dev libglew-dev libssl-dev libgtk-3-dev libglfw3 libglfw3-dev xorg-dev

Finish Python.

curl https://bootstrap.pypa.io/get-pip.py --output get-pip.py

sudo python2 get-pip.py

Setting up Cocos2d-x

You can get started with Cocos2d-x by either downloading a self-contained .zip from the website or by cloning our GitHub Repo. Pick what works for you. There is no need to do both.

By downloading a .zip archive

Download Cocos2d-x and unzip it. (maybe: ~/ or ~/Projects )

Cloning from GitHub

Use the following commands to clone our GitHub repo and get your environment setup. If you are not familar with GitHub's workflow, learn it or download using the step above, By downloading a .zip archive.

Clone Repo and setup dependencies

// all linux versions
cd <to where you want to clone this repo>

git clone https://github.com/cocos2d/cocos2d-x.git

cd cocos2d-x-root #where your cocos2d-x directory is located.

git submodule update --init

git submodule update

// Ubuntu 16, 17
python download-deps.py

// Ubuntu 18, 20
python2 download-deps.py

Make sure you have a working environment!

See Prerequisites above. This means a working Python, git and curl along with the dependency list above.

Building Cocos2d-x

Run cmake to generate makefile:

cd cocos2d-x-root # where your cocos2d-x directory is located.
mkdir -p build/linux-build
cd build/linux-build
cmake ../..

When cmake finishes, many files & folders will be generated in coocs2dx_root/build/linux-build
Run make to compile:
```
make -j 4
```
Everything will be generated in cocos2dx_root/build/linux-build/bin/cpp-tests/ if compiled successfully.

Run cpp-tests

cd cocos2dx_root/build/linux-build/bin/cpp-tests/
./cpp-tests

Starting a new project

Once everything above works, you can start a new project! To do this, read our document on the Cocos Command-line tool.

Troubleshooting

Please see this F.A.Q for troubleshooting help. Linux has a few known issues.

Linux