[droid] add initial readme

docs/README.android

@@ -0,0 +1,346 @@
+TOC
+1. Introduction
+2. Installing and setting up the Android environment
+3. Getting the source code
+4. Installing the required Ubuntu packages
+5. How to compile
+6. Installing XBMC in an Android system
+7. Running and debugging XBMC in an Android system
+8. Architecture
+9. Useful Commands
+
+-----------------------------------------------------------------------------
+1. Introduction
+-----------------------------------------------------------------------------
+
+We currently recommend Ubuntu Natty (11.04) or later. Current work has been
+done here.
+
+NOTE TO NEW LINUX USERS: All lines that are prefixed with the '#'
+character are commands that need to be typed into a terminal window /
+console (similar to the command prompt for Windows). Note that the '#'
+character itself should NOT be typed as part of the command.
+
+-----------------------------------------------------------------------------
+2. Installing and setting up the Android environment
+-----------------------------------------------------------------------------
+
+To develop XBMC for Android the Android SDK and NDK are required.
+Because the Android NDK is lacking support for wide characters (wchar_t)
+which XBMC relies on for Unicode implementation, a third-party NDK
+from Crystax is being used.
+
+--------------------------------------------------------------------
+2.1. Getting the Android SDK and NDK
+--------------------------------------------------------------------
+
+To get the Android SDK, go to http://developer.android.com/sdk and
+download the latest version for your operating system. The Crystax NDK
+can be downloaded from http://www.crystax.net/en/android/ndk
+
+[NOTICE] Compiling XBMC for Android requires at least Android NDK
+         Revision 7b. Android NDK Revision 7 and earlier do not work
+         properly for our cause. The corresponding Crystax NDK version
+         is android-ndk-r7-crystax-5.
+
+After downloading the SDK and NDK extract the files contained in the
+archives to your harddisk.
+
+Make sure you have a recent JRE and JDK installed otherwise the
+Android SDK will not work.
+
+--------------------------------------------------------------------
+2.2. Installing Android SDK packages
+--------------------------------------------------------------------
+
+After having extracted the Android SDK to <android-sdk> you need to
+install some android packages using the Android SDK Manager:
+
+   # cd <android-sdk>/tools
+   # android &
+
+Install at least the following packages:
+  - Tools
+    - Android SDK Tools
+    - Android SDK Platform-tools
+  - Android 2.3.3 (API 10)
+    - SDK Platform
+
+--------------------------------------------------------------------
+2.3. Creating an Android Virtual Device
+--------------------------------------------------------------------
+
+In the Android SDK Manager (see 2.2) go to Tools -> Manage AVDs...
+to open the Android Virtual Device Manager. Click on "New..." to
+create a new Android Virtual Device (AVD). Enter a name (<avd-name>)
+and select "Android 2.3.3 - API Level 10" as the Target. For the
+"SD Card Size" choose at least 512 MB. In the "Hardware" part specify
+at least "256" MB for "Device ram size". Click on "Create AVD" to
+create your AVD.
+
+--------------------------------------------------------------------
+2.4. Setup the Android toolchain
+--------------------------------------------------------------------
+
+To be able to compile XBMC and the libraries it depends on for the
+Android platform you first need to setup an Android toolchain using
+the Android NDK which you earlier extracted to <android-ndk>.
+
+   # cd <android-ndk>
+   # ls platforms
+   # cd build/tools
+   # ./make-standalone-toolchain.sh --ndk-dir=<android-ndk> \
+     --platform=android-<x> --install-dir=<android-toolchain>/android-<x>
+
+The output of "ls platforms" gives you a list of available platforms
+which you can pass to the --platform option of the
+make-standalone-toolchain.sh script. Make sure that <x> is at least 9.
+The --install-dir option (and therefore the <android-toolchain> value)
+specifies the path whereto the script will copy the necessary files.
+
+ATTENTION FOR X86 BUILDS:
+If you want to build for the x86 platform there is a flaw in the mentioned
+NDK. See http://code.google.com/p/android/issues/detail?id=19851 which results
+in linker errors mentioning "sigsetjmp and siglongjmp".
+In that case you have to download the libc.tar.bz2 from that google issue
+entry:
+
+http://android.googlecode.com/issues/attachment?aid=198510003000&name=libc.tar.bz2&token=6uNpHc1v8ixmVOTq3y6-ohUfb0o%3A1341156659947
+
+And extract it to <android-toolchain>/android-<x>/sysroot/usr/lib/ and overwrite
+the libc.so there. (where <android-toolchain>/android-<x>/ is the path you have given on the
+--install-dir option above)
+
+-----------------------------------------------------------------------------
+3. Getting the source code
+-----------------------------------------------------------------------------
+
+   # sudo apt-get install git-core
+   # cd $HOME
+   # git clone git://github.com/xbmc/android.git xbmc-android
+   # cd xbmc-android
+   # git submodule update --init addons/skin.touched
+
+-----------------------------------------------------------------------------
+4. Installing the required Ubuntu packages
+-----------------------------------------------------------------------------
+
+   # sudo apt-get install git-core make g++ gcc cvs rpl TODO
+
+If you run a 64bit operating system you will also need to get ia32-libs
+
+  # sudo apt-get install ia32-libs
+
+*** For developers and anyone else who compiles frequently it is recommended to use ccache
+sudo apt-get install ccache
+
+*** A tip for those with multiple computers at home is to check out distcc (totally unsupported from xbmc of course)
+sudo apt-get install distcc
+
+-----------------------------------------------------------------------------
+5. How to compile
+-----------------------------------------------------------------------------
+
+Compiling XBMC for Android consists of compiling the libraries XBMC depends
+on with the Android toolchain and creating an Android Application Package
+(APK) which can be installed in an Android system.
+
+--------------------------------------------------------------------
+5.1. Building dependencies
+--------------------------------------------------------------------
+
+   # cd $HOME/xbmc-android/tools/android/depends
+   # ./bootstrap
+   # ./configure --help
+
+   Run configure with the correct settings for you local configuration.
+
+   Anyone working on the dependencies themselves will want to set the
+   environment variables specified in ~/.bashrc or similar, to avoid
+   having to input these with each configure. 
+
+   # make -j <jobs>
+
+   This build was designed to be massively parallel. Don't be afraid to
+   give it a 'make -j20' or so.
+
+--------------------------------------------------------------------
+5.2. Building XBMC
+--------------------------------------------------------------------
+
+   # cd $HOME/xbmc-android
+   # make -C tools/android/depends/xbmc
+
+   After the first build (assuming bootstrap and configure are successful),
+   subsequent builds can be run with a simple 'make'.
+
+--------------------------------------------------------------------
+5.3. Building the APK
+--------------------------------------------------------------------
+
+   # cd $HOME/xbmc-android/tools/android/packaging
+   # make
+
+This will create the debug APK named "xbmcapp-debug.apk" in the
+"images" sub-directory
+
+-----------------------------------------------------------------------------
+6. Installing XBMC in an Android system
+-----------------------------------------------------------------------------
+
+To install XBMC through the previously built APK in an Android system you can
+either install it on a real device (smartphone/tablet/...) running Android
+2.3.x or use the Android emulator and the previously created AVD.
+
+--------------------------------------------------------------------
+6.1. Installing XBMC in the Android emulator
+--------------------------------------------------------------------
+
+   # cd $HOME/xbmc-android/tools/android/packaging
+   # emulator-arm -avd <avd-name> -wipe-data &
+   # adb install images/xbmcapp-debug.apk
+
+--------------------------------------------------------------------
+6.2. Installing XBMC on the Android device
+--------------------------------------------------------------------
+
+Make sure your Android device is connected to your computer through
+USB. Furthermore you have to enable the following option in your
+device's Android settings:
+
+  - Applications
+    [X] Unknown sources
+
+   # cd $HOME/xbmc-android/tools/android/packaging
+   # adb devices
+   # adb -s <device-id> install images/xbmcapp-debug.apk
+
+The <device-id> can be retrieved from the list returned by the
+"adb devices" command and is the first value in the row representing
+your device.
+
+-----------------------------------------------------------------------------
+7. Running and debugging XBMC in an Android system
+-----------------------------------------------------------------------------
+
+After installing XBMC's APK in an Android system you can start it using its
+Launcher icon in Android's Application Launcher.
+
+--------------------------------------------------------------------
+7.1. Debugging XBMC
+--------------------------------------------------------------------
+
+To be able to see what is happening while running XBMC you first need
+to enable USB debugging in your Android settings (this is already done
+when using the emulator):
+
+  - Applications
+    [X] Unknown sources
+     -  Development
+      [X] USB debugging
+
+To access the log output of your Android system run (the -s parameter
+and the <device-id> may not be needed when using the Android emulator)
+
+  # adb -s <device-id> logcat
+
+
+--------------------------------------------------------------------
+7.2. GDB
+--------------------------------------------------------------------
+
+GDB can be used to debug, though the support is rather primitive. Rather than
+using gdb directly, you will need to use ndk-gdb which wraps it. Do NOT trust
+the -p/--project switches, as of ndk7b they do not work. Instead you will need
+to cd to tools/android/packaging/xbmc and execute it from there.
+
+  # ndk-gdb --start
+
+This will open the installed version of XBMC and break. The warnings can be
+ignored as we have setup the appropriate paths already.
+
+Caveats:
+
+- Anything related to dlopen'd libs is hit or miss. Not good when libxbmc.so is
+  run that way. Basic functionality works, though be aware that breakpoints may
+  not be reliable yet.
+
+- Timings during the first second or two can be strange because gdb doesn't
+  know when we're actually into xbmc. For example, a breakpoint set for
+  android_init will likely never be hit. Use of ndk-gdb's --delay switch may
+  help.
+
+
+--------------------------------------------------------------------
+8. Architecture
+--------------------------------------------------------------------
+
+During the early days of the android port, xbmc was launched via a stub lib
+that then dlopen'd libxbmc. This was done to get around bionic's poor handling
+of shared libs. We now compile everything into libxbmc itself so that it has
+no runtime dependencies beyond system libs. Done this way, we're able to launch
+into libxbmc directly.
+
+But we still hit Bionic's loader's deficiencies when we dlopen a lib. There are
+two main issues to overcome for loading:
+
+1. Bionic imports all symbols for a lib as soon as it is loaded, and it will
+refuse to open a lib if it has a single unresolved symbol
+
+2. It does not search recursively during the resolve. So if liba depends on
+libb, dlopen'ing liba will _not_ pull in missing symbols from libb. This is
+particularly nasty considering #1.
+
+To work-around these problems we use our own recursive loader in place of
+dlopen. This loader mimics expected behavior. Using the example above, loading
+libb before liba will mean that everything will resolve correctly.
+
+Additionally, Android does not use versioned solibs. libfoo.so.1 which is
+typical on linux would not be found by the loader. This means that we must
+strip the SONAME and NEEDED values out of the libs as well as changing the
+filenames themselves. The cleaner solution would be to patch libtool/cmake/etc
+to not add versioning in the first place. For now, we use the brute-force
+approach of modifying the binary and blanking out the versions.
+
+See here for more info:
+http://www.bernawebdesign.ch/byteblog/2011/11/23/creating-non-versioned-shared-libraries-for-android/
+
+As a final gotcha, all libs must be in the form of ^lib*.so$ with no
+exceptions (they won't even install otherwise), and the soname must match.
+So we have to do some renaming to get some of our self-built libs loaded.
+
+Development:
+Typical android native activities are built with ndk-build which is a wrapper
+around Make. It would be a nightmare to port our entire buildsystem over, so
+instead we build as usual then package ourselves. It may be beneficial to use
+ndk-build to do the actual packaging, but for now its behavior is emulated.
+
+ABI:
+Presently we are targeting armv7a+neon for arm, and i686 for x86. Note that x86
+builds successfully but has not been tested.
+
+--------------------------------------------------------------------
+9. Useful Commands
+--------------------------------------------------------------------
+
+Below are a few helpful commands when building/debugging. These assume that pwd
+is 'tools/android/packaging' and that the proper sdk/ndk paths are set.
+
+-Install a new build over the existing one
+  # adb -e install -r images/xbmcapp-debug.apk
+
+-Launch XBMC on the emulator without the GUI
+  # adb shell am start -a android.intent.action.MAIN -n org.xbmc/android.app.NativeActivity
+
+-Kill a misbehaving XBMC
+  # adb shell ps | grep org.xbmc | awk '{print $2}' | xargs adb shell kill
+
+-Filter logcat messages by a specific tag (e.g. "XBMC")
+  # adb logcat -s XBMC:V
+
+-Create a (new) debug key to sign debug APKs
+  # keytool -genkey -v -store -alias androiddebugkey -dname "CN=Android Debug,O=Android,C=US" -keypass android -storepass android -keyalg RSA -keysize 2048 -validity 10000
+
+-Enable CheckJNI (BEFORE starting the application)
+  # adb shell setprop debug.checkjni 1
+