appmotor/doc/mainpage.dox

/*! \mainpage Optimizing Application Startup

\section intro Introduction

The \c invoker program and the \c applauncherd daemon help
applications launch faster and save memory via shared resources and
application type specific initializations. The \c invoker uses a
socket connection to request application launch, and applications are
forked from the daemon process so that they can share memory with the
daemon (and each other) using copy-on-write.  The invoker also
provides application specific splash screen support, and provides a
single instance facility that allows only one instance of an
application to be running at a time.

The following table shows what services are available for different kinds
of applications.

<table>
<tr><th></th>		<th>boosting</th>	<th>splash</th>	<th>single instance</th></tr>
<tr><td>QML</td>	<td>x</td>		<td>x</td>	<td>x</td></tr>
<tr><td>Qt</td>		<td>x(1)</td>		<td>x</td>	<td>x</td></tr>
<tr><td>MeeGo Touch</td><td>x</td>		<td>x</td>	<td>x</td></tr>
<tr><td>other</td>	<td>-</td>		<td>x</td>	<td>x</td></tr>
</table>

(1) Only library preloading.

All functionality of the launcher daemon is accessed using the \c
invoker program. The daemon is usually started automatically as part
of the UI session (e.g. \c upstart in Harmattan and \c uxlaunch in MeeGo).

The \c applauncherd daemon process links in a set of libraries so that
the launched applications do not need to do linking and symbol
resolution for the libraries at startup. In addition, startup latency
is reduced by doing some initializations before application launch.

When \c applauncherd is started, it forks off a number of \a booster
processes, one for each application type supported by the
launcher. The boosters first do some application type specific but
application independent initialization if applicable. For example, the
QML booster instantiates a \c QApplication and a \c QDeclarativeView,
and stores the instances in MDeclarativeCache. Each booster then
starts listening on its dedicated socket.

Applications are launched by using the \c invoker program. The invoker
sends the path of the application binary to the desired booster
process, along with data on its running environment (e.g. command line
arguments and environment variables). The booster process loads the
binary, initializes its environment, and finally calls the \c main()
function in the binary. If the booster process had instantiated some
objects, they can be picked up from the cache instead of constructing
them at startup. For example, a QML application runner written in C++
can pick up the \c QApplication and \c QDeclarativeView instances from
MDeclarativeCache.

\section gettingstarted Getting Started

This section gives a quick introduction on \c invoker usage and
boosting applications.

\subsection gettingstartedebooster Splash Screen and Single Instance

The \c invoker can be used to get a splash screen for the application
and to implement single instance behavior. If the \a exec \a booster
is used, no modifications to the application source code are needed. Simply
specify the name of the splash image on the invoker command line as
follows. For more details see \subpage eboost "the exec booster documentation" and
\subpage splash "the splash documentation".

\code 
invoker --type=e --splash=/usr/share/images/myAppSplash.jpg /usr/bin/myApp
\endcode

If single instance behavior is desired, it can be requested with a
command line option as follows:

\code
invoker --type=e --single-instance /usr/bin/myApp
\endcode

This causes \c invoker to look for a running instance of the
application using a simple lock file based mechanism. If an already
running instance is found, it is brought to the foreground instead of
launching a new instance of the application. See 
\subpage singleinstance "the single instance documentation" for more
information.

The options can also be combined, in which case the splash screen is
only shown when a new instance of the application is started:

\code 
invoker --type=e --single-instance --splash=/usr/share/images/myAppSplash.jpg /usr/bin/myApp
\endcode

\subsection boostingqtquick Boosting Qt Quick Applications

In order to boost Qt Quick applications with \c invoker, some changes
in the application and the way it is built are needed. The process is
similar for MeeGo Touch applications and plain Qt applications, for
details see appropriate documentation below. The \c applauncherd-dev
package needs to be installed to get the necessary headers and
libraries.

We assume a QML application that uses a simple C++ based runner. The
first step is to modify the application so that it picks up instances
of \c QApplication and \c QDeclarativeView from MDeclarativeCache. To
do this, the include directive for MDeclarativeCache is needed, and
the lines where the classes are instantiated need to be modified:

\code
    #include <MDeclarativeCache>
\endcode

\code
     QApplication *app = MDeclarativeCache::qApplication(argc, argv);
     QDeclarativeView *window = MDeclarativeCache::qDeclarativeView();
\endcode

All the boosters except the exec booster need the application binary
to be compiled as Position Independent Executable (PIE). This is
achieved by using \c -fPIC when compiling and \c -rdynamic \c -pie
when linking. A minimal QML helloworld could be compiled as linked as
follows.

\code
c++ -DQT_GUI_LIB -DQT_CORE_LIB -I/usr/include/qt4 -I/usr/include/qt4/QtGui -I/usr/include/qt4/QtCore -fPIC -I/usr/include/applauncherd -o main.o -c main.cpp
c++ main.o  -o qml-helloworld -rdynamic -pie -lmdeclarativecache -lQtCore -lQtDeclarative 
\endcode

The resulting binary can now be launched using the invoker as follows.
The \c --type=d command parameter specifies that this is a QML application.

\code
invoker --type=d ./qml-helloworld
\endcode

Normally the compiler and linker flags would be provided automatically
either by using \subpage usingpkgconfig "pkg-config" directly, or using it
via \subpage usingcmake "cmake" or \subpage usingqmake "qmake".

It is also a good idea to hide any unnecessary symbols in the
application binary to speed up opening it in the booster. How to do
this is covered in \subpage qmlboost "the QML booster documentation"
and \subpage libmeegotouchboost "the MeeGo Touch booster documentation".

\section reference Reference documentation

- How to enable boosted startup for different types of applications: 
  - \ref qmlboost "QML"
  - \ref qtboost "Qt"
  - \ref libmeegotouchboost "MeeGo Touch"
  - \ref eboost "Generic booster for all applications"

- \ref splash "How to enable splash screen for the application"

- \ref singleinstance "How to enable single instance support for the application"

- \ref invokerparameters "Advanced \c invoker command line parameters"

- \ref advancedapplauncherd "Advanced \c applauncherd usage"

\section tipsntricks Tips and tricks

- How to compile and link applications with different build systems:
  - \ref usingcmake "CMake"
  - \ref usingqmake "QMake"
  - \ref usingpkgconfig "pkg-config"

- \ref debug "How to debug boosted applications"

- \ref dbus "How to use applauncherd with D-Bus"

- \ref aegis "Aegis platform security and applauncherd"

- \ref limitations "Limitations and known issues"

*/