The build instructions should differ only minimally between operating systems. It might be possible to build through QtCreator, but I've no idea how to do so (see below)

+

The build instructions should differ only minimally between operating systems.

+

+

The Android SDK Platform / Emulator image for '''API 15''' is the earliest that supports OpenGL ES 2 (it also supports hardware acceleration using the host OS' GPU, which is nice). Prior SDKs will '''not''' work; to test with earlier versions of Android OS, you must use a physical device. Necessitas' SDK is currently out-of-date and doesn't have API Level 15, so you'll need to download it separately if you do want to use emulation.

== Prerequisites ==

== Prerequisites ==

Line 5:

Line 7:

=== All ===

=== All ===

#[https://sourceforge.net/p/necessitas/home/necessitas/ Necessitas] (the Qt port for Android). The necessitas package includes the Android SDK and NDK, QtCreator, and the Qt libraries

#[https://sourceforge.net/p/necessitas/home/necessitas/ Necessitas] (the Qt port for Android). The necessitas package includes the Android SDK and NDK, QtCreator, and the Qt libraries

−

#*API 11 is the current target, so you may want to install that (it may be wise for us to target 10 or an earlier one, however); if using another target, be sure to comment out the bits of the necessitas Java code that aren't applicable (they're prefixed by //@ANDROID-XX; it looks like necessitas QtCreator is supposed to treat these as preprocessor directives)

+

#*API 8 is the current target, so be sure it's installed (the installer checks it be default); this is the lowest API level that support Open GL ES 2

#*If you have JRE installed, the JAVA_HOME environment variable may be pointing at that instead of the JDK; you need this to point to the JDK root directory for <code>ant</code> to work properly

#*If you have JRE installed, the JAVA_HOME environment variable may be pointing at that instead of the JDK; you need this to point to the JDK root directory for <code>ant</code> to work properly

Line 34:

Line 36:

== Build ==

== Build ==

−

−

I'm using build scripts based on QGIS' Android port from Marco Bernasocchi. These will make sure the build environment is set up correctly, that everything is set up for cross-compiling instead of compiling for your system, that the files all end up in the right places, and that the apk is built from those files. You can do all of this manually, but it's a considerably larger amount of typing than is required to build for the other platforms.

=== Configure ===

=== Configure ===

−

Within the <code>stellarium/android/util</code> directory, copy <code>config.templ</code> to <code>config.conf</code>, and edit according to the instructions within.

+

Create a subdirectory <code>builds</code> inside the directory where you synced to, and another subdirectory <code>android</code> inside that, so that you've got

−

=== Build ===

+

stellarium/builds/android/

−

Open up a terminal, head into the <code>stellarium/android/util</code> directory, and run

+

inside the <code>builds/android</code> directory, you'll want to run cmake, passing in the path to the Android toolchain so that it sets up for cross-compiling instead of compiling Stellarium for your own system. You also need to export an environment variable for the location of the NDK. The following commands will do that (replace the path in the export with the path of the ndk on your system):

Assuming you configured the config.conf correctly, Stellarium should build without a hitch.

+

But cmake will fail. The error message may mention something that's not in your PATH. Follow the onscreen instructions. To add to your path (temporarily; doing it permanently varies according to the OS), use the following command in the terminal window:

−

=== Deploy to device ===

+

export PATH=/path/to/some/directory:$PATH

−

This is a necessary step to test Stellarium, as the Android emulator lacks OpenGL ES 2 support and will crash very quickly. Get the Android device connected to your computer by USB and make sure the adb drivers are installed (may be automatic, but it varies according to device), or use [http://www.appbrain.com/app/adbwireless-(widget-version)/siir.es.adbWireless adbWireless] to connect over wifi. Once you've connected and got adb working, run:

+

Otherwise, the problem is that you need to configure cmake properly; the default values are for paths on my own system, you'll need to configure them. To configure cmake, either run

−

./install-apk.sh

+

ccmake

−

./run-apk.sh

+

−

to install, then run the apk, or:

+

in place of <code>cmake</code> in the above command, or edit the <code>CMakeCache.txt</code> file directly in any text editor. The most important Android-specific parameters are (some will be set by default unless you first built in that directory without the toolchain):

−

./build-run-apk.sh

+

* OPENGL_MODE

+

** Set to ES2 for Android devices

+

* BUILD_STATIC_PLUGINS

+

** Currently should be set to 0 as not all plugins support OpenGL ES2

+

* GUI_MODE

+

** Mobile

+

** You can also use <code>Desktop</code> to use the Desktop UI, if you so choose. The Mobile GUI is a work in progress.

+

* NECESSITAS_QT_ROOT

+

** Set this to the path to necessitas' Qt libraries; on Windows, this is normally <code>necessitas/Android/Qt/480</code>

+

* ARM_TARGET

+

** "armeabi-v7a", "armeabi-v7a with NEON", "armeabi-v7a with VFPV3", or "armeabi"

+

*** armeabi is the slowest and most compatible (ARMv5 and greater)

+

*** armeabi-v7a is faster, and will work on most devices released in the past few years, and maybe all devices that are even capable of running Stellarium (ARMv7 and greater)

+

*** "armeabi-v7a with VFPV3" enables VFPV3-D16 support, which ''should'' be compatible with every ARMv7a device. We may want to test this to see if that's true and whether there's a performance benefit

+

*** "armeabi-v7a with NEON" enables NEON and VFPV3 instructions. NEON is a SIMD instruction set that must be specifically programmed for (there is a compiler option to auto-vectorize code to work with NEON, but that would completely rule out compatibility with devices that don't have NEON, and may have negligible benefit [http://wiki.debian.org/ArmHardFloatPort/VfpComparison#NEON])

+

** I'm thinking the best idea will be compile "armeabi" and "armeabi-v7 with VFPV3", as this should allow pretty good compatibility. NDK allows libraries for different EABIs to coexist in the same package, and will choose the appropriate one for the device.

+

* ANDROID_API_LEVEL

+

** leave it at default (android-8); this is the lowest API we can use, so using this allows the greatest compatibility. Because we're using Qt, it's unlikely we'll need the extra features the higher levels give us

−

To quickly rebuild/install/run it.

+

=== Build and deploy ===

+

+

Once all the parameters are set up, run cmake again. It should succeed this time. Now, we want to build a debug apk without assets (see [[Android port]]; even if you wanted to include assets in the apk, they can't currently be used). Run:

+

+

make install

+

make build_apk_debug_no_assets

+

+

This will create the apk.

+

+

Copy <code>builds/android/Stellarium-apk/share/stellarium</code> to the root of your device's external storage (i.e. to <code>/sdcard/stellarium</code>). If external storage isn't at /sdcard on the device, you need to create a symlink to wherever external storage is at. If you rebuild Stellarium but don't change the assets or translation files, you won't need to recopy this directory; otherwise, you will.

+

+

To install the APK, either copy it to the device and install, or:

+

+

make deploy_debug_apk

+

+

And to run it, either hit the icon (it's currently a Q without a label; <small>this is owing to lazyness, the fix isn't difficult</small>), or run

+

+

make run_apk

+

+

== Want to contribute, or having problems building? ==

+

+

See: [[Android_port#Communication]]. Pop into IRC and let me know, or toss out an email to the mailing list.

+

+

== Troubleshooting Stellarium ==

+

+

If something goes wrong: The log file will be present at <code>/data/data/org.stellarium.stellarium/files/.stellarium/log.txt</code> (you can't view this on most devices without root) or ''possibly'' at <code>/sdcard/stellarium/log.txt</code> (will eventually change it so it ''always'' ends up here to avoid the root requirement). This will hopefully have information on what happened.

+

+

If it crashed before creating the log, or if the log doesn't contain anything useful, try running logcat through adb on your PC while you run the app on the device:

+

+

adb logcat

+

+

If ''that'' doesn't help, it's time for debugging:

== Debug (C++) ==

== Debug (C++) ==

=== Debug with gdb ===

=== Debug with gdb ===

−

(incomplete)

+

('''Note''': there's now an ndk-debug.sh script in <code>stellarium/android/util</code> which handles most of this; I'll have to remember to rewrite this section)

−

(also, should write our own version of the ndk-gdb script to automate some of this)

+

If you need to debug as soon as the native code starts, import the project into Eclipse as described below, and set a breakpoint right before the necessitas code starts up the native side of the app. This line in <code>QtActivity.java</code> should do the trick:

If you need to debug as soon as the native code starts, import the project into Eclipse as described below, and set a breakpoint right before the necessitas code starts up the native side of the app. This line in <code>QtActivity.java</code> should do the trick:

Line 72:

Line 119:

QtApplication.setQtActivityDelegate(qtLoader);

QtApplication.setQtActivityDelegate(qtLoader);

−

Now, on the device (or, do it on your workstation by prefixing these commands with "adb shell"):

+

With the device attached to adb (test with <code>adb devices</code>):

−

Find the process ID for Stellarium.

+

Find the process ID for Stellarium:

−

ps | grep stellarium

+

adb shell ps | grep stellarium

−

Then attach gdbserver to it

+

Then attach gdbserver to it:

−

gdbserver :5039 --attach ''pid''

+

adb shell gdbserver :5039 --attach ''pid''

−

On your workstation, have ADB forward port from the device

+

Have ADB forward that port from the device:

adb forward tcp:5039 tcp:5039

adb forward tcp:5039 tcp:5039

−

Now, I have the feeling that the build process doesn't strip symbols from debug executables (if we'd used ndk-build, it would), so you likely don't have to give gdb an unstripped version of the library. However, the downside is that the library is enormous... then again, it's probably dwarfed by the size of the supporting files, so no biggie.

+

Pull the app process off the device; this process starts and runs Android apps, so it's the process you're going to be debugging. gdb needs this.

−

Pull the app process off the device; this is the process starts and runs Android apps, so gdb is going to need it.

+

'''Windows Note:''' MinGW will interpret the paths in the <code>pull</code> commands below as ''Windows paths'' and passes them to adb accordingly (<code>/system/bin/app_process</code> becomes <code>C:\system\bin\app_process</code>). They're supposed to be paths on the Android device though, not your system. Either use <code>cmd</code>, or type the paths as <code>//system/bin/app_process</code>

Open gdb, which should reside somewhere in the android ndk or sdk directories (figure out where).

+

Open gdb, which should reside somewhere in the android ndk directory (in Windows, it's under <code>necessitas/android-ndk-r6b/toolchains/arm-linux-androideabi-4.4.3/prebuilt/windows/bin</code>)

−

Tell gdb where your source is

+

Tell gdb where your source is:

directory path/to/source

directory path/to/source

−

Tell gdb that it's looking at an app_process process

+

Give gdb the executable that it's going to be debugging, the app_process binary you downloaded from the device:

−

file app_process

+

file path/to/app_process

−

And give it the location of libstellarium.so so it can find it

+

And give it the locations of libstellarium.so, libc.so, and any other libraries so it can find them (you can run the command multiple times, it will add each directory to the search path):

−

set solib-search-path /path/to/lib

+

set solib-search-path /path/to/lib/directory

Instructions on using gdb are beyond the scope of this document. You're on your own.

Instructions on using gdb are beyond the scope of this document. You're on your own.

Now you should be able to resume in Eclipse and in gdb, and debug as usual.

Now you should be able to resume in Eclipse and in gdb, and debug as usual.

+

+

It should be possible to hook gdb into Eclipse or QtCreator to allow GUI debugging. May want to investigate that at some point. It'll probably be handy to have a script do most of the setup for this use.

=== Debug with QtCreator ===

=== Debug with QtCreator ===

−

I haven't the foggiest. If anyone wants to investigate this, please go right ahead :)

==== To import the project into QtCreator ====

==== To import the project into QtCreator ====

−

Run the <code>necessitas-qtcreator.sh</code> script. This will start necessitas' QtCreator.

+

If you don't have the environment variables saved on your account, start necessitas' QtCreator in a terminal window that does. On Windows, you ''must'' start QtCreator for a MinGW shell, otherwise it won't detect the MinGW cmake generator and you'll be quite stuck.

+

+

In QtCreator, open the CMakeLists.txt in the root of the directory where you've checked out Stellarium. In the following windows, choose "MinGW Makefiles" or "Unix Makefiles" as the generator, put in any cmake commands you need (the toolchain one from above may be all), and run it. If it fails, look in the directory it's created and edit the <code>CMakeCache.txt</code> as described above.

+

+

(I can't get the MinGW Generator to work on Windows, even though it's the only option QtCreator gives. Passing in <code>-G"Unix Makefiles"</code> appears to work)

−

Edit the <code>build-stel.sh</code> script, uncommenting the lines to echo the cmake flags and then exit. Run it, saving the cmake flags out to a file (<code>./build-stel.sh > flags.out</code>). Copy the flags.

+

To get it to build, deploy, and run the code, you can just add build commands to the project as described above (<code>make install</code>, ...)

−

In QtCreator, open the CMakeLists.txt in the root of the directory where you've checked out Stellarium. In the following windows, choose "MinGW Makefiles" or "Unix Makefiles" as the generator, paste the flags into the cmake arguments box, and click "Run cmake". Proceed, and you should be done.

+

==== Debugging ====

−

However, when you try to run or debug the app, it builds the code and then does nothing with it. Not sure how to resolve that, or how to get it to attach to a process on a device. QtCreator is still a very nice IDE for editing the code, though.

+

To have it actually debug the code is not straight-forward. You need to 'trick' Necessitas' QtCreator into working for you, and even then it probably won't work well:

+

* create an empty Android project

+

* clear out all of the build steps, but leave the deploy/running/debugging steps

+

* copy in the binaries you built using the project you imported above, or symlink to the build directory or something

+

* run it (using an actual device ''or'' and Android-15 target)

== Debug (Java) ==

== Debug (Java) ==

−

There is some Java code here, but thanks to necessitas it should be kept to a minimum (aside from localization and bits from necessitas itself).

+

There is some Java code here, but thanks to necessitas it should be kept to a minimum.

=== Debug with Eclipse ===

=== Debug with Eclipse ===

Revision as of 08:58, 22 April 2012

The build instructions should differ only minimally between operating systems.

The Android SDK Platform / Emulator image for API 15 is the earliest that supports OpenGL ES 2 (it also supports hardware acceleration using the host OS' GPU, which is nice). Prior SDKs will not work; to test with earlier versions of Android OS, you must use a physical device. Necessitas' SDK is currently out-of-date and doesn't have API Level 15, so you'll need to download it separately if you do want to use emulation.

Sync to experimental Android branch

More instructions for using Bazaar and Launchpad can be found in the Bazaar and Launchpad documentation.

Build

Configure

Create a subdirectory builds inside the directory where you synced to, and another subdirectory android inside that, so that you've got

stellarium/builds/android/

inside the builds/android directory, you'll want to run cmake, passing in the path to the Android toolchain so that it sets up for cross-compiling instead of compiling Stellarium for your own system. You also need to export an environment variable for the location of the NDK. The following commands will do that (replace the path in the export with the path of the ndk on your system):

But cmake will fail. The error message may mention something that's not in your PATH. Follow the onscreen instructions. To add to your path (temporarily; doing it permanently varies according to the OS), use the following command in the terminal window:

export PATH=/path/to/some/directory:$PATH

Otherwise, the problem is that you need to configure cmake properly; the default values are for paths on my own system, you'll need to configure them. To configure cmake, either run

ccmake

in place of cmake in the above command, or edit the CMakeCache.txt file directly in any text editor. The most important Android-specific parameters are (some will be set by default unless you first built in that directory without the toolchain):

OPENGL_MODE

Set to ES2 for Android devices

BUILD_STATIC_PLUGINS

Currently should be set to 0 as not all plugins support OpenGL ES2

GUI_MODE

Mobile

You can also use Desktop to use the Desktop UI, if you so choose. The Mobile GUI is a work in progress.

NECESSITAS_QT_ROOT

Set this to the path to necessitas' Qt libraries; on Windows, this is normally necessitas/Android/Qt/480

ARM_TARGET

"armeabi-v7a", "armeabi-v7a with NEON", "armeabi-v7a with VFPV3", or "armeabi"

armeabi is the slowest and most compatible (ARMv5 and greater)

armeabi-v7a is faster, and will work on most devices released in the past few years, and maybe all devices that are even capable of running Stellarium (ARMv7 and greater)

"armeabi-v7a with VFPV3" enables VFPV3-D16 support, which should be compatible with every ARMv7a device. We may want to test this to see if that's true and whether there's a performance benefit

"armeabi-v7a with NEON" enables NEON and VFPV3 instructions. NEON is a SIMD instruction set that must be specifically programmed for (there is a compiler option to auto-vectorize code to work with NEON, but that would completely rule out compatibility with devices that don't have NEON, and may have negligible benefit [1])

I'm thinking the best idea will be compile "armeabi" and "armeabi-v7 with VFPV3", as this should allow pretty good compatibility. NDK allows libraries for different EABIs to coexist in the same package, and will choose the appropriate one for the device.

ANDROID_API_LEVEL

leave it at default (android-8); this is the lowest API we can use, so using this allows the greatest compatibility. Because we're using Qt, it's unlikely we'll need the extra features the higher levels give us

Build and deploy

Once all the parameters are set up, run cmake again. It should succeed this time. Now, we want to build a debug apk without assets (see Android port; even if you wanted to include assets in the apk, they can't currently be used). Run:

make install
make build_apk_debug_no_assets

This will create the apk.

Copy builds/android/Stellarium-apk/share/stellarium to the root of your device's external storage (i.e. to /sdcard/stellarium). If external storage isn't at /sdcard on the device, you need to create a symlink to wherever external storage is at. If you rebuild Stellarium but don't change the assets or translation files, you won't need to recopy this directory; otherwise, you will.

To install the APK, either copy it to the device and install, or:

make deploy_debug_apk

And to run it, either hit the icon (it's currently a Q without a label; this is owing to lazyness, the fix isn't difficult), or run

make run_apk

Want to contribute, or having problems building?

Troubleshooting Stellarium

If something goes wrong: The log file will be present at /data/data/org.stellarium.stellarium/files/.stellarium/log.txt (you can't view this on most devices without root) or possibly at /sdcard/stellarium/log.txt (will eventually change it so it always ends up here to avoid the root requirement). This will hopefully have information on what happened.

If it crashed before creating the log, or if the log doesn't contain anything useful, try running logcat through adb on your PC while you run the app on the device:

adb logcat

If that doesn't help, it's time for debugging:

Debug (C++)

Debug with gdb

(Note: there's now an ndk-debug.sh script in stellarium/android/util which handles most of this; I'll have to remember to rewrite this section)

If you need to debug as soon as the native code starts, import the project into Eclipse as described below, and set a breakpoint right before the necessitas code starts up the native side of the app. This line in QtActivity.java should do the trick:

QtApplication.setQtActivityDelegate(qtLoader);

With the device attached to adb (test with adb devices):

Find the process ID for Stellarium:

adb shell ps | grep stellarium

Then attach gdbserver to it:

adb shell gdbserver :5039 --attach pid

Have ADB forward that port from the device:

adb forward tcp:5039 tcp:5039

Pull the app process off the device; this process starts and runs Android apps, so it's the process you're going to be debugging. gdb needs this.

Windows Note: MinGW will interpret the paths in the pull commands below as Windows paths and passes them to adb accordingly (/system/bin/app_process becomes C:\system\bin\app_process). They're supposed to be paths on the Android device though, not your system. Either use cmd, or type the paths as //system/bin/app_process

Open gdb, which should reside somewhere in the android ndk directory (in Windows, it's under necessitas/android-ndk-r6b/toolchains/arm-linux-androideabi-4.4.3/prebuilt/windows/bin)

Tell gdb where your source is:

directory path/to/source

Give gdb the executable that it's going to be debugging, the app_process binary you downloaded from the device:

file path/to/app_process

And give it the locations of libstellarium.so, libc.so, and any other libraries so it can find them (you can run the command multiple times, it will add each directory to the search path):

set solib-search-path /path/to/lib/directory

Instructions on using gdb are beyond the scope of this document. You're on your own.

Now you should be able to resume in Eclipse and in gdb, and debug as usual.

It should be possible to hook gdb into Eclipse or QtCreator to allow GUI debugging. May want to investigate that at some point. It'll probably be handy to have a script do most of the setup for this use.

Debug with QtCreator

To import the project into QtCreator

If you don't have the environment variables saved on your account, start necessitas' QtCreator in a terminal window that does. On Windows, you must start QtCreator for a MinGW shell, otherwise it won't detect the MinGW cmake generator and you'll be quite stuck.

In QtCreator, open the CMakeLists.txt in the root of the directory where you've checked out Stellarium. In the following windows, choose "MinGW Makefiles" or "Unix Makefiles" as the generator, put in any cmake commands you need (the toolchain one from above may be all), and run it. If it fails, look in the directory it's created and edit the CMakeCache.txt as described above.

(I can't get the MinGW Generator to work on Windows, even though it's the only option QtCreator gives. Passing in -G"Unix Makefiles" appears to work)

To get it to build, deploy, and run the code, you can just add build commands to the project as described above (make install, ...)

Debugging

To have it actually debug the code is not straight-forward. You need to 'trick' Necessitas' QtCreator into working for you, and even then it probably won't work well:

create an empty Android project

clear out all of the build steps, but leave the deploy/running/debugging steps

copy in the binaries you built using the project you imported above, or symlink to the build directory or something

run it (using an actual device or and Android-15 target)

Debug (Java)

There is some Java code here, but thanks to necessitas it should be kept to a minimum.

Debug with Eclipse

Create a new project, choose Android project, and choose "Create project from existing source". Point Eclipse at the stellarium/android/java directory. Go to Project -> Properties, and set the JDK compliance level to 1.6. You can now use Eclipse to build and debug the software. If debugging, as noted above, you must use a device. Stellarium will not run in the Android emulator.