README.Android

   1 Android-specific notes
   2
   3 Note that this document has not necessarily been updated to match
   4 reality...
   5
   6 For instructions on how to build for Android, see README.cross.
   7
   8 * Getting something running on an emulated device
   9
  10         Create an AVD in the android UI, don't even try to get
  11 the data partition size right in the GUI, that is doomed to producing
  12 an AVD that doesn't work. Instead start it from the console:
  13
  14         LD_LIBRARY_PATH=$(pwd)/lib emulator-arm -avd <Name> -partition-size 500
  15
  16 In order to have proper acceleration, you need the 32-bit libGL.so:
  17
  18         sudo zypper in Mesa-libGL-devel-32bit
  19
  20         Where <Name> is the literal name of the AVD that you entered.
  21
  22         Then:
  23
  24         cd android/experimental/LOAndroid3
  25         ant debug install
  26         adb logcat
  27
  28         And if all goes well - you should have some nice debug output to enjoy
  29 when you start the app. After a while of this loop you might find that you have
  30 lost a lot of space on your emulator's or device's /data volume. If using the
  31 emulator, you can do:
  32
  33         adb shell stop; adb shell start
  34
  35 but on a (non-rooted) device you probably just need to reboot it. On the other
  36 hand, this phenomenon might not happen on actual devices.
  37
  38 * What about using a real device?
  39
  40         That works fine, too.
  41
  42 * Debugging
  43
  44         First of all, you need to configure the build with --enable-debug or
  45 --enable-dbgutil.  You may want to provide --enable-selective-debuginfo too,
  46 like --enable-selective-debuginfo="sw/" or so, in order to fit into the memory
  47 during linking.
  48
  49         Building with all symbols is also possible but the linking is currently
  50 slow (around 10 to 15 minutes) and you need lots of memory (around 16GB + some
  51 swap).
  52
  53         You also want to avoid --with-android-package-name (or when you use
  54 that, you must set it to "org.libreoffice"), otherwise ndk-gdb will complain
  55 that
  56
  57 ERROR: Could not extract package's data directory. Are you sure that
  58        your installed application is debuggable?
  59
  60         When you have all this, install the .apk to the device, and:
  61
  62         cd android/experimental/LOAndroid3
  63         <android-ndk-r10d>/ndk-gdb --adb=<android-sdk-linux>/platform-tools/adb --start
  64
  65         Pretty printers aren't loaded automatically due to the single shared
  66         object, but you can still load them manually. E.g. to have a pretty-printer for
  67         rtl::OString, you need:
  68
  69         (gdb) python sys.path.insert(0, "/master/solenv/gdb")
  70         (gdb) source /master/instdir/program/libuno_sal.so.3-gdb.py
  71
  72 * Common Errors / Gotchas
  73
  74 lo_dlneeds: Could not read ELF header of /data/data/org.libreoffice...libfoo.so
  75         This (most likely) means that the install quietly failed, and that
  76 the file is truncated; check it out with adb shell ls -l /data/data/....
  77
  78
  79 * Detailed explanation
  80
  81 Note: the below talk about unit tests is obsolete; we no longer have
  82 any makefilery etc to build unit tests for Android.
  83
  84 Unit tests are the first thing we want to run on Android, to get some
  85 idea how well, if at all, the basic LO libraries work. We want to
  86 build even unit tests as normal Android apps, i.e. packaged as .apk
  87 files, so that they run in a sandboxed environment like that of
  88 whatever eventual end-user Android apps there will be that use LO
  89 code.
  90
  91 Sure, we could quite easily build unit tests as plain Linux
  92 executables (built against the Android libraries, of course, not
  93 GNU/Linux ones), push them to the device or emulator with adb and run
  94 them from adb shell, but that would not be a good test as the
  95 environment such processs run in is completely different from that in
  96 which real end-user apps with GUI etc run. We have no intent to
  97 require LibreOffice code to be used only on "rooted" devices etc.
  98
  99 All Android apps are basically Java programs. They run "in" a Dalvik
 100 virtual machine. Yes, you can also have apps where all *your* code is
 101 native code, written in a compiled language like C or C++. But also
 102 also such apps are actually started by system-provided Java
 103 bootstrapping code (NativeActivity) running in a Dalvik VM.
 104
 105 Such a native app (or actually, "activity") is not built as a
 106 executable program, but as a shared object. The Java NativeActivity
 107 bootstrapper loads that shared object with dlopen.
 108
 109 Anyway, our current "experimental" apps (DocumentLoader,
 110 LibreOffice4Android and LibreOfficeDesktop) are not based on
 111 NativeActivity any more. They have normal Java code for the activity,
 112 and just call out to a single, app-specific native library (called
 113 liblo-native-code.so) to do all the heavy lifting.