User Tools

Site Tools


using_the_android_demo_as_a_template_for_your_own_projects
 This guide is based on Android 1.2.1.1 and NDK version r10e.
 The Android builds require GCC 4.9 which is in NDK r10e.

Using the Android Demo as a template for your own projects

If you have worked through Compiling orx and the Android demo and all compiled and deployed fine, then you are right to continue with this tutorial.

That means your own application should be able to work. There are pitfalls along the way and I'll do my best to guide you through.

Copy demo as a template

Depending how you structure your own project, it is likely that you have a subfolder list something like this:

  bin
  build
      windows
          codelite
      mac
          xcode
  data
  include
  lib
  src

Perhaps you are targeting more than one operating system and IDE. We want to add the Android demo project to the build folder where it can be customised to work with your project. So copy the whole orx/code/demo/android folder to your build folder so it becomes:

  bin
  build
      android <------- here
          app/
          gradle/
          build.gradle
          gradlew
              settings.gradle
          etc...
      windows
      mac
  data
  include
  lib
  src

Choosing the right version of Gradle

At the moment, the Demo Project is set to use Gradle version 0.14.0. This may or may not work for you, depending on what version of Android Studio you are using.

The Gradle version is stored in the build/android/build.gradle file.

For the latest Android Studio 1.2.1.1, it requires the Gradle version to be set to: 1.2.3 However, this version of Android Studio will fix this for you.

For Android Studio (Beta) 0.8.14, it requires Gradle version 0.13.+.

In short, get the latest Android Studio.

Naming your project and APK file

Choosing a name now is important and will reduce the confusion later.

Edit the build/android/settings.gradle file.

 include ':app'

Whtever you rename app to, you need to rename the build/android/app folder to match.

When it comes time to import the project later into Android Studio, this will be the project name.

It also becomes the name of the APK, eg: app-debug.apk and app-debug-unaligned.apk

Activity Name

The Activity is called OrxDemo. You can see it stored under the folder structure:

org/orxproject/orxtest/OrxDemo.java (or build\android\app\src\main\java\org\orxproject\orxtest)

See that the name/paths convention above matches the activity in the build/android/app/src/main/AndroidManifest.xml file:

 <activity android:name="org.orxproject.orxtest.OrxDemo"

