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         make cmd cmd=bash
  25         cd android/qa/sc
  26         make clean all install
  27         make run ; adb shell logcat
  28
  29         And if all goes well - you should have some nice unit test output to
  30 enjoy. After a while of this loop you might find that you have lost a lot of
  31 space on your emulator's or device's /data volume. If using the emulator, you
  32 can do:
  33
  34         adb shell stop; adb shell start
  35
  36 but on a (non-rooted) device you probably just need to reboot it. On the other
  37 hand, this phenomenon might not happen on actual devices.
  38
  39         and continue onwards & upwards.
  40
  41 * What about using a real device?
  42
  43         That works fine, too. You won't be able to use the "adb shell
  44 stop" and "adb shell start" commands to do anything, as far as I
  45 know. But don't seem to be necessary on a real device anyway?
  46
  47 * Debugging
  48
  49         Some versions of the NDK had a broken gdb in the way that it can see
  50 symbols only for shlibs that were already loaded when the debuggee was
  51 attached, so you need to carefully guess where to put:
  52
  53         fprintf(stderr, "Sleeping NOW!\n"); ::sleep(20);
  54
  55         into the code; and when you see that in logcat, you have time
  56 to run: ndk-gdb and it will attach the process.
  57
  58         thread 12 # or perhaps 13
  59         backtrace
  60
  61         may show you the native code trace.
  62
  63         In r8b the ndk-gdb seems to work a bit better, and I think it isn't
  64 necessary to use the mingw-and-ndk ndb-gdb any longer.
  65
  66 * Getting the symbols
  67
  68 In order to be able to debug, you also need the symbols.  Currently they are
  69 stripped using a $(STRIP) call in android/Bootstrap/Makefile.shared ; make
  70 sure you change it only to 'cp'.
  71
  72 But then you need to limit the size of the resulting binary by other means,
  73 that is strip most of the symbols (but the interesting ones) already during
  74 the build.  For that, use something like
  75
  76 --enable-dbgutil
  77 --enable-selective-debuginfo="sal/"
  78
  79 in your autogen.input (but of course limit the --enable-selective-debuginfo
  80 only to directories / libraries that are interesting to you).
  81
  82 * Common Errors / Gotchas
  83
  84 lo_dlneeds: Could not read ELF header of /data/data/org.libreoffice...libfoo.so
  85         This (most likely) means that the install quietly failed, and that
  86 the file is truncated; check it out with adb shell ls -l /data/data/....
  87
  88
  89 * Detailed explanation
  90
  91 Note: the below talk about unit tests is obsolete; we no longer have
  92 any makefilery etc to build unit tests for Android.
  93
  94 Unit tests are the first thing we want to run on Android, to get some
  95 idea how well, if at all, the basic LO libraries work. We want to
  96 build even unit tests as normal Android apps, i.e. packaged as .apk
  97 files, so that they run in a sandboxed environment like that of
  98 whatever eventual end-user Android apps there will be that use LO
  99 code.
 100
 101 Sure, we could quite easily build unit tests as plain Linux
 102 executables (built against the Android libraries, of course, not
 103 GNU/Linux ones), push them to the device or emulator with adb and run
 104 them from adb shell, but that would not be a good test as the
 105 environment such processs run in is completely different from that in
 106 which real end-user apps with GUI etc run. We have no intent to
 107 require LibreOffice code to be used only on "rooted" devices etc.
 108
 109 All Android apps are basically Java programs. They run "in" a Dalvik
 110 virtual machine. Yes, you can also have apps where all *your* code is
 111 native code, written in a compiled language like C or C++. But also
 112 also such apps are actually started by system-provided Java
 113 bootstrapping code (NativeActivity) running in a Dalvik VM.
 114
 115 Such a native app (or actually, "activity") is not built as a
 116 executable program, but as a shared object. The Java NativeActivity
 117 bootstrapper loads that shared object with dlopen.
 118
 119 Anyway, our current "experimental" apps (DocumentLoader,
 120 LibreOffice4Android and LibreOfficeDesktop) are not based on
 121 NativeActivity any more. They have normal Java code for the activity,
 122 and just call out to a single, app-specific native library (called
 123 liblo-native-code.so) to do all the heavy lifting.