appmotor/README

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

Applauncherd is a daemon that helps to launch applications faster by preloading
dynamically linked libraries and caching stuff (MComponentCache). It also saves
memory, because all launched applications share certain resources.

There's also an option to efficiently launch applications as single instances 
(see 2.3).  

Technical overview
==============================

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, "booster", before knowing which application is
going to be launched next. There can be different kinds of boosters 
optimized for different kinds of applications, e.g. Qt, Meego Touch, QML. 
Boosters are loaded as plugins. Applauncherd searches
for plugin libraries in /usr/lib/applaucherd/lib*booster.so and forks a new process
for each booster to wait for launch commands from the user.

The user uses the launcher always through a special invoker program. The invoker 
(/usr/bin/invoker) tells booster process to load an application binary via a
socket connection. 

The application to be used with applauncherd must be compiled as a shared 
library or a position independent executable (-pie) and it must always
export main().


Technical details
==============================

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. 

The launcher itself is a library that is loaded by a small C-program (/usr/bin/applauncherd.bin). Idea behind this is to avoid linking the launcher binary to any
libraries. This allows us to fully control the flags with which the preloaded
libraries are opened with dlopen(). 

Aegis platform security is used to protect the socket connection between
invoker and launcher. This works only for ARM target. 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. This document focuses
on using MeeGo Touch booster, but other boosters briefly introduced in Section 7.

Booster processes do some initializations that cannot be shared among other
processes and therefore have to be done after forking. This allows, for instance,
instantiating an MApplication (QApplication) 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 applications can fetch certain objects from a cache. 
This will significantly reduce the startup time of an application. 


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 both traditionally and with the launcher.

To improve linking and loading 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 as well.


1.1 Build configuration for MeeGo Touch applications

Use these instructions if you are building a MeeGo Touch application.
In this case your application must build-depend on libmeegotouch-dev. It will
install the .pc file for pkg-config and the feature file for QMake.

  Using QMake
  -----------

  If you are using QMake, making your application boostable is just a
  matter of installing libmeegotouch-dev package and adding the following
  line to your .pro file:

    CONFIG += meegotouch-boostable

  The meegotouch-boostable configuration option includes the meegotouch
  option (so you don't have to specify it explicitly) and ultimately
  uses pkg-config to get the correct flags.

  Using QMake with pkg-config
  ---------------------------
  
  If you want to use pkg-config directly for some reason (like getting
  error messages), you can do it by adding the following lines to your 
  .pro file:

    QMAKE_CXXFLAGS += `pkg-config --cflags meegotouch-boostable`
    QMAKE_LFLAGS += `pkg-config --libs meegotouch-boostable`

  Manual settings for QMake
  -------------------------

  You can manually set the options in your .pro file like this:

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

  Note that you have to update the flags manually if there are any changes in
  the required flags.

  Using CMake with pkg-config
  ---------------------------

  You can utilize pkg-config in CMake by including FindPkgConfig in CMakeLists.txt:

  include(FindPkgConfig) 
  
  To obtain the compiler and linker flags, add the following lines:

  pkg_check_modules(MEEGOTOUCH_BOOSTABLE REQUIRED meegotouch-boostable)
  add_definitions(${MEEGOTOUCH_BOOSTABLE_CFLAGS})
  link_libraries(${MEEGOTOUCH_BOOSTABLE_LDFLAGS})
  
  If you do not want to use pkg-config for some reason, you can manually add the
  compiler and linker flags like this:

  set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -fPIC -fvisibility=hidden 
      -fvisibility-inlines-hidden")
  set(CMAKE_EXE_LINKER_FLAGS "-pie -rdynamic")
  
  Again, this requires you to update the flags if something changes.

  Automatic settings with pkg-config (any build system)
  -----------------------------------------------------

  The correct flags can be automatically obtained with:

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


1.2 Build configuration for plain Qt / generic applications

Use these instructions if you are building a plain Qt / generic application
that is not depending on libmeegotouch. In this case, your application
must build-depend on applauncherd-dev, not libmeegotouch-dev. It will install
the .pc file for pkg-config and the feature file for QMake. 

  Using QMake
  -----------

  If you are using QMake, making your application boostable is just a
  matter of installing applauncherd-dev package and adding the following
  line to your .pro file:

    CONFIG += qt-boostable

  The qt-boostable configuration option uses pkg-config to get the correct flags.

  Using QMake with pkg-config
  ---------------------------
  
  If you want to use pkg-config directly for some reason, you can do it
  by adding the following lines to your .pro file:

    QMAKE_CXXFLAGS += `pkg-config --cflags qt-boostable`
    QMAKE_LFLAGS += `pkg-config --libs qt-boostable`

  Manual settings for QMake
  -------------------------

  You can manually set the options in your .pro file like this:

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

  Note that you have to update the flags manually if there are any changes in
  the required flags.

  Using CMake with pkg-config
  ---------------------------

  You can utilize pkg-config in CMake by including FindPkgConfig in CMakeLists.txt:

  include(FindPkgConfig) 
  
  To obtain the compiler and linker flags, add the following lines:

  pkg_check_modules(QT_BOOSTABLE REQUIRED qt-boostable)
  add_definitions(${QT_BOOSTABLE_CFLAGS})
  link_libraries(${QT_BOOSTABLE_LDFLAGS})
  
  If you do not want to use pkg-config for some reason, you can manually add the
  compiler and linker flags like this:

  set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -fPIC -fvisibility=hidden 
      -fvisibility-inlines-hidden")
  set(CMAKE_EXE_LINKER_FLAGS "-pie -rdynamic")
  
  Again, this requires you to update the flags if something changes.


  Automatic settings with pkg-config (any build system)
  -----------------------------------------------------

  The correct flags can be automatically obtained with:

    pkg-config --cflags --libs qt-boostable

  When using these, your application must build-depend on applauncherd-dev,
  which will install the needed qt-boostable.pc file for pkg-config.


1.3 Changes to the code

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)
  {
  ...
  }

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
user documentation for MeeGo Touch. 