You can rename these folders and activity file, but ensure that whatever you name them to, ensure that you:

  • rename the OrxDemo.java file to the same name.
  • edit the OrxDemo.java file (or whatever you renamed it to) and change the class name to match:
 public class OrxDemo extends OrxActivity {
      

Also in the OrxDemo.java file, change the following line to suit your path:

 package org.orxproject.orxtest;

The Package Name

Back in the AndroidManifest.xml file, you can also deal with the Package Name.

The package name you choose is also very important. This allows your application to be unique once released out on the internet.

In the AndroidManifest.xml file you'll find:

 <manifest xmlns:android="http://schemas.android.com/apk/res/android"
 package="org.orxproject.orxtest">

Again, the package name follows the convension of:

org/orxproject/orxtest/

You also need to make the change in the build/android/app/build.gradle file:

  applicationId "org.orxproject.orxtest"

To read more: https://developer.atlassian.com/display/DOCS/Choosing+a+Package+Name and http://developer.android.com/guide/topics/manifest/manifest-element.html#package

Application Name

This is the title text used when you see your application icon on your device.

The App name is located at: build/android/app/src/main/res/values/strings.xml

  <string name="app_name">OrxDemo</string>

The Module Name

Your application must also be given a module name, and in each place, they must match. This is set in both the Android.mk and Application.mk files located in the build/android/app/src/jni folder:

Android.mk

  LOCAL_MODULE    := someModuleName    ???usually orxTest... does this relate to orxtest or can it be anything? Trying rasterBlasterReloadedModule

Application.mk

  APP_MODULES = someModuleName

build/android/app/src/main/java/org/orxproject/orxtest/OrxDemo.java (or whatever you named it to):

  System.loadLibrary("someModuleName");

Extra libraries

If you are developing in c++ and make use of other includes like <vector> or <sstream>, be sure to add the following to your Application.mk file to avoid compile errors:

 APP_STL := stlport_static

The initial .ini config file

What should you name your startup ini file? What is the loader looking for?

Currently, name it orxd.ini for debug or orx.ini for release.

Not sure which you are compiling for? Have a look in the jni/Android.mk file. The “LOCAL_STATIC_LIBRARIES := orxd” line tells it is orxd (debug). In this case, go with orxd.ini.

According to Android Manual Setup, it is possible to nominate a named *.ini file instead of orx.ini or orxd.ini. However this has not been tested as part of this guide.

Your ini file(s) should be copied into the build/android/app/src/main/assets folder.

Which orxLib?

The demo includes a orx-lib.aar which is located at: build/android/app/aars

You can use this for your own orx projects. However if you wish to compile your own from the latest orx and choose either a release or debug version, refer back to Compiling Orx and the Android Demo Project.

Your Source Files

All your source files, *.cpp and *.h should be copied into the build/android/app/src/jni folder.

Then to ensure the ndk can compile your source into a library, each source file (but not header files) will need to be listed in the jni/Android.mk file:

LOCAL_SRC_FILES := file01.cpp file02.cpp file03.cpp file04.cpp file05.cpp

They need to be laid out on the same line due to CR/LF issues in the file, causing errors like

 "*** commands commence before first target. Stop.". 

See the following regarding the issue and tips on :

generally how to resolve.

However, listing on one line makes the problem go away.

Image and Sound files

All your PNGs and OGGs and whatever else need to be copied into the build/android/app/src/main/assets folder.

Compiling the APK

Commandline your way to your project android folder at build/android/app/src.

set NDK_MODULE_PATH=<MY_LIBS>\orx\code (this is the orx project code folder, not your project)

 ndk-build

This command will build all your .cpp files into an .so library file for both armeabi-v7a and x86 CPUs. These are placed in a new libs folder located at: build\android\app\src\libs Compiled objects (that make up the final .so files) are compiled into a new obj folder.

Load Android Studio

Select the “Import project (Eclipse, ADT, etc)” option and choose your project's android folder, located at build\android. Gradle will now starting building. This could take a long time, especially the first time. The version set in build/android/build.gradle means that many required files may have to be downloaded by Android Studio.

(If it asks you to choose between Android SDKs and an SDK set in your project that points to an SDK of a previous install, best to choose Android. If there are packages in the old SDK that are missing in the new SDK, and your project needs them, Studio will ask if you want to copy them over. A nice touch.)

Building a Debug apk

Select Build / Rebuild

if you receive an error like:

 Unsupported method: SourceProvider.getJniDirectories().
 The version of Gradle you connect to does not support that method.

Android Studio will not support 0.14.0. If you set this version (as supplied in the orx demo, it will ask if you want to update the version. Say yes and let it sync to the new version).

Then try selecting Build / Rebuild again.

Again, changing the version may mean lengthy gradle downloads while new library versions download in the background.

If successful, there will be a new “build” folder created at: build/android/app/build Under this will be three subfolders: generated, intermediates and tmp. These folders contain all the information needed to create a final APK file.

Select Run / Run 'app' (this step actually builds the apk file)

Quit any emulator that tries to launch. Orx programs can't be emulated. But the APK file should be built and ready. A new subfolder called “output” should be added to the previous three subfolders.

Locate your apk file in: build\android\app\build\outputs\apk

Copy the apk your Android device. And try it out.

You are done!

Release Builds

You can switch between building a debug APK and a release one. Debug is set by default. In order to switch to the Release build type:

  1. Click View / Tool Windows / Build Variants
  2. You will see your module name: "app".
  3. In the next column is the build variant. Click on "debug".
  4. A dropdown will appear where you can choose "release"

Then “Rebuild Project”.

Before you can generate a release APK, you will need to sign it. You don't need to do this for debug APKs. You can do this by:

  1. Right clicking on the "app" project.
  2. Click "Open Module Settings"
  3. Click the "Signing" tab.
  4. Click the + sign.

Continue on, by visiting the following link: http://developer.android.com/tools/publishing/app-signing.html and scroll down to the section titled “Signing Your App in Android Studio”.

Misc Troubleshooting Tips

  • APK too small? And the lib folder is missing in your project? Did you forget to ndk-build your project before going to Android Studio? To check, rename your project.apk to project.apk.zip. OPen the zip and confirm you have a lib folder there.
  • You need to ensure that paths are correct to your images and sounds, between android and other platforms. You can use the [Resource] config option to configure multiple paths. Tutorial coming soon on pathing.
  • If you are sick of manually copying your image and sound assets, and concatenating ini files, some scripts will be published here soon that you can use in your own projects.
using_the_android_demo_as_a_template_for_your_own_projects.txt · Last modified: 2015/12/06 20:10 (18 months ago) (external edit)