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 (12 months ago)]
iarwain ↷ Links adapted because of a move operation
using_the_android_demo_as_a_template_for_your_own_projects [2019/02/19 14:05 (22 hours ago)] (current)
sausage Major overhaul
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 ​r17bIt is fully usable, but is still in progress.
-   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 ======
Line 11: Line 10:
 ===== 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 23:
     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. 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     bin
Line 33: Line 32:
             build.gradle             build.gradle
             gradlew             gradlew
-                ​settings.gradle+            ​settings.gradle
             etc...             etc...
         windows         windows
Line 43: Line 42:
  
  
-===== 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 ===== ===== Naming your project and APK file =====
Line 60: Line 48:
 Choosing a name now is important and will reduce the confusion later. Choosing a name now is important and will reduce the confusion later.
  
-Edit the build/​android/​settings.gradle file.+Edit the ''​build/​android/​settings.gradle'' ​file.
  
    ​include ':​app'​    ​include ':​app'​
  
-Whtever ​you rename app to, you need to rename the build/​android/​app folder to match.+Whatever ​you rename ​''​app''​ above 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. 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+It also becomes the name of the **//APK//**, eg: ''​app-debug.apk'' ​and ''​app-debug-unaligned.apk''​
  
  
Line 74: Line 62:
 ===== Activity Name ===== ===== Activity Name =====
  
-The Activity is called OrxDemo. You can see it stored under the folder structure:+The Activity is currently ​called OrxDemo. You can see it stored under the folder structure:
  
-org/orxproject/orxtest/​OrxDemo.java +   build/android/android-tilt/src/main/java/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:+You can change these folder names to suit your project. If you do, see that the name/path convention above matches the activity in the ''​build/​android/​app/​src/​main/​AndroidManifest.xml'' ​file:
  
    <​activity android:​name="​org.orxproject.orxtest.OrxDemo"​    <​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:+You can rename these folders and activity file contents, but ensure that whatever you name them to, ensure that you:
  
     * rename the OrxDemo.java file to the same name.     * rename the OrxDemo.java file to the same name.