2. LAUNCHING YOUR APPLICATION USING INVOKER

The application to be launched must be "invoked" using the invoker binary.
Invoker then sends the application data, essentially arguments and environment, 
to the launcher daemon via a socket connection. The launched application will
see its real binary name in its argv[0] (the old maemo-launcher stripped
the assumed .launch extension, but that is not done anymore). 

2.1 Launch from the command-line

Use --type=m parameter for MeeGo Touch applications and --type=qt for
plain Qt applications and everything else (see section 7). In these
examples --type=m is used. 

Here is a launch example for a MeeGo Touch application:

  /usr/bin/invoker --type=m <application_name>

2.2 D-Bus launch

If you are using D-Bus to launch your application, it can be done
straightly in the .service-file and without any wrapper scripts slowing
things down:

  [D-BUS Service]
  Name=com.nokia.<application_name>
  Exec=/usr/bin/invoker --type=m /usr/bin/<application_name>

By default, invoker waits for the application to terminate and exits with
the same exit code. Unix signals are also forwarded.
  
Note 1: If --no-wait and --delay is used, it is important to add enough delay to
invoker so that it won't exit before the launched application gets its
(possible) D-Bus service registered. Otherwise D-Bus daemon may think that the
application just died. 

Note 2: There is a slight difference in the application start-up time if you use a
wrapper script instead of the actual binary in Exec-field of .desktop and .service files. Therefore, it is recommended that you always use the actual invoker call with the binary name as presented above. 

Note 3: When .desktop file contains the X-Maemo-Service field, the application 
is started by default through D-Bus. This might cause some delay for
application start-up time. Therefore it is recommended not to have the 
X-Maemo-Service field inside .desktop files with launched applications,
unless it is really needed for some other reason.

See invoker --help for all possible command-line parameters.

2.3 Single instance launch

Usually user wants his application to be run as a single instance. This means,
that if the launched application is already running, the existing application
window is activated and no new application processes are started.

This can be achieved by adding --single-instance to the invoker command:

  [D-BUS Service]
  Name=com.nokia.<application_name>
  Exec=/usr/bin/invoker --single-instance --type=m /usr/bin/<application_name>
 
As a result, a lock file 
/tmp/single-instance-locks/<application_name>/instance.lock is created. 
If applauncherd cannot acquire the lock, it tries to find the corresponding
window and activates it.

This functionality is implemented in a position-independent executable called
single-instance. Applauncherd uses this executable as a library, but it can be
used as an ordinary program to start anything as a single instance:

  /usr/bin/single-instance <application_name>

Note, that in this case the launcher is not used.

Consider using --single-instance instead of the single instance functionality
provided by D-Bus, because itvery likely is much faster.

 
3. STARTING APPLAUNCHERD

Applauncherd is usually started by UpStart during the boot time, but it can be
also started manually in scratchbox or in the device by the /usr/bin/applauncherd
script. Applauncherd does not daemonize itself by default. If daemonizing is
wanted, use --daemon command-line parameter.

3.1 Boot mode

There is a special boot mode that can be used to speed up device boots when
applauncherd is used. 

In boot mode, no booster caches are initialized and the booster respawn delay is 
set to zero to ensure quick booster restarts after launches.

The boot mode is activated by starting applauncherd with --boot-mode. Normal mode
can be entered again by sending SIGUSR1 Unix signal to the launcher.

3.2 Debug info

Additional debug messages and logging also to stdout can be enabled with --debug.


4. PLATFORM SECURITY (AEGIS)

If your application does not have an Aegis manifest file, no actions are required.

All security tokens requested for the application must be requested also for 
applauncherd.bin in the application's Aegis manifest file.


5. PACKAGE DEPENDENCIES

Applications using the launcher must depend on applauncherd package.


6. CURRENT KNOWN ISSUES

6.1 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(). 

6.2 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. Invoker will return the same
    return value as the application did, or it will be terminated by
    the same signal as the launched application. Signals received by
    the invoker process will be forwarded to the launched application.

6.3 Crashes after application's main()

If an application is launched with invoker, there may be some
destructors of MeeGo Touch classes executed after application's
main(). This can cause crashes, if the application has installed a
custom debug message handler and didn't uninstall it before exit.


7. OTHER BOOSTERS

Warning: behavior of these boosters is subject to change.

Qt booster is a no-operation booster. It can be used by calling 
invoker --type=qt. Qt booster requires only that main() is exported
with M_EXPORT (or Q_DECL_EXPORT).
Any MeeGo Touch boostable application can be launched with this booster type as well, but it results in a slower start-up because of empty cache.


8. COMMAND-LINE PARAMETERS

All parameters are listed by:

invoker --help
applauncherd --help


9. MORE INFORMATION

See MeeGo Touch documentation for fast application startup.