How to Run Cocos2D-X Samples on Android

Let’s take MacOS as an example, the processes on win32 and linux are more or less the same.

Prerequisite

Download Cocos2D-X

At first, you should download cocos2d-x and unzip it. We could simply unzip it on the root directory of your home folder.

Double click the folder cocos2d-x and you will find a lot of files and folders. Here it the screenshot:

Before configuring the development environment, let’s download some dependency software at first.

Download JDK, SDK and NDK

Since we are trying to develop Android games, so Java is a must have toolkit.

• Open Your Terminal(You can hit Control-Space to open Spotlight and enter “Terminal” and hit “Enter” key), input the following commands to verify whether your machine supports java or not.

java -version

If the following lines shown on your Terminal then you may have get [[JDK|http://www.oracle.com/technetwork/java/javase/downloads/index.html]] properly installed.

(Note, the java version number may be different, but it’s doesn’t matter. As to cocos2d-x, you could upgrade the JDK and we recommend you to install JDK 1.6 or 1.7)

java version "1.7.0_51"
Java(TM) SE Runtime Environment (build 1.7.0_51-b13)
Java HotSpot(TM) 64-Bit Server VM (build 24.51-b03, mixed mode)

• Download the Android SDK. If you are using Mac, click this link to download ADT Bundle for Mac.
  The bundle includes the newest Android SDK version plus an Eclipse version with Android Development Tool installed. So we don’t need to download an extra Eclipse and install the ADK manually any more.

After downloading it, unzip the package at ~/AndroidDev directory. The folder contains two folders: sdk and eclipse.

You could launch the Eclipse and install other SDK versions. Here is an example: donwloadSDK

• Download NDK. Here is the [download link|https://developer.android.com/tools/sdk/ndk/index.html]]. You could always prefer the latest version. When we are writing this article, the latest version of NDK is r9d.

After downloading it, unzip the package at the same location of the Android SDK. In our case, it is under the ~/AndroidDev directory.

Verify Your Environment

Aha, we have installed all the required softwares. Let’s do the final verification.

At first, we should verify that python 2.7 is installed and it is accessible under the current user’s environment which means you could type python --version in your Terminal(or Command Line on win32) and it will give you the following result:

-> % python --version
Python 2.7.5
If there is a prompt like “command not found: python” which means your python environment is not correct, you should install it. We recommend you install python with homebrew.

brew install python
If the homebrew isn’t installed on your system, please refer to this link for more information.

At last, let’s install ant tools. If you are a homebrew user, you could simply type the following command in your terminal to install ant:

brew install ant

Time in Action - Step By Step Guides

Configure Andriod development environment is really tough but worth it, isn’t it?

Without any further ado, let’s rock!

Use setup.py to configure your android development environment

At first, open your Termial and cd to ~/cocos2d-x.

If you type ls command, it will show you all the files.

Now, type python setup.py and you will get the following results:

It added the COCOS2D_CONSOLE_ROOT environment variable to point to the bin directory under ~/cocos2d-x/tools/cocos2d-console directory.

And then it looked for an NDK_ROOT environment variable. If you haven’t configured this environment before, it will prompts you the environment variable is not found and you should enter the path of your NDK.

In our case, we could input /Users/guanghui/AndroidDev/android-ndk-r9d/.

Caution: You must expand the ~ sign to your own user directory path. Otherwise, the scripts will fail due to error path value.

Here is the screenshot:

Now it’s time to repeat the last procee to configure the ANDROID_SDK_ROOT. You can simply input /Users/guanghui/AndroidDev/adt-bundle-mac-x86_64-20130522/sdk/. The adt-bundle-mac-x86_64-xxxx, the xxxx number maybe different. So please note this non-trival difference.

If you don’t install ant program, you should install ant first.

After you have installed ant, when the scripts ask you to config the ANT_ROOT, you can simply hit Enter key and let the scripts do the remaining job for you.

If all the environment variables are correctly configured, you should let them take effect.

On *nix systems, you could issue the following commands:

source ~/.bash_profile

on win32 system, you can just close the command line windows and restart it.

Use android-build.py to build cocos2d-x samples

Now it’s time to compile the built-in samples of cocos2d-x.

At first, you should change your directory to the where the android-build.py scripts lays.

cd build
and then

python android-build.py -p 10 cpp-tests
Bang! Hit enter and the scripts will handle all the remaining things for you.

Let’s over all the parameters to android-build.py.

If you only type python android-build.py in the Terminal, it will give you the following result:

Please read the help information carefully when this is your first time trying to build cocos2d-x.

If all things are going well, you will get the following meesage:

How to deploy it on your Android phone via command line

Now it’s time to test on your Android phone.

At first, you should enable USB Debugging on your phone and then connect your phone via an USB line.

At first, change your directory to the the bin directory of testcpp android project:

cd ~/cocos2d-x/tests/cpp-tests/proj.android/bin

(Note:If your current directory is build, you could use some relative path like thiscd …/tests/cpp-tests/proj.android/bin)

Then you could use adb to install the apk to your android phone:

adb install TestsDemo-debug.apk

If it prompts you the adb is not a command, then you could run the following commands in your Terminal or add this code line into your ~/.bashrc file.

export PATH=$PATH:$ANDROID_SDK_ROOT/tools:$ANDROID_SDK_ROOT/platform-tools
If it gives you the following screenshot, congratulations, it’s done!

Troubleshootings

• After configuring the setup.py file, you still suffer NDK_ROOT not found issue, you maybe miss sourcing the ~/.bash_profile file.

• If you are on Windows pc, you should be careful about the difference of the filesystem conventions.

In Summary

In this article, we use the MacOS system as our development environment. But it should work well on other platform.

If you are create a new project with cocos2d-console, you should try this documentation for more help to get it run on your Android phone.

If you have any problems, please post it on the forum.

python android-build.py -p 10 cpp-tests
get the following result,why?

it prompts you the export is not a command，why

@JLee___ Did you download “Ant” and add it to enviroment?

@yuye yeah

@JLee___

I am a windows user,
It showed me same error when I used cmd.
But, I tried it with cygwin(though it should have worked without it, as it is v3.0RC2)
It didn’t show me those errors, but it started compiling the cpp files(as in ver 2.2.2)
and then it finally failed after sometime stating few errors, which were not expected.

Hi YUYE! Thank you for your work! It was useful.

And I have a question
Why install the python and the ant, when they come with the NDK? Or their version from the NDK is not working properly?

@catch_up I’ll check it again tomorrow in windows.

@KeyLimeJam

thank u for focus on my tutorials.

I’am sorry,can u tell me what does

“when they come with the NDK?” 's mean.

I’am not sure what’s your problem , so if it is possible. u can post a error picture to here. I think i’ll be clear for me to help u .

thank u again

@yuye

Thank you for your support…If you want to look up to my steps:
Here are they and problems while setting up for android on windows:

1)I already had pre-configured for ANDROID_SDK_ROOT, NDK_ROOT, since cocos2d-x v2.2.2
2)I downloaded latest Cocos2d-x 3.0rc2, unzipped it
3)In cmd, where setup.py is present, I run the command python setup.py …where python v2.7.6
4) After few sec, it says, ANT-path not found, give the path.
5)So, instead of giving path here, I set its path in environment variables.
6)I restarted the cmd, and again, I put the same command.