Line 90: Line 77:
    ​public class OrxDemo extends OrxActivity {    ​public class OrxDemo extends OrxActivity {
         ​         ​
-Also in the OrxDemo.java file, change the following line to suit your path:+Also in the ''​OrxDemo.java'' ​file, change the following line to suit your path:
   
    ​package org.orxproject.orxtest;​    ​package org.orxproject.orxtest;​
Line 97: Line 84:
 ===== The Package Name ===== ===== The Package Name =====
  
-Back in the AndroidManifest.xml file, you can also deal with the Package Name.+Back in the ''​AndroidManifest.xml'' ​file, you can also alter 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. 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:+For example, ​the first line in the ''​AndroidManifest.xml'' ​file you'll find:
  
-   <​manifest xmlns:​android="​http://​schemas.android.com/​apk/​res/​android"​ +   ​package org.orxproject.orxtest
-   package="org.orxproject.orxtest">+
  
-Again, the package name follows the convension of:+Change this to match.
  
-org/​orxproject/​orxtest/​ +You also need to make the change in the ''​build/​android/​<YOUR APP NAME>/​build.gradle'' ​file:
- +
-You also need to make the change in the build/​android/​app/​build.gradle file:+
  
     applicationId "​org.orxproject.orxtest"​     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+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
  
  
Line 123: Line 107:
 This is the title text used when you see your application icon on your device. 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 +The App name is located at: ''​build/​android/​<YOUR APP NAME>/​src/​main/​res/​values/​strings.xml''​
-    <string name="​app_name">​OrxDemo</​string>​+
  
 +    <string name="​app_name">​OrxDemo</​string>​
  
  
Line 131: Line 115:
 ===== The Module Name ===== ===== 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:+Your application must also be given a module name. You can choose this name. In several placesthe module name must match. This is set in both the ''​Android.mk'' ​and ''​Application.mk'' ​files located in the ''​build/​android/​app/​src/main/jni folder''​:
  
 Android.mk Android.mk
-    LOCAL_MODULE ​   := someModuleName ​   ​???usually orxTest... does this relate to orxtest or can it be anything? Trying rasterBlasterReloadedModule+    LOCAL_MODULE ​   := someModuleName ​   ​(usually orxTest)
  
 Application.mk Application.mk
     APP_MODULES = someModuleName     APP_MODULES = someModuleName
  
-build/​android/​app/​src/​main/​java/​org/​orxproject/​orxtest/​OrxDemo.java (or whatever you named it to):+build/​android/​<YOUR APP NAME>/​src/​main/​java/​org/​orxproject/​orxtest/​OrxDemo.java (or whatever you named it to):
  
     System.loadLibrary("​someModuleName"​);​     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 
  
  
Line 157: Line 133:
 What should you name your startup ini file? What is the loader looking for? 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.+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.+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 [[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.+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.
  
-Your ini file(s) should be copied into the build/​android/​app/​src/​main/​assets folder.+Your ini file(s) should be copied into the ''​build/​android/​<YOUR APP NAME>/​src/​main/​assets'' ​folder.
  
  
-===== Which orxLib? =====+===== Which orxLib? ​(explain this better) ​=====
  
-The demo includes ​orx-lib.aar which is located at: build/​android/​app/aars+The demo includes ​an orx-lib.aar which is located at: build/​android/​<YOUR APP NAME>/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 [[en:​tutorials:​setup_android|Compiling Orx and the Android Demo Project]]. 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 [[en:​tutorials:​setup_android|Compiling Orx and the Android Demo Project]].
Line 175: Line 151:
 ===== 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/​<YOUR APP NAME>/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 ''​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 171:
 ===== 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/​<YOU APP NAME>/​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.+Commandline your way to your project android folder at ''​build/​android/​<YOUR APP NAME>/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 183:
    ​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\<YOUR APP NAME>\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.
  
  
-Load Android Studio+====== Packaging with Android Studio ​======
  
-Select the "​Import project (Eclipse, ADT, etc)" option and choose your project'​s android folder, located at build\android. +Load Android Studio.
-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 themStudio will ask if you want to copy them over. A nice touch.)+Select the ''​Open an existing ​Android ​Studio project''​ option ​and choose your project's android folderlocated at ''​build\android''​.
  
 +Gradle will attempt to build immediately.
  
-===== Building a Debug apk =====+It might fail with an error: 
 +   ​Android NDK: WARNING: Ignoring unknown import directory: C:/​Work/​Dev/​orx-projects/​android-tilt/​build/​android/​android-tilt/​src/​main/​jni/​../​../​../​../​../​../​ 
 +    
 +In this case, go to ''​Android.mk''​ in your text editor at ''​\build\android\<​YOUR APP NAME>​\src\main\jni''​ 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:
  
-Select Build Rebuild+   ​$(call import-add-path,​$(LOCAL_PATH)/../​../​../​../​../​../​../​../​orx/​code/​)
  
-if you receive an error like:+But yours will vary.
  
-   ​Unsupported methodSourceProvider.getJniDirectories(). +Once change, re-sync and build with''​File > Sync Project with Gradle ​Files''​
-   The version of Gradle ​you connect to does not support that method.+
  
 +After this, the wrapping code for your project is complete.
  
-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).+===== Building a Debug apk =====
  
-Then try selecting ​Build / Rebuild again.+Select the ''​Build > Build APK(s)''​ menu.
  
-Again, changing the version may mean lengthy gradle downloads while new library versions download ​in the background.+Locate your apk file in: ''​build\android\<​YOUR APP NAME>​\build\outputs\apk\debug''​
  
-If successful, there will be a new "​build"​ folder created at: build/​android/​app/​build +You are done!
-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.+===== Testing =====
  
-Locate ​your apk file inbuild\android\app\build\outputs\apk+There are three way to test your application:
  
-Copy the apk your Android ​deviceAnd try it out+  - Connecting a phone via USB in Developer Mode. Select ''​Run > Run 'Your APP Name' ''​ to send to the phone. You can track application progress and logs via Android ​Studio'​s output pane. 
- +  - Select ''​Run > Run 'Your APP Name' ''​ to send to the Android Emulator
-You are done!+  - Take the APK and manually copy it to your device.
  
  
Line 255: Line 232:
  
     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 275: Line 252:
 ===== 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 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.   * 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 (12 months ago) by iarwain