What is applauncherd?
==============================

Applauncherd is a daemon and it helps to launch applications faster by preloading MeeGo Touch and Qt dynamically linked libraries and making some initializations before loading the application binary and executing the main function.

The applauncherd daemon is started by UpStart as part of XSession, that is, at the same level as the desktop (MeeGo Touch homescreen). Applauncherd forks the will-be-application process a.k.a booster before knowing which application is going to be launched next. 

Users use the launcher always through a special invoker program. The invoker (/usr/bin/invoker) tells booster process to load an application binary. 

Before loading, booster process changes its security credentials so that the code in the application binary will be executed with the correct credentials. Loading the binary is done with dlopen(), and therefore the application needs to be compiled and linked as a shared library or a position independent executable. The booster process also sets the
environment variables. Finally, it finds the main function in the application binary with dlsym() and calls the main() with the command line arguments given by the invoker.

Aegis platform security is used to protect the socket connection between invoker and launcher. Currently this works only on the target device. It is automatically disabled by the build scripts when compiling on x86. 

Each application type (currently Qt and MeeGo Touch) has its own booster process. When booster launches the application by calling the "main()" function, applauncherd will create new booster process of that type. Qt booster can be used for all kinds of applicationts.

Booster processes do some initializations that cannot be shared among other processes and therefore have to be done after the fork. This allows, for instance, instantiating a MeeGo Touch application before knowing the name of the application. Then the booster process waits for a connection from the invoker with the information about which application should be launched. 

With MeeGo Touch booster it's possible to fetch certain objects from a cache. This will significantly reduce the startup time of an application. 

Note: Please refer to the MeeGo Touch documentation for instructions on MComponentCache and how to enable it in your application. This README file describes only the idea behind the launcher and the
basic usage, it's not the "official" user documentation.


Using applauncherd
==============================

1. COMPILING YOUR APPLICATION TO BE LAUNCHABLE

Binaries intended to be run with applauncherd should be compiled with -fPIC option to produce position independent code. In order to produce a position independent executable, -pie option and -rdynamic options can be used in linking. This allows the result to be executed traditionally and with the launcher.

To improve linking and load times of shared object libraries the size of dynamic export table it is encouraged to hide the unnecessary symbols from the resulting binary by using -fvisibility=hidden and -fvisibility-inlines-hidden flags in compilation as well. 

  Manual settings for QMake
  -------------------------
  
  If you are using QMake, you can define following variables in .pro file:

    QMAKE_CXXFLAGS += -fPIC -fvisibility=hidden -fvisibility-inlines-hidden
    QMAKE_LFLAGS += -pie -rdynamic

  Manual settings for CMake
  -------------------------

  With CMake, you can compile and install your program like this:

    set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -fPIC -fvisibility=hidden -fvisibility-inlines-hidden")
    set(CMAKE_EXE_LINKER_FLAGS " -pie -rdynamic")
    install(PROGRAMS myapplication DESTINATION /usr/bin RENAME myapplication.launch)

  Automatic settings with pkg-config
  ----------------------------------

  The correct flags can be automatically obtained with:

    pkg-config --cflags --libs meegotouch-boostable

  And with qmake: 
  
    CONFIG += meegotouch-boostable

  CMake also has a pkg-config support.

  When using these, your application must build-depend on applauncherd-dev.

  Symbol visibility
  -----------------

  With -fvisibility=hidden you must make sure that the symbol for main() is exported,
  because otherwise the launcher is not able to find the entry point for your
  application. This can be done like this (MeeGo Touch):

  #include <MExport>

  M_EXPORT int main(int argc, char **argv)
  {
  ...
  }

  or like this (Qt):

  #include <QtCore/QtGlobal>
  
  Q_DECL_EXPORT int main(int argc, char **argv)
  {
  ...
  }

  or like this (generic way with gcc):

  extern "C" __attribute__ ((__visibility__("default"))) int main(int argc, char **argv)
  {
  ...
  }

2. LAUNCHING YOUR APPLICATION

Rename appication binary to <application_name>.launch and replace the original binary by a wrapper script that executes invoker with correct application type and the name of the application binary as a parameter. 

Use --type=m parameter for MeeGo Touch applications and --type=qt for plain Qt applications and everything else. Here is a launch script example for a typical application:

  #!/bin/sh
  echo "/usr/bin/invoker --type=m" $0.launch $@
  exec /usr/bin/invoker --type=m $0.launch $@

If you are using D-Bus to launch your application, then this can be done straightly in the .service-file without any wrapper scripts:

  [D-BUS Service]
  Name=com.nokia.<application_name>
  Exec=/usr/bin/invoker --delay <seconds> --type=m /usr/bin/<application_name>.launch
  
  Note: when launching through D-Bus, it is important to add enough delay to invoker so that it won't
  exit before the launched application gets its D-Bus service registered. Otherwise D-Bus daemon may
  think that the application just died. Another option is to use --wait-term which makes invoker
  wait until the launched application exits.

3. STARTING Applauncherd

Applauncherd is started by UpStart during the boot time, but it can be also started manually in scratchbox or on the device by the /usr/bin/applauncherd script.

4. PLATFORM SECURITY (Aegis)

Altough the connection between invoker and launcher is protected by Aegis, Application developer doesn't need to request for any additional security tokens to make things work.

5. PACKAGING

Applications using the launcher must depend on applauncherd package.

6. CURRENT KNOWN ISSUES

  Forking and MComponentCache
  ---------------------------

  It's not possible to use MComponentCache if you fork() in your application
  before trying to fetch components from the cache. This is just due to the
  fact that X11 connections get messed up after fork(). 

  Issues with scripts, D-Bus, and process monitoring
  --------------------------------------------------
  
  By default, invoker processes terminate before or right after booster processes have called main().
  This may confuse shell scripts and process monitoring in D-Bus daemon and Upstart, for instance. To
  help solving these issues invoker accepts parameters:
  
  --delay 10 invoker waits for 10 seconds before terminating 
  --wait-term invoker will not terminate until the launched application process terminates.

7. FURTHER READING

MeeGo Touch documentation for fast application startup.