cocos2d-x 3.0rc开发指南：Windows下Android环境搭建

对于刚接触 cocos2d-x 3.0rc 的朋友来说，环境搭建是至关重要的一步。本文将详细说明在 Windows 系统下搭建 Android 开发环境的具体步骤。

安装工具

1. 配置 JDK

JDK 是 Java 开发的基础环境，你可以从 JDK 下载地址 下载。本人使用的系统是 Win7 64 位版，但安装的是 JDK7 Windows X86 版。假设安装目录为 C:\Program Files (x86)\Java\jdk1.7.0_21，当然你也可以选择其他目录。

接下来设置环境变量：

• JAVA_HOME=C:\Program Files (x86)\Java\jdk1.7.0_21
• CLASSPATH=.;%JAVA_HOME%\lib;
• 在 Path 变量中增加 %JAVA_HOME%\bin;

本文假设你知道如何设置环境变量，如果不清楚，可以使用搜索引擎查找相关资料。设置完成后，打开命令提示符（CMD），输入 java -version。若出现以下提示，则表明环境变量设置成功：

C:\Users\arlin>java -version
java version "1.7.0_21"
Java(TM) SE Runtime Environment (build 1.7.0_21-b11)
Java HotSpot(TM) Client VM (build 23.21-b01, mixed mode, sharing)

2. 下载 Android SDK

Google 为 Android 开发者提供了 ADT（Android Developer Tools），其中包含了 SDK 和 Eclipse。你可以从 下载地址 下载。这里可以选择 32 位或 64 位版本，本人选择的是 32 位版，并将其解压到 d:\adt-bundle-windows-x86\ 目录，其目录结构如下：

--<adt-bundle-windows-x86>
--<eclipse>
--<sdk>
--SDK Manager.exe

3. 下载 Android NDK

Android NDK 可从 下载地址 获取，同样有 32 位和 64 位版可选。本人选择 32 位版，并将其解压到 ADT 同目录下，此时 ADT 的目录结构如下：

--<adt-bundle-windows-x86>
--<eclipse>
--<sdk>
--<android-ndk-r8e>
--SDK Manager.exe

4. 下载 ANT

ANT 用于自动构建 Android 程序，可从 下载地址 下载。本人选择的是 apache-ant-1.9.3-bin.zip，并将其解压到 ADT 目录下，此时 ADT 的目录结构如下：

--<adt-bundle-windows-x86>
--<eclipse>
--<sdk>
--<android-ndk-r8e>
--<apache-ant-1.9.3>
--SDK Manager.exe

5. 下载 Python

从 cocos2d-x 3.0 版本开始，在不同平台下创建和构建工程统一使用 Python。你可以从 下载地址 下载 Python 2.7.3 版本。经测试，使用最新版本在运行 setup.py 时可能会出现语法错误，而 2.7.3 版本则无此问题。

配置环境变量：最新版本的 Python 可以自动添加到 Path 环境变量中，但 2.7.3 版本需要手动设置。假设 Python 安装在 d:\Python27\，将该路径添加到 Path 环境变量中。在命令提示符下输入 python，若出现以下字样，则说明环境变量设置正确：

C:\Users\arlin>python
Python 2.7.3 (default, Apr 10 2012, 23:31:26) [MSC v.1500 32 bit (Intel)] on win32
Type "help", "copyright", "credits" or "license" for more information.
>>>

cocos2d-x 下载与配置

1. 下载 cocos2d-x

目前最新版本是 3.0RC，可从 下载地址 下载。下载完成后，将其解压到指定目录，例如 f:\cocos2dx\cocos2d-x-3.0rc0\。

2. 设置环境变量

cocos 工具需要以下几个环境变量，用于后续的新建工程、构建工程等操作：

• COCOS_CONSOLE_ROOT：cocos 控制台路径，用于新建、构建和发行工程。
• NDK_ROOT：NDK 根目录。
• ANDROID_SDK_ROOT：SDK 根目录。
• ANT_ROOT：ANT 根目录。

这些环境变量可以通过 cocos2d-x 根目录下的 setup.py 脚本进行配置。启动命令提示符，运行 setup.py：

F:\cocos2dx\cocos2d-x-3.0rc0>setup.py

此时，脚本会要求你提供 NDK、SDK 和 ANT 的路径，根据之前的解压路径输入即可。整个命令过程如下：

