/*!  \page qmlboost Using the QML booster 

This section describes how to use the QML (QDeclarative) booster. The
booster provides the application with the key libraries already
present in the process, and instances of \c QApplication and \c
QDeclarativeView waiting in the cache.

\section qmlboostprereq Prerequisites

The launcher can start an application if the following pre-requisites are met:

  - The QML-application uses a C++-based runner.
  - The runner uses \c QApplication and \c QDeclarativeView directly, i.e. does not inherit from the classes.
  - \c applauncherd-dev package is installed.

\section qmlboostcompiling 1. Compiling and linking for launcher

Binaries intended to be run with \c applauncherd should be compiled
with \c -fPIC option to produce position independent code. They should
then be linked either as shared libraries, or better yet as position
independent executables, which can be executed both traditionally and
with the launcher. The \c -pie and \c -rdynamic linker flags
accomplish this.

To improve linking and loading times of shared object libraries it is
encouraged to hide any unnecessary symbols from the resulting binary
by using \c -fvisibility=hidden and \c -fvisibility-inlines-hidden
flags as well.  However, \c applauncherd needs to find the entry point
for your application, so the symbol \c main needs to be explicitly made
visible. This can be done as follows:

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

If your application loads a plugin that needs to access some symbols
in the main application, the symbols also need to be exported. In
addition, the \c --global-syms invoker parameter needs to use, as
described in \ref invokerparameters "Advanced Invoker Command Line Parameters".

Normally you should not need to worry about the compiler and linker
flags, as the \c applauncherd-dev package provides configuration
options for \c QMake, \c cmake, and \c pkg-config. If you are building
a Debian package, make your package build-depend on \c
applauncherd-dev and your application binary package depend on
\c applauncherd.

For details on how to get the compiler and linker flags, see 
\ref usingqmake "Using QMake", \ref usingcmake "Using CMake", or
\ref usingpkgconfig "Using pkg-config".

\section qmlboostcache 2. Utilizing the booster cache

Instantiating \c QApplication and \c QDeclarativeView is a relatively
expensive operation. The QML booster helps reduce application startup
latency by creating instances of the classes in MDeclarativeCache. In
order to make use of this functionality, the applications needs to
pick up the instances from the cache. Thus, if the application code
instantiates the classes as

\code
      QApplication app(argc, argv);
      QDeclarativeView view;
\endcode

it needs to be modified into:

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

You also need to:
\code
    #include <MDeclarativeCache>
\endcode

The cache class works both with the booster and without it. In the
non-boosted case there are no pre-created instances, so the cache
class simply creates the instances on the fly.

The ownership of the instances is transferred from the cache to the
application code. The instances need to be deleted in the correct
order, deleting the \c QApplication instance before the \c
QDeclarativeView instance is known to cause crashes.

\section qmlboostexit 3. Adapting application source code

Making use of the cache is typically the only modification needed to
the application. However, if the application has explicit calls to \c
exit(), these should be changed to use \c _exit() instead. The brief
explanation is that this prevents cleanup actions related to shared
libraries to be performed multiple times. For more details see 
\ref limitations "Limitations and known issues".

\section qmlboostinvoker 4. Launching the application

Now everything should be in place for launching the application. The
linker flags create a Position Independent Binary (PIE), so the
application can still be invoked from the command line. In order to
verify that the modifications done to the application and the build
scripts have not broken anything, it is a good idea at this point to
check that the application still starts and functions normally from
the command line:

\code
$ ./myApp
\endcode

The next step is to use the \c invoker to launch the application. In
order for this to work, you need to have \c applauncherd and \c
booster-d (the QML booster process) running. To check that this is the
case, you can do:

\code
$ ps ax | grep booster-d
\endcode

If you don't see the booster process, you need to start \c
applauncherd manually. In Harmattan and MeeGo, \c applauncherd should
be running as part of the UI session.

Once you have verified that the booster process is running, you can
use the following command line to ask the booster process to turn into
your application:

\code
/usr/bin/invoker --type=d ./myApp
\endcode

Your application should start exactly as if it had been invoked from
the command line, just a little bit faster. You can now proceed to
change the \c .desktop file or \c .service file that launches the
application to use the invoker command.

\section qmlboostfinishingtouch 5. Finishing touches.

The invoker can also provide single instance behavior and a splash
screen for you application as follows. For more details, see 
\ref singleinstance "the single instance documentation" and 
\ref splash "the splash screen documentation."

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

*/