7. Now, it shows me this:

cocos console root found
ndk_root is found
android_sdk_root is found
ant_root is found

Please restart the terminal or restart the computer to make added system variable
take effect

8)I restarted the PC several times, then again it showed me the same thing.
9)I ignored it this time, and continued with:
cd build
python android-build.py -p 10 cpp-tests

10)Then, build failed giving the error as stated by JLee, everytime, I ran this command.
11)Finally, I switched to cygwin(although cocos2d-x v3.0rc must work without it), I ran same commands, it proceeded by compiling the cpp files, as it used to do in v2.2.2, and then again it failed giving unexpected errors.

@yuye

I was trying a bit more today. I hope, these problems will help you to address our problems in a better way.

1)Already set the path variables, as mentioned in earlier post.
2) This time, I put the commands once again, BUT IN CMD(“ADMIN MODE”), otherwise, it gives errors same as mentioned by @JLee__ … in first post.
3) went to cocos2d-x3.0rc2 root, run python setup.py
4)It gave me same thing: Restart the PC for changes in environment variables to take effect, even though I’ve restarted it many time.
5)Ignoring this fault, I moved on to cd build,and run python android-build.py cpp-tests -p 10
6) It says, BUILD FAILED, stating few errors along with this one: JAVA_HOME is not pointing to jdk, it also said that it is currently set to c:/…/jre7

7. So, I changed the environment variables, thus creating new path JAVA_HOME, setting to jdk C:/…/jdk1.7.0_25

8)This time also BUILD FAILED but, it gave me same previous errors but not of JAVA_HOME.
NOTE: these are the same errors as throws, when I was following the same steps by running cygwin(both with and without ADMIN mode), as mentioned in my previous post

ERRORS are attached below

Why not regenerate samples with ‘cocos new’ script command?
Then users could use ‘cocos run’. This is much easier than the current path which is totally unfriendly to newbies.

@catch_up ok I’ll checking it for you

I would like to give you a BIG KISS! it’s really helpful, I have spent two days to struggle and google how to install it.

@yuye

Hi, I tried the same things with latest cocos2d-x v 3.0
It actually worked.
I ran it on AVD launched from eclipse(AVD-API 10 and AVD-API 15 one by one)

*****But few things were confusing:

1. While it was compiling, I found somewhere in cmd, that it was doing it for API 10, which is actually the min. req for cocos2d-x v3.0
2. For AVD-API 10, the app actually actually crashed-I don’t know why!!!, but for AVD-API-15 it worked fine. Also interestingly, the frame rate, went from ~35 to ~73, which was surprising!!

Hi all,
After struggling with the precompiled Android sample code, which always crashed on the device I tried ’ python android-build.py -p 10 cpp-tests’ on my Mac. I kept getting:

make: /Applications/Android/android-ndk-r9c/toolchains/arm-linux-androideabi-4.8/prebuilt/darwin-x86/bin/arm-linux-androideabi-g++: No such file or directory

So I renamed/duplicated linux-x86_64 to darwin-86 in my NDK file structure.

Now I’m getting:

[armeabi] Compile++ thumb: cpp_tests_shared <= main.cpp
/Applications/Android/android-ndk-r9c/toolchains/arm-linux-androideabi-4.8/prebuilt/darwin-x86/bin/arm-linux-androideabi-g++: /Applications/Android/android-ndk-r9c/toolchains/arm-linux-androideabi-4.8/prebuilt/darwin-x86/bin/arm-linux-androideabi-g++: cannot execute binary file
make: *** [obj/local/armeabi/objs/cpp_tests_shared/main.o] Error 126
make: *** Waiting for unfinished jobs…
Build dynamic library for project [ /Users/admin/Documents/cocos2d-x-3.0/build/…/tests/cpp-tests/proj.android ] fails!

I ran setup and configured everything but Ant.

Any help will be appreciated.

Ok, egg on my face: I didn’t download the darwin NDK.

@dotsquid I think so. I’ll tell the engine team

@catch_up It just can run in real device

@batymahn u can not use build_native
you must use command line with
cocos run -p android