Setting up cocos2d-x...
-> Adding COCOS2D_CONSOLE_ROOT environment variable... OK
-> Added: COCOS_CONSOLE_ROOT = F:\cocos2dx\cocos2d-x-3.0rc0\tools/cocos2d-console/bin
-> Looking for NDK_ROOT envrironment variable... NOT FOUND
Please enter its path (or press Enter to skip): d:\adt-bundle-windows-x86\android-ndk-r8e
ADDED
-- Added: NDK_ROOT = d:\adt-bundle-windows-x86\android-ndk-r8e
-> Looking for ANDROID_SDK_ROOT envrironment variable... NOT FOUND
Please enter its path (or press Enter to skip): D:\adt-bundle-windows-x86\sdk
ADDED
-> Added: ANDROID_SDK_ROOT = D:\adt-bundle-windows-x86\sdk
-> Looking for ANT_ROOT envrironment variable... NOT FOUND
Please enter its path (or press Enter to skip): d:\adt-bundle-windows-x86\apache-ant-1.9.3\bin
ADDED
-> Added: ANT_ROOT = d:\adt-bundle-windows-x86\apache-ant-1.9.3\bin
Set up successfull:
COCOS_CONSOLE_ROOT was added into registry
NDK_ROOT was added into registry
ANDROID_SDK_ROOT was added into registry
ANT_ROOT was added into registry
Please restart the terminal or restart computer to make added system variables take effect

命令最后提示我们重启终端或者重启系统，以使这些环境变量生效。一般情况下，关闭命令提示符和资源管理器即可。如果后续遇到环境变量找不到的错误，直接重启系统试试。

要测试环境变量是否生效，重新打开命令提示符，输入以下命令查看：

F:\cocos2dx\cocos2d-x-3.0rc0>set NDK_ROOT
NDK_ROOT=d:\adt-bundle-windows-x86\android-ndk-r8e

F:\cocos2dx\cocos2d-x-3.0rc0>set ANT_ROOT
ANT_ROOT=d:\adt-bundle-windows-x86\apache-ant-1.9.3\bin

F:\cocos2dx\cocos2d-x-3.0rc0>set ANDROID_SDK_ROOT
ANDROID_SDK_ROOT=D:\adt-bundle-windows-x86\sdk

F:\cocos2dx\cocos2d-x-3.0rc0>set COCOS_CONSOLE_ROOT
COCOS_CONSOLE_ROOT=F:\cocos2dx\cocos2d-x-3.0rc0\tools/cocos2d-console/bin

新建和构建工程

1. 新建工程

我们使用 tools\cocos2d-console 工具来新建工程，该工具提供了以下几个功能：

• new：创建一个新的工程。
• compile：编译当前工程，生成二进制文件。
• deploy：发布程序到一个平台。
• run：编译、发布并运行程序。

我们现在只需要使用 new 功能，在命令提示符中输入 cocos new --help，可查看 new 命令的参数帮助：

usage: cocos new [-h] [-p PACKAGE_NAME] -l {cpp,lua,js} [-d DIRECTORY] [-t TEMPLATE_NAME] [--no-native] [PROJECT_NAME]

创建一个新工程

必要参数：
PROJECT_NAME 工程名

可选参数:
-h, --help            显示帮助信息
-p PACKAGE_NAME, --package PACKAGE_NAME
设置包名，如com.colin.mbgame
-l {cpp,lua,js}, --language {cpp,lua,js}
使用的主要语言，可以是：[cpp | lua | js]
-d DIRECTORY, --directory DIRECTORY
工程所在的目录
-t TEMPLATE_NAME, --template TEMPLATE_NAME
要创建的工程模板名

lua/js 工程参数:
--no-native           No native support.

现在，在命令提示符中输入以下命令来创建一个新工程：

F:\cocos2dx>cocos new mygame1 -p com.colin.mbgame -l cpp -d f:\cocos2dx\mbgame

执行上述命令后，会得到以下输出：

F:\cocos2dx>python F:\cocos2dx\cocos2d-x-3.0rc0\tools\cocos2d-console\bin\/cocos.py new mygame1 -p com.colin.mbgame -l cpp -d f:\cocos2dx\mbgame
Runing command: new
> Copy template into f:\cocos2dx\mbgame\mygame1
> Copying cocos2d-x files...
> Rename project name from 'HelloCpp' to 'mygame1'
> Replace the project name from 'HelloCpp' to 'mygame1'
> Replace the project package name from 'org.cocos2dx.hellocpp' to 'com.colin.mbgame'

这表明我们已经成功创建了一个工程。到 f:\cocos2dx\mbgame\ 目录下查看，工程目录结构如下：

--<mygame1>
--<Classes>
--<cocos2d>
--<proj.android>
--<proj.ios_mac>
--<proj.linux>
--<proj.win32>
--<Resources>
--.cocos-project.json
--CMakeLists.txt

