User Tools

Site Tools


using_the_android_demo_as_a_template_for_your_own_projects

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
using_the_android_demo_as_a_template_for_your_own_projects [2018/02/14 04:46 (14 months ago)]
iarwain ↷ Links adapted because of a move operation
using_the_android_demo_as_a_template_for_your_own_projects [2019/03/04 02:06 (7 weeks ago)] (current)
sausage
Line 1: Line 1:
-   This guide is based on Android ​1.2.1.and NDK version ​r10e. +   This guide is based on Android ​Studio 3.1.and NDK version ​r17b.
-   The Android builds require GCC 4.9 which is in NDK r10e.+
  
 ====== Using the Android Demo as a template for your own projects ====== ====== Using the Android Demo as a template for your own projects ======
 +
 +<WRAP center round box 90%>
 +To decide on which Android port to use, see: [[en:​tutorials:​which_android|Which Android Port should you use?]]
 +</​WRAP>​
  
 If you have worked through [[en:​tutorials:​setup_android|Compiling orx and the Android demo]] and all compiled and deployed fine, then you are right to continue with this tutorial. ​ If you have worked through [[en:​tutorials:​setup_android|Compiling orx and the Android demo]] and all compiled and deployed fine, then you are right to continue with this tutorial. ​
Line 11: Line 14:
 ===== Copy demo as a template ===== ===== Copy demo as a template =====
  
-Depending how you structure your own project, it is likely that you have a subfolder list something like this:+Depending how you structure your own project, ​(especially if you use the [[en:​tutorials:​creating_your_own_project|init script to create your projects]]) ​it is likely that you have a folder layout ​something like this:
  
     bin     bin
Line 24: Line 27:
     src     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:+Perhaps you are targeting more than one operating system and IDE. You'​ll ​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     bin
Line 33: Line 36:
             build.gradle             build.gradle
             gradlew             gradlew
-                ​settings.gradle+            ​settings.gradle
             etc...             etc...
         windows         windows
Line 43: Line 46:
  
  
-===== Choosing the right version of Gradle ​===== +===== The Application ID =====
-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.+The Application ID notation ​is used to make Android applications (and their ownership) unique from all other applications that are available.
  
-For the latest Android Studio 1.2.1.1, it requires ​the Gradle version to be set to1.2.3 +This notation is peppered through many files in the demo project and we'll need to change all of them to make the project your ownThe notation used in the demo is:
-However, this version of Android Studio will fix this for you.+
  
-For Android Studio (Beta) 0.8.14, it requires Gradle version 0.13.++   org.orxproject.orxtest.OrxDemo
  
-In shortget the latest Android Studio+  * The ''​org.orxproject.orxtest''​ portion is called the **Package Name** and also the **Application ID**. 
- +  * The ''​OrxDemo''​ portion is the **Class Name**. 
 +  * The entire sequence which is ''​org.orxproject.orxtest.OrxDemo''​ is the **Activity**.  
 + 
 +To make this demo easier to followlet's come up with a fantasy application name and company. 
 + 
 +Imagine you owned the domain name: ''​rabbitgames.net''​ 
 +And your game was ''​Rocket Boy''​. Then a good identifier might be: 
 + 
 +   ​net.rabbitgames.rocketboy.RocketBoyGame 
 + 
 +So therefore:​ 
 + 
 +  * ''​net.rabbitgames.rocketboy''​ would be your **Package Name** and **Application ID**. 
 +  * ''​RocketBoyGame''​ would be the **Class Name**. 
 +  * ''​net.rabbitgames.rocketboy.RocketBoyGame''​ would be the **Activity**.  
 + 
 +These names do not represent anything visual in your game itself, title, or icon, etc. Those are defined elsewhere.  
 + 
 +We will apply this notation though a few files coming up. 
 + 
 +Read more about this at: https://​developer.android.com/​studio/​build/​application-id
   
-===== Naming your project and APK file ===== 
  
-Choosing a name now is important ​and will reduce the confusion later.+===== Naming Folders ​and APK file =====
  
-Edit the build/android/settings.gradle file.+The string you choose will become ​the name of the **//APK//**, for example: ''​app-debug.apk''​ and ''​app-debug-unaligned.apk''​
  
-   ​include ​':app'+Similar to the naming we discussed earlier, let's call the app: ''​rocket-boy'​'.
  
