LiquidFun Build and Run Instructions
Building for Android

Version Requirements

Following are the minimum required versions for the tools and libraries you need for building LiquidFun for Android:

  • Android SDK: Android 2.3.3 (API Level 10)
  • ADT: 20130917
  • NDK: android-ndk-r9
  • NDK plugn for Eclipse: bundled with ADT
  • cmake (when building from source): 2.8.12.1

Before Building

Building

Each LiquidFun project for Android has an associated AndroidManifest.xml file and jni subdirectory. For samples, AndroidManifest.xml contains details about how to build an Android package (apk). For libraries, such as LiquidFun and freeglut, the AndroidManifest.xml file informs the ndk-build tool that the directory contains NDK makefiles under the jni subdirectory.

The following Android NDK projects live in the liquidfun directory tree.

  • liquidfun/Box2D - liquidfun dynamic and static libraries.
  • liquidfun/Box2D/HelloWorld - Non-interactive Hello World sample application.
  • liquidfun/Box2D/Testbed - Interactive Testbed sample application.

To build an Android NDK project:

  • Open a command line window.
  • Go to the working directory containing the project to build.
  • Execute ndk-build.

For example, to build the LiquidFun dynamic and static libraries: 

cd liquidfun/Box2D
ndk-build

Executing a Sample

Running a sample requires the Android Development Tools (ADT) plugin and the NDK Eclipse plugin.

Running an application using Eclipse:

  • Build a project using ndk-build (see above).
  • Open ADT Eclipse.
  • Select "File->Import..." from the menu.
  • Select "Android > Existing Android Code Into Workspace", and click "Next".
  • Click the "Browse..." button next to Root Directory: and select the project folder (e.g. liquidfun/Box2D/Testbed).
  • Click "Finish". Eclipse imports the project, and displays it in the Package Explorer pane.
  • Right-click the project, and select "Run->Run As->Android Application" from the menu.
  • If you do not have a physical device, you must define a virtual one. For details about how to define a virtual device, see managing avds. We don’t recommend a virtual device for development.
  • If the target is a physical device, unlock the device and observe the application executing.

Build and Run from the Command Line:

It's also possible to use build_apk.sh to build, deploy, and execute an application. build_apk.sh requires the installation of the Android NDK and Android SDK. On Windows the script requires that you install [Cygwin][], as it makes use of Bash and common UNIX utilities. In addition, build_apk.sh requires the addition of the Android SDK sdk/tools, Android SDK sdk/platform-tools and Android NDK root directories to the PATH environment variable.

To build and run an application using build_apk.sh:

  • Change into the directory containing the project to build.
  • Run build_apk.sh.

For example, the following will build the Testbed application, deploy it to the connected device, and start it: 

cd liquidfun/Box2D/Testbed
../AndroidUtil/build_apk.sh

Code Generation

By default, code is generated for devices that support the armeabi-v7a ABI. Alternatively, you can generate a fat .apk that includes code for all ABIs. To do so, override APP_ABI on ndk-build's command line: 

ndk-build APP_ABI=all

Running Unit Tests

Developers modifying the LiquidFun library can verify that it is still working correctly by executing the provided unit tests.

Use the run_tests_android.sh script to execute unit tests: 

./liquidfun/Box2D/Unittests/run_tests_android.sh

run_tests_android.sh uses build_apk.sh to build, deploy, and execute each unit test on the connected device. The "Build and Run from the Command Line" section above describes the setup requirements for build_apk.sh.