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 "Precise Pangolin" (12.04) 64Bit. This is what our continuous
17 integration system "jenkins" is using.
18 Additionally, building from OSX Snow Leopard is working.
20 NOTE TO NEW USERS: All lines that are prefixed with the '#'
21 character are commands that need to be typed into a terminal window /
22 console (similar to the command prompt for Windows). Note that the '#'
23 character itself should NOT be typed as part of the command.
25 -----------------------------------------------------------------------------
26 2. Installing the required Ubuntu packages
27 -----------------------------------------------------------------------------
28 These are the minimum packages necessary for building XBMC. Non-Ubuntu
29 users will need to get the equivalents.
31 # sudo apt-get install build-essential default-jdk git curl autoconf \
32 unzip zip zlib1g-dev gawk gperf cmake
34 If you run a 64bit operating system you will also need to get ia32-libs
36 # sudo apt-get install ia32-libs
38 The following versions are used on our continuous integration system "jenkins". Other (newer)
39 versions might work as well.
41 JDK: openjdk-6-jdk (java version "1.6.0_27")
42 JRE: openjre-6-jre (java version "1.6.0_27")
45 -----------------------------------------------------------------------------
46 3. Installing and setting up the Android environment
47 -----------------------------------------------------------------------------
49 To develop XBMC for Android the Android SDK and NDK are required.
51 --------------------------------------------------------------------
52 3.1. Getting the Android SDK and NDK
53 --------------------------------------------------------------------
55 To get the Android SDK, go to http://developer.android.com/sdk and
56 download the latest version for your operating system. The NDK
57 can be downloaded from http://developer.android.com/tools/sdk/ndk/
59 [NOTICE] Compiling XBMC for Android requires Android NDK
60 Revision r9. For the SDK just use the latest available.
63 After downloading the SDK and NDK extract the files contained in the
64 archives to your harddisk. For our example we are extracting in the following
65 directories (this matches the example from tools/depends/README aswell):
67 NDK (referenced as <android-ndk> from now on):
70 TOOLCHAIN (arm) (referenced as <android-toolchain-arm> from now on):
71 /opt/arm-linux-androideabi-4.8-vanilla/android-14
73 TOOLCHAIN (x86) (referenced as <android-toolchain-x86> from now on):
74 /opt/x86-linux-4.8-vanilla/android-14
76 SDK (referenced as <android-sdk> from now on):
77 /opt/android-sdk-linux
79 Make sure you have a recent JRE and JDK installed otherwise the
80 Android SDK will not work. (see point 2.)
82 --------------------------------------------------------------------
83 3.2. Installing Android SDK packages
84 --------------------------------------------------------------------
86 After having extracted the Android SDK to <android-sdk> you need to
87 install some android packages using the Android SDK Manager:
89 # cd <android-sdk>/tools
90 # ./android update sdk -u -t platform,platform-tool
92 --------------------------------------------------------------------
93 3.3. Setup the Android toolchain
94 --------------------------------------------------------------------
96 To be able to compile XBMC and the libraries it depends on for the
97 Android platform you first need to setup an Android toolchain using
98 the Android NDK which you earlier extracted to <android-ndk>. The
99 following commands will create a toolchain suitable for the most
101 The --install-dir option (and therefore the <android-toolchain-arm>/<android-toolchain-x86> value)
102 specifies where the resulting toolchain should be installed (your choice).
104 [NOTICE] XBMC uses the android API Version 14 and gcc version 4.8!
106 Building for arm architecture:
111 # ./make-standalone-toolchain.sh --ndk-dir=../../ \
112 --install-dir=<android-toolchain-arm>/android-14 --platform=android-14 \
113 --toolchain=arm-linux-androideabi-4.8
115 Building for x86 architecture:
120 # ./make-standalone-toolchain.sh --ndk-dir=../../ \
121 --install-dir=<android-toolchain-x86>/android-14 --platform=android-14 \
122 --toolchain=x86-4.8 --arch=x86 --system=linux-x86_64
124 Make sure to pick a toolchain for your desired architecture.
126 --------------------------------------------------------------------
127 3.4. Create a (new) debug key to sign debug APKs
128 --------------------------------------------------------------------
130 All packages must be signed. The following command will generate a
131 self-signed debug key. If the result is a cryptic error, it
132 probably just means a debug key already existed, no cause for alarm.
134 # keytool -genkey -keystore ~/.android/debug.keystore -v -alias \
135 androiddebugkey -dname "CN=Android Debug,O=Android,C=US" -keypass \
136 android -storepass android -keyalg RSA -keysize 2048 -validity 10000
138 -----------------------------------------------------------------------------
139 4. Getting the source code
140 -----------------------------------------------------------------------------
143 # git clone git://github.com/xbmc/xbmc.git xbmc-android
145 # git submodule update --init addons/skin.touched
147 -----------------------------------------------------------------------------
149 -----------------------------------------------------------------------------
151 Compiling XBMC for Android consists of compiling the libraries XBMC depends
152 on with the Android toolchain and creating an Android Application Package
153 (APK) which can be installed in an Android system.
155 --------------------------------------------------------------------
156 5.1. Building dependencies
157 --------------------------------------------------------------------
159 # cd $HOME/xbmc-android/tools/depends
163 Run configure with the correct settings for you local configuration.
164 See tools/depends/README for examples.
166 Anyone working on the dependencies themselves will want to set the
167 environment variables specified in ~/.bashrc or similar, to avoid
168 having to input these with each configure.
172 This build was designed to be massively parallel. Don't be afraid to
173 give it a 'make -j20' or so.
175 Verify that all deps built correctly (it will tell you so) before
176 continuing. You will get crazy build errors otherwise. If in doubt
177 run another 'make' (single threaded) until the message
178 "Dependencies built successfully." appears.
180 --------------------------------------------------------------------
182 --------------------------------------------------------------------
184 # cd $HOME/xbmc-android
185 # make -C tools/depends/target/xbmc
189 After the first build (assuming bootstrap and configure are successful),
190 subsequent builds can be run with a simple 'make' and 'make apk'.
192 -----------------------------------------------------------------------------
193 6. Installing XBMC in an Android system
194 -----------------------------------------------------------------------------
196 To install XBMC through the previously built APK in an Android system you can
197 either install it on a real device (smartphone/tablet/...) running Android
200 --------------------------------------------------------------------
201 6.1. Installing XBMC on the Android device
202 --------------------------------------------------------------------
204 Make sure your Android device is connected to your computer through
205 USB. Furthermore you have to enable the following option in your
206 device's Android settings:
211 # cd $HOME/xbmc-android/tools/android/packaging
213 # adb -s <device-id> install -r images/xbmcapp-debug.apk
215 The <device-id> can be retrieved from the list returned by the
216 "adb devices" command and is the first value in the row representing
219 -----------------------------------------------------------------------------
220 7. Running and debugging XBMC in an Android system
221 -----------------------------------------------------------------------------
223 After installing XBMC's APK in an Android system you can start it using its
224 Launcher icon in Android's Application Launcher.
226 --------------------------------------------------------------------
228 --------------------------------------------------------------------
230 To be able to see what is happening while running XBMC you first need
231 to enable USB debugging in your Android settings (this is already done
232 when using the emulator):
239 To access the log output of your Android system run (the -s parameter
240 and the <device-id> may not be needed when using the Android emulator)
242 # adb -s <device-id> logcat
245 --------------------------------------------------------------------
247 --------------------------------------------------------------------
249 GDB can be used to debug, though the support is rather primitive. Rather than
250 using gdb directly, you will need to use ndk-gdb which wraps it. Do NOT trust
251 the -p/--project switches, as they do not work. Instead you will need
252 to cd to tools/android/packaging/xbmc and execute it from there.
254 # ndk-gdb --start --delay=0
256 This will open the installed version of XBMC and break. The warnings can be
257 ignored as we have setup the appropriate paths already.
259 --------------------------------------------------------------------
261 --------------------------------------------------------------------
263 During the early days of the android port, xbmc was launched via a stub lib
264 that then dlopen'd libxbmc. This was done to get around bionic's poor handling
265 of shared libs. We now compile everything into libxbmc itself so that it has
266 no runtime dependencies beyond system libs. Done this way, we're able to launch
267 into libxbmc directly.
269 But we still hit Bionic's loader's deficiencies when we dlopen a lib. There are
270 two main issues to overcome for loading:
272 1. Bionic imports all symbols for a lib as soon as it is loaded, and it will
273 refuse to open a lib if it has a single unresolved symbol
275 2. It does not search recursively during the resolve. So if liba depends on
276 libb, dlopen'ing liba will _not_ pull in missing symbols from libb. This is
277 particularly nasty considering #1.
279 To work-around these problems we use our own recursive loader in place of
280 dlopen. This loader mimics expected behavior. Using the example above, loading
281 libb before liba will mean that everything will resolve correctly.
283 Additionally, Android does not use versioned solibs. libfoo.so.1 which is
284 typical on linux would not be found by the loader. This means that we must
285 strip the SONAME and NEEDED values out of the libs as well as changing the
286 filenames themselves. The cleaner solution would be to patch libtool/cmake/etc
287 to not add versioning in the first place. For now, we use the brute-force
288 approach of modifying the binary and blanking out the versions.
290 See here for more info:
291 http://www.bernawebdesign.ch/byteblog/2011/11/23/creating-non-versioned-shared-libraries-for-android/
293 As a final gotcha, all libs must be in the form of ^lib.*so$ with no
294 exceptions (they won't even install otherwise), and the soname must match.
295 So we have to do some renaming to get some of our self-built libs loaded.
298 Typical android native activities are built with ndk-build which is a wrapper
299 around Make. It would be a nightmare to port our entire buildsystem over, so
300 instead we build as usual then package ourselves. It may be beneficial to use
301 ndk-build to do the actual packaging, but for now its behavior is emulated.
304 Presently we are targeting armv7a+neon for arm, and i686 for x86.
306 --------------------------------------------------------------------
308 --------------------------------------------------------------------
310 Below are a few helpful commands when building/debugging. These assume that pwd
311 is 'tools/android/packaging' and that the proper sdk/ndk paths are set.
313 -Install a new build over the existing one
314 # adb -e install -r images/xbmcapp-debug.apk
316 -Launch XBMC on the emulator without the GUI
317 # adb shell am start -a android.intent.action.MAIN -n org.xbmc.xbmc/android.app.NativeActivity
319 -Kill a misbehaving XBMC
320 # adb shell ps | grep org.xbmc | awk '{print $2}' | xargs adb shell kill
322 -Filter logcat messages by a specific tag (e.g. "XBMC")
323 # adb logcat -s XBMC:V
325 -Enable CheckJNI (BEFORE starting the application)
326 # adb shell setprop debug.checkjni 1