Prerequisites

All

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)

Sync to experimental Android branch

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

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. Some of the functionality from these shell scripts needs to be moved into the cmake files; ideally, you'll call cmake directly, modifying a few settings as needed, and it'll do all the rest automatically.

Configure

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

Build

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

./build-all.sh

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

Deploy to device

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 adbWireless to connect over wifi. Once you've connected and got adb working, run:

./install-apk.sh
./run-apk.sh

to install, then run the apk, or:

./build-run-apk.sh

To quickly rebuild/install/run it.

Debug (C++)

Debug with gdb

(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 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

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

To import the project into QtCreator

Run the necessitas-qtcreator.sh script. This will start necessitas' QtCreator.

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

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.

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.

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).

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.