A compatibility layer for applications packaged as .apk
C C++ Makefile
Latest commit e9c0f4d Jul 17, 2015 @thp More Harmattan fixes
Failed to load latest commit information.
accelerometer Accelerometer abstraction; let platform plugin provide accelerometer Mar 26, 2014
android/dalvik_compat add an option to use the dalvikvm if possible (see usage) Dec 31, 2013
apklib Rename apklib/keycodes.h -> compat/android_keycodes.h Oct 15, 2013
audio Mixer abstraction. Fixes #39 Mar 27, 2014
compat More Harmattan fixes Jul 17, 2015
debug fix thumb wrappers Apr 24, 2015
imagelib implement SailfishOS support, made in collaboration with vakkov Dec 13, 2014
jni don't call strdup on NULL ptr, workaround for plants vs zombies v6.0.1 Jul 15, 2015
libs Cleanup build system and directory structure Mar 26, 2014
linker rename some more methods and (\!) variables to fix conflicts with lib… Jun 10, 2015
mixer use apkenv's mixer abstraction instead of SDL in the worldofgoo module Dec 16, 2014
modules fix multitouch in angrybirds Jul 15, 2015
platform More Harmattan fixes Jul 17, 2015
.gitignore add apkenv, libdvm_compat.so and generated modules to gitignore Jul 3, 2015
LICENSE.apkenv Initial public release Nov 19, 2012
README add a little bit of information about the debugging options Jul 5, 2015
README.raspberrypi Raspberry Pi Bionic libraries instructions Mar 12, 2013
apkenv.c fix a silly bug: if the last library was skipped (blacklisted) an ent… Jun 12, 2015
apkenv.h apkenv 42.23.0 Jul 16, 2015
config.mk world of goo, workaround for segfault on sailfishos Jun 28, 2015
debian Add symlinks for supported platforms Jul 16, 2015
makefile Build fixes for MeeGo 1.2 Harmattan Jul 17, 2015
rpm Add symlinks for supported platforms Jul 16, 2015

README

apkenv
======

A compatibility layer for applications packaged as .apk.

Support website: http://thp.io/2012/apkenv/


Example module and .apk
=======================

An example module is provided in modules/trg2.c - you can use this module as a
basis to create your own modules. You can download the .apk that works with
this example module from:

    http://thp.io/2011/trg2/


"Installing" applications
=========================

apkenv now includes a very rudimentary facility to "install" an .apk as an
application. What it really does is extract the icon from the .apk (this might
not work for all .apks - we'd need to read the manifest to get the real file
name and application name in all cases) and create a launcher icon that starts
apkenv with the apk file as its argument. To use it, type:

   apkenv --install /path/to/your.apk

please note that installing is not supported on the pandora port yet.


softfp vs. hardfp
=================

Android is softfp.
Maemo 5 is softfp.
MeeGo 1.2 Harmattan is hardfp.
Pandora is softfp.

softfp and hardfp differ in the way functions with floating point arguments
get called. Trying to call a hardfp function with the softfp calling
convention will not work and likely result in a crash or worse. To avoid
this, you can add an attribute to function declarations to make sure that
the function accepts its parameters using the softfp calling convention,
like this:

    __attribute__((pcs("aapcs")))

There's a convenience #define in apkenv.h called "SOFTFP" with which you can
decorate all functions that are either in a native library (i.e. in
modules/) or that will be called from the native library (i.e. in compat/).
Please note that in theory this attribute is only required on functions that
pass float values in the arguments, but do it always to save you some
headaches.


Debugging crashes
=================

First of all, enable debugging in the makefile (set DEBUG=1). Then rebuild
to get a debug build with lots of debug output. You can then check which
symbols get mapped from where at the linker phase (e.g. apkenv x.apk | grep
'from libc') - in general, most libc functions must be mapped in order to
avoid problems (e.g. stdio functions don't work in Bionic libc, so we have
to hack around these issues - the same is true for memory (de-)allocation,
etc..).

When you have all relevant functions mapped, ltrace'ing apkenv can help you
find the library function in which it crashes - this will not list functions
from Bionic libs, but only from your system libraries (another reason why it
is usually a good idea to map system-level functions).

apkenv now also has some more in depth debugging options (see --help), for
example tracing calls to bionic libraries (-ta -u), while running an app this
will show you which bionic functions are called from the app and if the crash
happens soon after one of the bionic functions is called try adding this
function to the hooks, in some cases this has helped us to fix crashes.

Documentation
=============

JNI Invocation API
http://docs.oracle.com/javase/1.5.0/docs/guide/jni/spec/invocation.html

JNI Functions
http://docs.oracle.com/javase/1.5.0/docs/guide/jni/spec/functions.html

JNI Types and Data Structures
http://docs.oracle.com/javase/1.5.0/docs/guide/jni/spec/types.html

GCC Function Attributes
http://gcc.gnu.org/onlinedocs/gcc/Function-Attributes.html

ARM Hard Float Point: VFP Comparison
http://wiki.debian.org/ArmHardFloatPort/VfpComparison

Android MotionEvent
http://developer.android.com/reference/android/view/MotionEvent.html


Third Party Code
================

All code written by me (thp) for apkenv is licensed under a simplified BSD
license (see LICENSE.apkenv). However, code from third parties might be
licensed under a different license, and have different copyright holders:

apklib/unzip.{c,h}, apklib/ioapi.{c,h}:
    The MiniZip project - http://www.winimage.com/zLibDll/minizip.html
    Copyright (C) 1998-2010 Gilles Vollant (minizip)
    Copyright (C) 2007-2008 Even Rouault
    Copyright (C) 2009-2010 Mathias Svensson ( http://result42.com )

apklib/ioapi_mem.c:
    ioapi implementation for accessing .zip files in memory
    Copyright (C) 1998-2003 Gilles Vollant
    Copyright (C) 2003 Justin Fletcher

linker/*:
    The Android Bionic Linker + The Android Bionic C Library
    Copyright (c) 2005-2008, The Android Open Source Project

jni/jni.h:
    libnativehelper: Support functions for Android's class libraries
    Copyright (C) 2006 The Android Open Source Project

compat/hooks.c, compat/pthread_wrapper.c:
    pthread wrapper implementation based on code from libhybris
    Copyright (C) 2012 Carsten Munk


Pandora Port
============

All code written by me (crowriot) for apkenv's pandora port is 
licensed under same conditions as the apkenv itself.