3 2. Installing and setting up the Android environment
4 3. Getting the source code
5 4. Installing the required Ubuntu packages
7 6. Installing XBMC in an Android system
8 7. Running and debugging XBMC in an Android system
12 -----------------------------------------------------------------------------
14 -----------------------------------------------------------------------------
16 We currently recommend Ubuntu Natty (11.04) or later. Current work has been
17 done here. Additionally, building from OSX Snow Leopard is working.
19 NOTE TO NEW USERS: All lines that are prefixed with the '#'
20 character are commands that need to be typed into a terminal window /
21 console (similar to the command prompt for Windows). Note that the '#'
22 character itself should NOT be typed as part of the command.
24 -----------------------------------------------------------------------------
25 2. Installing the required Ubuntu packages
26 -----------------------------------------------------------------------------
27 These are the minimum packages necessary for building XBMC. Non-Ubuntu
28 users will need to get the equivalents.
30 # sudo apt-get install build-essential default-jdk git curl autoconf \
31 unzip zip zlib1g-dev gawk gperf cmake
33 If you run a 64bit operating system you will also need to get ia32-libs
35 # sudo apt-get install ia32-libs
38 -----------------------------------------------------------------------------
39 3. Installing and setting up the Android environment
40 -----------------------------------------------------------------------------
42 To develop XBMC for Android the Android SDK and NDK are required.
43 Because the Android NDK is lacking support for wide characters (wchar_t)
44 which XBMC relies on for Unicode implementation, a third-party NDK
45 from Crystax is being used.
47 --------------------------------------------------------------------
48 3.1. Getting the Android SDK and NDK
49 --------------------------------------------------------------------
51 To get the Android SDK, go to http://developer.android.com/sdk and
52 download the latest version for your operating system. The Crystax NDK
53 can be downloaded from http://www.crystax.net/en/android/ndk
55 [NOTICE] Compiling XBMC for Android requires at least Crystax Android NDK
56 Revision 7b. Crystax Android NDK Revision 7 and earlier do not work
57 properly for our cause. The corresponding Crystax NDK version
58 is android-ndk-r7-crystax-5.beta3 Do not use the standard Android NDK.
60 [NOTICE] We previously used android-ndk-r7-crystax-5.beta2, but it produced
61 binaries that would NOT run on Jellybean 4.2. At this time,
62 android-ndk-r7-crystax-5.beta3 is required.
64 After downloading the SDK and NDK extract the files contained in the
65 archives to your harddisk.
67 Make sure you have a recent JRE and JDK installed otherwise the
68 Android SDK will not work.
70 --------------------------------------------------------------------
71 3.2. Installing Android SDK packages
72 --------------------------------------------------------------------
74 After having extracted the Android SDK to <android-sdk> you need to
75 install some android packages using the Android SDK Manager:
77 # cd <android-sdk>/tools
78 # ./android update sdk -u -t platform,platform-tool
80 --------------------------------------------------------------------
81 3.3. Setup the Android toolchain
82 --------------------------------------------------------------------
84 To be able to compile XBMC and the libraries it depends on for the
85 Android platform you first need to setup an Android toolchain using
86 the Android NDK which you earlier extracted to <android-ndk>. The
87 following commands will create a toolchain suitable for the most
89 The --install-dir option (and therefore the <android-toolchain> value)
90 specifies where the resulting toolchain should be installed (your choice).
95 # ./make-standalone-toolchain.sh --ndk-dir=../../ \
96 --install-dir=<android-toolchain>/android-14 --platform=android-14
98 ATTENTION FOR X86 BUILDS - THIS DOES NOT APPLY TO 99% OF BUILDS:
99 If you want to build for the x86 platform there is a flaw in the mentioned
100 NDK. See http://code.google.com/p/android/issues/detail?id=19851 which results
101 in linker errors mentioning "sigsetjmp and siglongjmp".
102 In that case you have to download the libc.tar.bz2 from that google issue
105 http://android.googlecode.com/issues/attachment?aid=198510003000&name=libc.tar.bz2&token=6uNpHc1v8ixmVOTq3y6-ohUfb0o%3A1341156659947
107 And extract it to <android-toolchain>/android-<x>/sysroot/usr/lib/ and overwrite
108 the libc.so there. (where <android-toolchain>/android-<x>/ is the path you have given on the
109 --install-dir option above)
111 --------------------------------------------------------------------
112 3.4. Create a (new) debug key to sign debug APKs
113 --------------------------------------------------------------------
115 All packages must be signed. The following command will generate a
116 self-signed debug key. If the result is a cryptic error, it
117 probably just means a debug key already existed, no cause for alarm.
119 # keytool -genkey -keystore ~/.android/debug.keystore -v -alias \
120 androiddebugkey -dname "CN=Android Debug,O=Android,C=US" -keypass \
121 android -storepass android -keyalg RSA -keysize 2048 -validity 10000
123 -----------------------------------------------------------------------------
124 4. Getting the source code
125 -----------------------------------------------------------------------------
128 # git clone git://github.com/xbmc/xbmc.git xbmc-android
130 # git submodule update --init addons/skin.touched
132 -----------------------------------------------------------------------------
134 -----------------------------------------------------------------------------
136 Compiling XBMC for Android consists of compiling the libraries XBMC depends
137 on with the Android toolchain and creating an Android Application Package
138 (APK) which can be installed in an Android system.
140 --------------------------------------------------------------------
141 5.1. Building dependencies
142 --------------------------------------------------------------------
144 # cd $HOME/xbmc-android/tools/depends
148 Run configure with the correct settings for you local configuration.
150 Anyone working on the dependencies themselves will want to set the
151 environment variables specified in ~/.bashrc or similar, to avoid
152 having to input these with each configure.
156 This build was designed to be massively parallel. Don't be afraid to
157 give it a 'make -j20' or so.
159 Verify that all deps built correctly (it will tell you so) before
160 continuing. You will get crazy build errors otherwise.
162 --------------------------------------------------------------------
164 --------------------------------------------------------------------
166 # cd $HOME/xbmc-android
167 # make -C tools/depends/target/xbmc
171 After the first build (assuming bootstrap and configure are successful),
172 subsequent builds can be run with a simple 'make' and 'make apk'.
174 -----------------------------------------------------------------------------
175 6. Installing XBMC in an Android system
176 -----------------------------------------------------------------------------
178 To install XBMC through the previously built APK in an Android system you can
179 either install it on a real device (smartphone/tablet/...) running Android
182 --------------------------------------------------------------------
183 6.1. Installing XBMC on the Android device
184 --------------------------------------------------------------------
186 Make sure your Android device is connected to your computer through
187 USB. Furthermore you have to enable the following option in your
188 device's Android settings:
193 # cd $HOME/xbmc-android/tools/android/packaging
195 # adb -s <device-id> install -r images/xbmcapp-debug.apk
197 The <device-id> can be retrieved from the list returned by the
198 "adb devices" command and is the first value in the row representing
201 -----------------------------------------------------------------------------
202 7. Running and debugging XBMC in an Android system
203 -----------------------------------------------------------------------------
205 After installing XBMC's APK in an Android system you can start it using its
206 Launcher icon in Android's Application Launcher.
208 --------------------------------------------------------------------
210 --------------------------------------------------------------------
212 To be able to see what is happening while running XBMC you first need
213 to enable USB debugging in your Android settings (this is already done
214 when using the emulator):
221 To access the log output of your Android system run (the -s parameter
222 and the <device-id> may not be needed when using the Android emulator)
224 # adb -s <device-id> logcat
227 --------------------------------------------------------------------
229 --------------------------------------------------------------------
231 GDB can be used to debug, though the support is rather primitive. Rather than
232 using gdb directly, you will need to use ndk-gdb which wraps it. Do NOT trust
233 the -p/--project switches, as of ndk7b they do not work. Instead you will need
234 to cd to tools/android/packaging/xbmc and execute it from there.
236 # ndk-gdb --start --delay=0
238 This will open the installed version of XBMC and break. The warnings can be
239 ignored as we have setup the appropriate paths already.
241 --------------------------------------------------------------------
243 --------------------------------------------------------------------
245 During the early days of the android port, xbmc was launched via a stub lib
246 that then dlopen'd libxbmc. This was done to get around bionic's poor handling
247 of shared libs. We now compile everything into libxbmc itself so that it has
248 no runtime dependencies beyond system libs. Done this way, we're able to launch
249 into libxbmc directly.
251 But we still hit Bionic's loader's deficiencies when we dlopen a lib. There are
252 two main issues to overcome for loading:
254 1. Bionic imports all symbols for a lib as soon as it is loaded, and it will
255 refuse to open a lib if it has a single unresolved symbol
257 2. It does not search recursively during the resolve. So if liba depends on
258 libb, dlopen'ing liba will _not_ pull in missing symbols from libb. This is
259 particularly nasty considering #1.
261 To work-around these problems we use our own recursive loader in place of
262 dlopen. This loader mimics expected behavior. Using the example above, loading
263 libb before liba will mean that everything will resolve correctly.
265 Additionally, Android does not use versioned solibs. libfoo.so.1 which is
266 typical on linux would not be found by the loader. This means that we must
267 strip the SONAME and NEEDED values out of the libs as well as changing the
268 filenames themselves. The cleaner solution would be to patch libtool/cmake/etc
269 to not add versioning in the first place. For now, we use the brute-force
270 approach of modifying the binary and blanking out the versions.
272 See here for more info:
273 http://www.bernawebdesign.ch/byteblog/2011/11/23/creating-non-versioned-shared-libraries-for-android/
275 As a final gotcha, all libs must be in the form of ^lib.*so$ with no
276 exceptions (they won't even install otherwise), and the soname must match.
277 So we have to do some renaming to get some of our self-built libs loaded.
280 Typical android native activities are built with ndk-build which is a wrapper
281 around Make. It would be a nightmare to port our entire buildsystem over, so
282 instead we build as usual then package ourselves. It may be beneficial to use
283 ndk-build to do the actual packaging, but for now its behavior is emulated.
286 Presently we are targeting armv7a+neon for arm, and i686 for x86. Note that x86
287 builds successfully but has not been tested.
289 --------------------------------------------------------------------
291 --------------------------------------------------------------------
293 Below are a few helpful commands when building/debugging. These assume that pwd
294 is 'tools/android/packaging' and that the proper sdk/ndk paths are set.
296 -Install a new build over the existing one
297 # adb -e install -r images/xbmcapp-debug.apk
299 -Launch XBMC on the emulator without the GUI
300 # adb shell am start -a android.intent.action.MAIN -n org.xbmc.xbmc/android.app.NativeActivity
302 -Kill a misbehaving XBMC
303 # adb shell ps | grep org.xbmc | awk '{print $2}' | xargs adb shell kill
305 -Filter logcat messages by a specific tag (e.g. "XBMC")
306 # adb logcat -s XBMC:V
308 -Enable CheckJNI (BEFORE starting the application)
309 # adb shell setprop debug.checkjni 1