MeeGo 1.2 Harmattan Developer Documentation Develop for the Nokia N9

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 QApplication and QDeclarativeView waiting in the cache.

Note: This functionality is currently included in the Qt Quick application template provided by the Qt SDK. To enable QML booster in your application, select Make application boostable checkbox when creating a new project with the template.

Prerequisites

The launcher can start an application if the following prerequisites are met:

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

1. Compiling and linking for launcher

If you intend to run a binary with applauncherd, compile it with -fPIC option to produce position-independent code. It is recommended that you link them either as shared libraries, or, preferably, as position-independent executables, which can be executed both traditionally and with the launcher. The -pie and -rdynamic linker flags accomplish this.

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

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

If your application loads a plug-in that needs to access some symbols in the main application, the symbols also need to be exported. In addition, you must use the --global-syms invoker parameter, as described in Advanced invoker command line parameters.

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

For details on how to get the compiler and linker flags, see Using qmake, Using CMake, or Using pkg-config.

2. Utilising the booster cache

Instantiating QApplication and 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 need to pick up the instances from the cache. Thus, if the application code instantiates the classes as follows:

      QApplication app(argc, argv);
      QDeclarativeView view;

Modify it as follows:

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

You also need to add:

    #include <MDeclarativeCache>

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 QApplication instance before the QDeclarativeView instance is known to cause crashes.

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 exit(), these should be changed to use _exit() instead. The brief explanation is that this prevents cleanup actions related to shared libraries to be performed multiple times. For more details see Limitations and known issues.

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:

$ ./myApp

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

$ ps ax | grep booster-d

If you do not see the booster process, you need to start applauncherd manually. In MeeGo 1.2 Harmattan, 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:

/usr/bin/invoker --type=d ./myApp

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 .desktop file or .service file that launches the application to use the invoker command.

5. Finishing touches

The invoker can also provide single instance behaviour and a splash screen for your application as follows. For more details, see Enabling single instance support for an application and Enabling a splash screen for an application.

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