README.Android

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