README.Android

   1 Android-specific notes
   2
   3 Unit tests are the first thing we want to run on Android, to get some
   4 idea how well, if at all, the basic LO libraraies work. We want to
   5 build even unit tests as normal Android apps, i.e. packaged as .apk
   6 files, so that they run in a sandboxed environment like that of
   7 whatever eventual end-user Android apps there will be that use LO
   8 code.
   9
  10 Sure, we could quite easily build unit tests as plain Android
  11 executables, push them to the device or emulator with adb and run them
  12 from adb shell, but that would not be a good test as the environment
  13 would be completely different. They would run as root, and not
  14 sandboxed. We have no intent to require LibreOffice code to be used
  15 only on "rooted" devices etc.
  16
  17 All Android apps are basically Java programs. They run "in" a Dalvik
  18 virtual machine. Yes, you can also have apps where your code is only
  19 native code, written in a compiled language like C or C++. But also
  20 also such apps are actually started by system-provided Java
  21 bootstrapping code (NativeActivity) running in a Dalvik VM.
  22
  23 Such a native app (or actually, "activity") is not built as a
  24 executable program, but as a shared object. The Java NativeActivity
  25 bootstrapper loads that shared object with dlopen.
  26
  27 It is somewhat problematic to construct .apk packages except by using
  28 the high-level tools in the Android SDK. At least I haven't figured
  29 out how to manually construct an .apk that is properly signed so that
  30 it will run in the emulator. (I don't have any Android device...) I
  31 only know how to let the SDK Ant tooling do it...
  32
  33 A LO Android app would work would something like this:
  34
  35 We have a top Java bootstrapping class
  36 org.libreoffice.android.Bootstrap that loads a small helper native
  37 library liblo-bootstrap.so that implements JNI wrappers for dlopen(),
  38 dlsym(), and ELF header scanning coresponding to looking for DT_NEEDED
  39 entries with readelf.
  40
  41 The Java code then loads the actual native library that corresponds to
  42 the LibreOffice-related "program" we want to run. For unit tests, a
  43 library that corresponds to cppunittester program. Then through helper
  44 functions in liblo-bootstrap it calls a named function in that
  45 "program".
  46
  47 This Android-specific native code (the lo-bootstrap library) is for
  48 now in sal/android, and the Java code in the android "module"
  49 (subdirectory right here).
  50
  51 --Tor Lillqvist <tml@iki.fi>