-Whtever you rename ​app to, you need to rename the build/​android/​app folder to match.+Edit the ''​build/​android/​settings.gradle''​ file and change from: 
 + 
 +   ​include ':app', ':​orx-lib'​ 
 + 
 +to
 + 
 +   ​include ':​rocket-boy'​':​orx-lib'​ 
 + 
 +Now you need to rename the folder ''​build/​android/​app'' ​folder to match so it becomes: ''​build/​android/​rocket-boy''​.
  
 When it comes time to import the project later into Android Studio, this will be the project name. 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 
  
 +===== Renaming the Folders to match the Activity Name =====
 +
 +The Activity is currently called ''​OrxDemo''​. You can see it stored under the folder structure:
 +
 +   ​build/​android/​rocket-boy/​src/​main/​java/​org/​orxproject/​orxtest/​OrxDemo.java
 +
 +Change these folder names to: 
 +
 +   ​build/​android/​rocket-boy/​src/​main/​java/​net/​rabbitgames/​rocketboy/​RocketBoyGame.java
  
  
-===== Activity Name =====+<WRAP center round box 90%> 
 +An activity is a screen, or drawable area. An Android application can have multiple activities, one stacked on another, and each removed using the back button on a device.
  
-The Activity is called OrxDemo. You can see it stored under the folder structure:+An activity ​can also show or hide a title or onscreen keyboard.
  
-org/orxproject/orxtest/​OrxDemo.java +Read more about Activities at: https://developer.android.com/​reference/​android/​app/Activity 
-(or build\android\app\src\main\java\org\orxproject\orxtest)+</​WRAP>​
  
-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:+===== Edit RocketBoyGame.java =====
  
-    * rename ​the OrxDemo.java file to the same name. +Edit the ''​RocketBoyGame.java'' ​file and change the class name to match:
-    * edit the OrxDemo.java file (or whatever you renamed it to) and change the class name to match:+
  