2. 构建 Android 工程

同样使用 cocos2d-console 工具，这里使用 compile 命令。在命令提示符中输入 f:\cocos2dx\mbgame\mygame1>cocos compile --help 查看帮助：

usage: cocos compile [-h] [-s SRC_DIR] [-q] [-p PLATFORM] [-m MODE] [-j JOBS] [--ap ANDROID_PLATFORM] [--source-map]

把当前工程编译为二进制

可选参数:
-h, --help            显示帮助信息
-s SRC_DIR, --src SRC_DIR
工程根目录，比如上面应该是f:\cocos2dx\mbgame\mygame1，如果不设，就为当前目录（cmd定位到的那个目录）
-q, --quiet           less output
-p PLATFORM, --platform PLATFORM
选择一个平台 android|ios|mac|web|win32|linux
-m MODE, --mode MODE  编译模式 debug|release, 默认为debug.
-j JOBS, --jobs JOBS  并行编译，如果你有4核，可以设为4。

Android Options:
--ap ANDROID_PLATFORM
parameter for android-update.Without the parameter,the script just build dynamic library for project. Valid android-platform are:[10|11|12|13|14|15|16|17|18|19]

Web Options:
--source-map          Enable source-map

现在，在命令提示符中输入以下命令来编译 Android 工程：

F:\cocos2dx\mbgame\mygame1>cocos compile -p android -j 4

上述命令表示编译当前目录下的 Android 工程，并且可以同时进行 4 个编译任务。如果一切正常，应该可以看到编译开始。最后，如果看到以下输出，则说明编译成功：

BUILD SUCCESSFUL
Total time: 7 seconds
Move apk to F:\cocos2dx\mbgame\mygame1\bin\debug\android
build succeeded.

我们到 f:\cocos2dx\mbgame\mygame1\proj.android\bin\ 目录下，可以看到 mygame1-debug.apk，这说明构建完成。将其安装到手机上运行，感觉启动速度好像快了很多，不过也可能是心理作用。

如果在构建过程中出现以下错误：

com.sun.tools.javac.Main is not on the classpath.
Perhaps JAVA_HOME does not point to the JDK.
It is currently set to "C:/Program Files/Java/jre1.5.0_11"

遇到这种情况时，直接将 C:/Program Files/Java/jdk1.5.0_11/lib 中的 tools.jar 拷贝到 C:/Program Files/Java/jre1.5.0_11/lib 中即可。

在 Eclipse 下运行程序

还记得我们下载的 ADT 中包含了 Eclipse，现在我们将工程导入到 Eclipse 中运行。

1. 启动 Eclipse

到 d:\adt-bundle-windows-x86\eclipse 目录下找到 eclipse.exe 并启动。第一次启动时，会提示设置工作区，你可以根据自己的需求设置工作区的位置。

2. 配置 SDK 和 NDK 路径

选择 Window/Preferences 菜单项，打开选项对话框。选择 Android 结点，查看 SDK Location 是否正确，若没有值，则手动将 SDK 的根目录设置进去。接着选择 Android/NDK 结点，在 NDK Location 中输入 d:\adt-bundle-windows-x86\android-ndk-r8e。

3. 导入工程

选择 File/Import，打开导入对话框，选择 Android/Existing Android Code Into Workspace，然后点击 Next。

• 第一步，导入 libcocos2dx 工程：在 Root Directory 中输入 F:\cocos2dx\mbgame\mygame1\cocos2d\cocos\2d\platform\android\java，此时会列出 libcocos2dx 工程，点击 Finish 完成导入。
• 第二步，导入我们的工程：在 Root Directory 中输入 F:\cocos2dx\mbgame\mygame1\proj.android，此时会列出 mygame1 工程，点击 Finish 完成导入。

最后，连接手机，选择运行或调试，即可在手机上运行程序。

4. 导入工程时的常见问题及解决方法

• 未导入 libcocos2dx 工程：只导入 mygame1 工程时，编译不会出错，但运行时会出现 ClassNotFound 异常，提示找不到 org/cocos2dx/lib/Cocos2dxHelper 类。希望官方后续能提供更详细的文档。
• Build target 设置问题：由于 ADT 只包含了 android4.4 (api-19) 的版本，默认使用该版本。若将 Build target 设置为 android2.3 (api-9)，运行程序会提示 Unable to execute dex: java.nio.BufferOverflowException 错误。这是 Android SDK Build tools 的 BUG，将其升级到 19.0.3 版本即可解决。打开 SDK Manager，找到 19.0.3 的 Android SDK Build Tools 并安装。