README.Android

   1 Android-specific notes
   2
   3 Note that this document has not necessarily been updated to match
   4 reality...
   5
   6 * Getting something running on an emulated device
   7
   8         Create an AVD in the android UI, don't even try to get
   9 the data partition size right in the GUI, that is doomed to producing
  10 and AVD that doesn't work. Instead start it from the console:
  11
  12         LD_LIBRARY_PATH=$(pwd)/lib emulator-arm -avd <Name> -partition-size 500
  13
  14 In order to have proper acceleration, you need the 32-bit libGL.so:
  15
  16         sudo zypper in Mesa-libGL-devel-32bit
  17
  18         Where <Name> is the literal name of the AVD that you entered.
  19
  20         Then:
  21
  22         make cmd cmd=bash
  23         cd android/qa/sc
  24         make clean all install
  25         make run ; adb shell logcat
  26
  27         And if all goes well - you should have some nice unit test output to
  28 enjoy. After a while of this loop you might find that you have lost a lot of
  29 space on your emulator's or device's /data volume. If using the emulator, you
  30 can do:
  31
  32         adb shell stop; adb shell start
  33
  34 but on a (non-rooted) device you probably just need to reboot it. On the other
  35 hand, this phenomenon might not happen on actual devices.
  36
  37         and continue onwards & upwards.
  38
  39 * What about using a real device?
  40
  41         That works fine, too. You won't be able to use the "adb shell
  42 stop" and "adb shell start" commands to do anything, as far as I
  43 know. But don't seem to be necessary on a real device anyway?
  44
  45 * Debugging
  46
  47         Debugging is fun, the default NDK gdb (in v7) is busted, you
  48 need to download a new one from:
  49
  50         http://code.google.com/p/mingw-and-ndk/
  51
  52         Even this 'fixed' gdb is broken in the way that it can see
  53 symbols only for shlibs that were already loaded when the debuggee was
  54 attached, so you need to carefully guess where to put:
  55
  56         fprintf(stderr, "Sleeping NOW!\n"); ::sleep(20);
  57
  58         into the code; and when you see that in logcat, you have time
  59 to run: ndk-gdb and it will attach the process.
  60
  61         thread 12 # or perhaps 13
  62         backtrace
  63
  64         may show you the native code trace.
  65
  66         In r8b the ndk-gdb seems to work a bit better, and I think it isn't
  67 necessary to use the mingw-and-ndk ndb-gdb any longer.
  68
  69
  70 * Common Errors / Gotchas
  71
  72 lo_dlneeds: Could not read ELF header of /data/data/org.libreoffice...libfoo.so
  73         This (most likely) means that the install quietly failed, and that
  74 the file is truncated; check it out with adb shell ls -l /data/data/....
  75
  76
  77 * Detailed explanation
  78
  79 Unit tests are the first thing we want to run on Android, to get some
  80 idea how well, if at all, the basic LO libraraies work. We want to
  81 build even unit tests as normal Android apps, i.e. packaged as .apk
  82 files, so that they run in a sandboxed environment like that of
  83 whatever eventual end-user Android apps there will be that use LO
  84 code.
  85
  86 Sure, we could quite easily build unit tests as plain Linux
  87 executables (built against the Android libraries, of course, not
  88 GNU/Linux ones), push them to the device or emulator with adb and run
  89 them from adb shell, but that would not be a good test as the
  90 environment such processs run in is completely different from that in
  91 which real end-user apps with GUI etc run. We have no intent to
  92 require LibreOffice code to be used only on "rooted" devices etc.
  93
  94 All Android apps are basically Java programs. They run "in" a Dalvik
  95 virtual machine. Yes, you can also have apps where all *your* code is
  96 native code, written in a compiled language like C or C++. But also
  97 also such apps are actually started by system-provided Java
  98 bootstrapping code (NativeActivity) running in a Dalvik VM.
  99
 100 Such a native app (or actually, "activity") is not built as a
 101 executable program, but as a shared object. The Java NativeActivity
 102 bootstrapper loads that shared object with dlopen.
 103
 104 Anyway, our current "experimental" apps (DocumentLoader and
 105 LibreOffice4Android) are not based on NativeActivity any more. They
 106 have normal Java code for the activity, and just call out to native
 107 libraries to do all the heavy lifting.
 108
 109 It is somewhat problematic to construct .apk packages except by using
 110 the high-level tools in the Android SDK. At least I haven't figured
 111 out how to manually construct an .apk that is properly signed so that
 112 it will run in the emulator. (I don't have any Android device...) I
 113 only know how to let the SDK Ant tooling do it...
 114
 115 At this stage, the plan is that a LO Android app will work would
 116 something like this:
 117
 118 We have a Java class org.libreoffice.android.Bootstrap that that loads
 119 a small helper native library liblo-bootstrap.so that implements JNI
 120 wrappers for dlopen(), dlsym(), and ELF header scanning coresponding
 121 to looking for DT_NEEDED entries with readelf.
 122
 123 The Java code then loads the actual native library that corresponds to
 124 the LibreOffice-related "program" we want to run. For unit tests, a
 125 library that corresponds to cppunittester program. Then through helper
 126 functions in liblo-bootstrap it calls a named function in that
 127 "program".
 128
 129 This Android-specific native code (the lo-bootstrap library) is for
 130 now in sal/android, and the Java code in the android "module"
 131 (subdirectory right here).