-   ​public class OrxDemo ​extends OrxActivity {+   ​public class RocketBoyGame ​extends OrxActivity {
         ​         ​
-Also in the OrxDemo.java ​file, change the following ​line to suit your path:+Also while in this file, change the first line to match the path:
   
-   ​package ​org.orxproject.orxtest;+   ​package ​net.rabbitgames.rocketboy;
  
  
-===== The Package Name ===== 
  
-Back in the AndroidManifest.xml ​file, you can also deal with the Package Name.+===== Edit AndroidManifest.xml ​=====
  
-The package name you choose is also very important. This allows your application to be unique once released out on the internet.+Edit ''​build/​android/​src/​main/​AndroidManifest.xml''​ file:
  
-In the AndroidManifest.xml file you'll find:+   <​activity android:name="​net.rabbitgames.rocketboy.RocketBoyGame"​
  
-   <​manifest xmlns:android="​http://​schemas.android.com/​apk/​res/​android"​ +Also in this file is the Package Name to change:
-   ​package="​org.orxproject.orxtest">​+
  
-Again, the package name follows ​the convension of:+For example, the first line in the ''​AndroidManifest.xml''​ file you'll find:
  
-org/orxproject/orxtest/+   ​package="​org.orxproject.orxtest"
  
-You also need to make the change in the build/​android/​app/​build.gradle file:+Change this to:
  
-    applicationId ​"org.orxproject.orxtest"+   ​package="net.rabbitgames.rocketboy"
  
-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 
  
  
- +===== Edit the build.gradle File =====
  
-===== Application Name =====+This file is located at ''​build/​android/​rocket-boy/​build.gradle''​.
  
-This is the title text used when you see your application icon on your device.+    applicationId "org.orxproject.orxtest"​ 
 +     
 +Change to:
  
-The App name is located at: build/​android/​app/​src/​main/​res/​values/​strings.xml +   applicationId ​"net.rabbitgames.rocketboy"
-    <string name="app_name">​OrxDemo</​string>​+
  
 +To read more about the importance of your application id: https://​developer.android.com/​studio/​build/​application-id and http://​developer.android.com/​guide/​topics/​manifest/​manifest-element.html#​package
  
  
 +
  
-===== The Module Name =====+===== Resource Strings ​=====
  
-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:+This is how to set the title text for your application icon when loaded on your device.
  
-Android.mk +The App name is located at''​build/​android/​rocket-boy/​src/​main/​res/​values/​strings.xml''​
-    LOCAL_MODULE ​   ​:= someModuleName ​   ???usually orxTest..does this relate to orxtest or can it be anything? Trying rasterBlasterReloadedModule+
  
-Application.mk +    <string name="​app_name">​OrxDemo</​string>​
-    APP_MODULES ​someModuleName+
  
-build/​android/​app/​src/​main/​java/​org/​orxproject/​orxtest/​OrxDemo.java (or whatever you named it to):+Change ​to:
  
-    ​System.loadLibrary("someModuleName");+    ​<string name="app_name">Rocket Boy</​string>​
  
  
  
-===== Extra libraries ​=====+===== The Module Name =====
  
-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:+Your application must also be given a module name. You set this name in three places, the module name must match:
  
-   ​APP_STL := stlport_static+''​build/​android/​rocket-boy/​src/​main/​jni/​Android.mk''​
  
 +    LOCAL_MODULE ​   := rocketBoyModule
  
 +''​build/​android/​rocket-boy/​src/​main/​jni/​Application.mk''​
  
-===== The initial ​.ini config file =====+    APP_MODULES ​rocketBoyModule 
 +     
 +''​build/​android/​rocket-boy/​src/​main/​java/​net/​rabbitgames/​rocketboy/​RocketBoyGame.java''​
  
-What should you name your startup ​ini file? What is the loader looking for?+    System.loadLibrary("​rocketBoyModule"​);​ 
 + 
 + 
 + 
 +===== The initial .ini config ​file =====
  
-Currently, name it orxd.ini for debug or orx.ini for release.+Orx will load its startup //ini// file from the ''​build/​android/​rocket-boy/​src/​main/​assets''​ folder.
  
-Not sure which you are compiling for? Have a look in the jni/Android.mk fileThe "​LOCAL_STATIC_LIBRARIES := orxd" line tells it is orxd (debug). In this case, go with orxd.ini.+Currently, Orx will load ''​orxd.ini''​ when in debug mode, or ''​orx.ini''​ for release mode. (Debug or release APKs are covered later).
  
-According to [[setup_android_manual|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.+Not sure which mode you are compiling for? Have a look in the ''​build/​android/​rocket-boy/​src/​main/​jni/​Android.mk'' ​file. The "​LOCAL_STATIC_LIBRARIES := orxd" line tells it is ''​orxd''​ (debug). In this case, load  ''​orxd.ini''​.
  
-Your ini file(s) should be copied into the build/android/app/src/main/assets folder.+It is possible to bootstrap a different ​//ini// file, for example: ''​rocket-boy.ini''​. However this has not been tested as part of this guide. Read about [[en:​tutorials:​changing_default_config_file|changing the default ini file here]].
  
  
-===== Which orxLib? ===== 
  
-The demo includes a orx-lib.aar ​which is located at: build/​android/​app/​aars+===== orx-lib.aar ​=====
  
-You can use this for your own orx projectsHowever if you wish to compile your own from the latest orx and choose either a release or debug version, refer back to [[en:​tutorials:​setup_android|Compiling Orx and the Android Demo Project]].+To be explainedSorry, I don't have the expertise ​to advise on this as yet.
  
  
 ===== Your Source Files ===== ===== Your Source Files =====
  
-All your source files, *.cpp and *.h should be copied into the build/​android/​app/src/jni folder.+All your source files, *.cpp and *.h should be copied into the ''​build/​android/​rocket-boy/src/main/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:+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 ''​build/​android/​rocket-boy/​src/​main/​jni/​Android.mk'' ​file:
  
-LOCAL_SRC_FILES := file01.cpp file02.cpp file03.cpp file04.cpp file05.cpp+   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 They need to be laid out on the same line due to CR/LF issues in the file, causing errors like
Line 195: Line 234:
 ===== Image and Sound files ===== ===== 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. +All your PNGs and OGGs and whatever else need to be copied into the ''​build/​android/​rocket-boy/​src/​main/​assets'' ​folder.
  
    
-===== Compiling the APK =====+===== Compiling the Project to a shared library ​=====
  
-Commandline your way to your project android folder at build/​android/​app/src.+Hidden. 
 + 
 + 
 +<hidden initialState="​invisible"​ NDK build step does not seem to be required any more.> 
 + 
 +Commandline your way to your project android folder at ''​build/​android/​rocket-boy/src/​main''​.
  
 set NDK_MODULE_PATH=<​MY_LIBS>​\orx\code (this is the orx project code folder, not your project) set NDK_MODULE_PATH=<​MY_LIBS>​\orx\code (this is the orx project code folder, not your project)
Line 207: Line 250:
    ​ndk-build    ​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+This command will build all your .cpp files into an .so library file for ''​arm64-v8a'',​ ''​armeabi-v7a'',​ ''​x86''​ and ''​x86_64'' ​CPUs. These are placed in a new libs folder located at: ''​build\android\rocket-boy\src\main\libs''​ 
 Compiled objects (that make up the final .so files) are compiled into a new obj folder. Compiled objects (that make up the final .so files) are compiled into a new obj folder.
  
 +</​hidden>​
  
-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 =====+====== Packaging with Android Studio ======
  
-Select Build / Rebuild+Load Android Studio.
  
-if you receive ​an error like:+Select the ''​Open ​an existing Android Studio project''​ option and choose your project'​s android folder, located at ''​build\android''​.
  
-   ​Unsupported method: SourceProvider.getJniDirectories(). +Gradle ​will attempt ​to build immediately.
-   The version of Gradle ​you connect ​to does not support that method.+
  
 +It might fail with an error:
 +   ​Android NDK: WARNING: Ignoring unknown import directory: /​build/​android/​rocket-boy/​src/​main/​jni/​../​../​../​../​../​../​
 +   
 +In this case, go to edit ''​\build\android\rocket-boy\src\main\jni\Android.mk''​ or expand ''​External Build Files''​ in Android Studio and edit it from there. You need to work out the relative path from ''​Android.mk''​ to the orx project'​s ''​lib/​static''​ folder. In my case it was:
  
-Android Studio will not support 0.14.0If you set this version (as supplied in the orx demo, it will ask if you want to update the versionSay yes and let it sync to the new version).+   ​$(call import-add-path,​$(LOCAL_PATH)/​../../../​../​../​../​../​../​orx/​code/​)
  
-Then try selecting Build / Rebuild again.+But yours will vary.
  
-Againchanging the version may mean lengthy gradle downloads while new library versions download in the background.+Once changedre-sync and build with: ''​File > Sync Project with Gradle Files''​
  
-If successful, there will be a new "​build"​ folder created at: build/​android/​app/​build +After this, the wrapping code for your project is complete.
-Under this will be three subfolders: generatedintermediates 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+===== Building a Debug apk =====
  
-Copy the apk your Android device. And try it out.+Select ​the ''​Build > Build APK(s)''​ menu. 
 + 
 +Locate your apk file in: ''​build\android\rocket-boy\build\outputs\apk\debug''​
  
 You are done! You are done!
 +
 +
 +===== Testing =====
 +
 +There are three ways to test your application:​
 +
 +  - Connecting a phone via USB in Developer Mode. Select ''​Run > Run '​RocketBoyGame'​ ''​ to send to the phone. You can track application progress and logs via Android Studio'​s output pane.
 +  - Select ''​Run > Run '​RocketBoyGame'​ ''​ to send to the Android Emulator.
 +  - Take the APK and manually copy it to your device.
  
  
Line 255: Line 307:
  
     1. Click View / Tool Windows / Build Variants     1. Click View / Tool Windows / Build Variants
-    2. You will see your module name: "​app"​.+    2. You will see your module name.
     3. In the next column is the build variant. Click on "​debug"​.     3. In the next column is the build variant. Click on "​debug"​.
     4. A dropdown will appear where you can choose "​release"​     4. A dropdown will appear where you can choose "​release"​
Line 263: Line 315:
 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: 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.+    1. Right clicking on the "rocket-boy" project.
     2. Click "Open Module Settings"​     2. Click "Open Module Settings"​
     3. Click the "​Signing"​ tab.     3. Click the "​Signing"​ tab.
Line 275: Line 327:
 ===== Misc Troubleshooting Tips ===== ===== 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.+  ​* General compile issues or failing APK on a phone. First thing to track down is mismatches in the naming of the project folders, and application ids, classname, etc. Go back and check each one for typos or mismatches. 
 +  ​* 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 rocket-boy.apk to rocket-boy.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.   * 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.   * 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.1518583594.txt.gz · Last modified: 2018/02/14 04:46 (14 months ago) by iarwain