RetroShare/README-Android.asciidoc

Compile Retroshare for Android
==============================

Compiling an application for Android is not as easy as one would imagine,
expecially one like RetroShare that has a big codebase and is not well
documented. This document is aimed to empower the reader so she can hopefully
succed or at least have a significant help in compiling her own RetroShare APK
installable on Android.


== Preparing The Environement

First of all setup your Qt for Android development environement following the
guide on the link:http://doc.qt.io/qt-5/androidgs.html[Qt for android web site].
At this point you should have Android SDK, Android NDK, and Qt for Android
working fine, and you should be capable of executing on an Android emulator or
on your Android phone Qt for Android examples.

But RetroShare is not as simple to compile as those examples. The good news is
that Android NDK ships all the necessary to build a custom toolchain that is
suitable to build RetroShare.
In order to build the toolchain with needed libraries RetroShare provides the
+android-prepare-toolchain.sh+ script; before you execute it you should define
some variables the script cannot determine in an easy and reliable manner by
itself in your terminal.

[source,bash]
-------------------------------------------------------------------------------
## The path where Android NDK is installed in your system
export ANDROID_NDK_PATH="/opt/android-ndk/"

## The path where your fresh compiled toolchain will be installed, make sure
## the parent exists
export NDK_TOOLCHAIN_PATH="${HOME}/Builds/android-toolchains/retroshare-android/"

## The CPU architecture of the Android device you want to target
export ANDROID_NDK_ARCH="arm"

## The Android API level the Android device you want to target
export ANDROID_PLATFORM_VER="19"

## The number of core that yout host CPU have (just to speed up compilation) set
## it to 1 if unsure
export HOST_NUM_CPU=1

./android-prepare-toolchain.sh
-------------------------------------------------------------------------------

== Preparing Qt Creator

Now that your environement is set up you should configure Qt Creator for Android
following the
link:http://doc.qt.io/qtcreator/creator-developing-android.html[official guide].
At the end of this step your Qt Creator should recognize the Android compiler
and the Qt for Android kit.

Your Kit is now ready to use. Now you can open RetroShare as a Qt Creator
project and in the Projects left menu add the newly created kit if not already
present, so you can select it on the build type selection button down on the
left.

As we use a custom toolchain one more step is needed +

_Qt Creator left pane -> Projects -> Build and Run -> Android SOMESTUFF kit ->
Build Environement -> Add

Variable: +NATIVE_LIBS_TOOLCHAIN_PATH+
Value: +Same value as NDK_TOOLCHAIN_PATH in Preparing The Environement step+

Some of RetroShare modules like +retroshare-gui+ and +WebUI+ are not available
on Android so to be able to compile RetroShare without errors you will have to
go to +

_Qt Creator left pane -> Projects -> Build and Run -> Android SOMESTUFF kit ->
Build Steps -> qmake -> Additional arguments_

and add the following configurations

[source,makefile]
-------------------------------------------------------------------------------
CONFIG+=no_retroshare_gui CONFIG+=no_retroshare_nogui CONFIG+=no_retroshare_plugins CONFIG+=retroshare_android_service CONFIG+=libresapilocalserver CONFIG+=no_libresapihttpserver CONFIG+=retroshare_qml_app
-------------------------------------------------------------------------------

WARNING: SQLCipher is not supported yet on RetroShare for Android. This poses a
major security concern, we are working to fix this ASAP.

WARNING: Some versions of QtCreator try to find the Android SDK in
+/opt/android/sdk+. A workaround to this is to make a symbolic link there
pointing to your SDK installation path, like
+mkdir -p /opt/android/sdk && ln -s /home/user/android-sdk-linux
/opt/android/sdk+

== Quircks

On some Android devices like +Huawei ALE-L21+ background applications are
killed when screen is turned off unless they are in the _protected app_ list.
At moment seems apps developers don't have a way to have the application
_protected_ by default, unless the phone vendor decide the app is _popular_ so
the user have to enable _protection_ for RetroShare manually on those mobile
phones. +

{empty} +
To enable enable _protection_: +Android menu -> Settings -> Privacy & security 
-> Protected apps -> RetroShare+ +
{empty} +

Other devices may offer similar _features_ please report them.

== Debugging with GDB

QtCreator actually support debugging only for the foreground activity, so to
debug what's happening in the core extra trickery is needed.
First of all you need to authorize root access to applications, then once you
plug your sacrifical Android phone run this commands

.Run gdbserver as root on Android phone
[source,bash]
--------------------------------------------------------------------------------
## Open a shell from your workstation on the connected Android phone
adb shell

## take note of the PID of the RetroShare process
ps | grep retroshare

## take the note of the phone IP
ip address show

## Gain root permissions on the shell
su

## Attach with gdbserver and listen on one TCP port
gdbserver :4567 --attach $RETROSHARE_PID
--------------------------------------------------------------------------------


.Prepare and run Android NDK GDB on your workstation
[source,bash]
--------------------------------------------------------------------------------
## Extract system lib from the phone to a temporary directory on your computer
adb pull /system/lib /tmp/system_lib

## Start Android NDK GDB of your phone architecture passing the executable
/opt/android-ndk/toolchains/arm-linux-androideabi-4.9/prebuilt/linux-x86_64/bin/arm-linux-androideabi-gdb RetroShare-Android_for_armeabi_v7a_GCC_4_9_Qt_5_9_2_android_armv7-Debug/retroshare-android-service/src/libretroshare-android-service.so

## Instruct GDB how and where to find libraries
(gdb) set auto-solib-add on
(gdb) set solib-search-path /tmp/system_lib

## Connect to the gdbserver running on the phone
(gdb) target remote $PHONE_IP:4567
--------------------------------------------------------------------------------


== Furter Readings

- link:http://doc.qt.io/qt-5/android-support.html[]
- link:https://developer.android.com/ndk/guides/libs.html[]
- link:retroshare://forum?name=Compiling%20nogui%20for%20android&id=8fd22bd8f99754461e7ba1ca8a727995&msgid=4e0f92330600bba9cf978f384f4b7b2f2ca64eff[]
- link:retroshare://file?name=Android%20Native%20Development%20Kit%20Cookbook.pdf&size=29214468&hash=0123361c1b14366ce36118e82b90faf7c7b1b136[]
- link:https://groups.google.com/forum/#!topic/android-developers/srATPaL0aRU[]
- link:https://stackoverflow.com/questions/31638986/protected-apps-setting-on-huawei-phones-and-how-to-handle-it[]
- link:https://tthtlc.wordpress.com/2012/09/19/how-to-do-remote-debugging-via-gdbserver-running-inside-the-android-phone/[]
- link:https://source.android.com/devices/tech/debug/gdb[]