Using externalNativeBuild with cocos2d-x

I’ve been working with cocos2d-x, a popular open-source game engine developed primarily for mobile platforms. It’s written in C++ and targets Android via the NDK. cocos2d-x comes with a command-line tool cocos that wraps the Android build tools in order to produce an APK.

Recently, Google removed the android command line tool in SDK Tools 25.3.0 (release notes), breaking cocos. The most straightforward solution for the time being would be to downgrade SDK Tools to 25.2.5 until a resolution is achieved.

In the meantime, Google has been working on an updated workflow for NDK projects that would seamlessly integrate native code editing and debugging in Android Studio. I thought, why not give it a try and see how well it works with cocos2d-x. It appears that it works pretty well — if you’re willing to ditch the cocos tool and use Gradle for full builds instead.

How to set this up?

Google has created a guide on how to use the new workflow here. While Android Studio 2.2 is required, I highly recommend using 2.3 — in my experience, 2.3 builds way faster than 2.2 did.

You can open up the proj.android-studio sub-directory in Android Studio. In essence, this involves creating an externalNativeBuild entry in the app-level build.gradle, and specifying the path to Android.mk. This is an example:

defaultConfig {
    applicationId "com.example.app"
    minSdkVersion 19
    targetSdkVersion 25
    versionCode 1
    versionName "1.0"

    externalNativeBuild {
        ndkBuild {
            arguments '-j' + Runtime.runtime.availableProcessors()
        }
    }

    ndk {
        abiFilters 'x86'
    }
}
...
externalNativeBuild {
    ndkBuild {
        path 'jni/Android.mk'
    }
}

The first Gradle sync will take some time as Android Studio collects the symbols that are used throughout the project (that includes all the header files used by cocos2d-x).

You can also find a complete build.gradle I used for my project here.

If everything goes well, you should see the static libraries on the left pane, and your own project files:

Benefits and Drawbacks

With the native code portion integrated into Android Studio, there are some niceties such as the ability to use the Hybrid Debugger which steps though mixed Java/C++ code. That said, Android Studio also does have decent C++ code completion support.

Nice and easy debugging. LLDB also works!

Android Studio does seem a little sluggish especially if you have tons of symbols (like in a cocos2d-x project), and builds do seem to take slightly longer especially you’re on Windows. Furthermore, due to cocos2d-x linking in too many object files at once, this causes the linking process to fail because the command line exceeds 8191 characters. A workaround would be to add APP_SHORT_COMMANDS := true to Application.mk.

Command Line Builds?

For people who need to build on a continuous integration setup, things are easy too. Just use Gradle:

./gradlew assembleDebug

This will create an APK in app/build/outputs/apk .

Conclusion

I’m pleased with the workflow and I hope the Android team will continue to improve the integration of NDK projects. Hopefully this helped someone!