/*! \mainpage Applauncherd Usage \section intro Introduction Invoker (front-end binary) and applauncherd (daemon) are tools that helps applications launch faster and save memory via shared resources. This is achieved by preloading a set of dynamically linked libraries and caching stuff (MComponentCache, MDeclarativeCache). There's a also a possibility to configure an application-specific splash screen, which is shown before the application is started. Also a single-instance support is provided to allow only one instance of an application at a time. This documentation describes the idea behind this functionality and how to utilize it. \section contents Contents - \ref howdoesitwork "How does it work?" - 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 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" - \ref invokerparameters "Advanced invoker command line parameters" - \ref customboosters "How to write custom boosters" - \ref technical "Technical overview" \page compilinglinking Compiling and linking your application 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. \section changestocode 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): \code #include M_EXPORT int main(int argc, char **argv) { ... } \endcode or like this (Qt): \code #include Q_DECL_EXPORT int main(int argc, char **argv) { ... } \endcode or like this (generic way with gcc): \code extern "C" __attribute__ ((__visibility__("default"))) int main(int argc, char **argv) { ... } \endcode \section buildconfiguration Build configuration These instructions describe how to build your application so that it can be launched using applauncherd. Only Debian packaging is considered, you have to creatively apply the instructions if you are doing RPM packaging. \li \subpage usingqmake "Using QMake" \li \subpage usingcmake "Using cmake" \li \subpage usingpkgconfig "Using pkg-config" \page usingqmake Using QMake If you are using QMake, making your application boostable is just a matter of adding a suitable configuration option. For MeeGo Touch applications, install the libmeegotouch-dev package. If you are creating Debian packages, your application must build-depend on libmeegotouch-dev to build correctly. Add the following line in your .pro file (the meegotouch-boostable configuration option includes the meegotouch option so you should not specify it explicitly): \verbatim CONFIG += meegotouch-boostable \endverbatim For Qt Declarative (QML) applications, and plain Qt applications, the configuration option is provided by the applauncherd-dev package. Again, a build dependency is required for correct building of Debian packages. The configuration options are: \verbatim CONFIG += qdeclarative-boostable \endverbatim \verbatim CONFIG += qt-boostable \endverbatim If you want to use pkg-config directly for some reason (like getting error messages), you can add explicit pkg-config calls in the appropriate flags. For MeeGo Touch, the flags are: \verbatim QMAKE_CXXFLAGS += `pkg-config --cflags meegotouch-boostable` QMAKE_LFLAGS += `pkg-config --libs meegotouch-boostable` \endverbatim For Qt Declarative, the flags are: \verbatim QMAKE_CXXFLAGS += `pkg-config --cflags qdeclarative-boostable` QMAKE_LFLAGS += `pkg-config --libs qdeclarative-boostable` \endverbatim For plain Qt, the flags are: \verbatim QMAKE_CXXFLAGS += `pkg-config --cflags qt-boostable` QMAKE_LFLAGS += `pkg-config --libs qt-boostable` \endverbatim You can also manually set the options in your .pro file like this: \verbatim QMAKE_CXXFLAGS += -fPIC -fvisibility=hidden -fvisibility-inlines-hidden QMAKE_LFLAGS += -pie -rdynamic \endverbatim Note that in this case you have to update the flags manually if there are any changes in the required flags. \page usingcmake Using CMake You can utilize pkg-config in CMake by including FindPkgConfig in CMakeLists.txt: \verbatim include(FindPkgConfig) \endverbatim To get Debian packages built correctly, make the package build-depend on libmeegotouch-dev for MeeGo Touch applications, and on applauncherd-dev for other cases. To obtain the compiler and linker flags, add the following lines in CMakeLists.txt. For MeeGo Touch applications: \verbatim pkg_check_modules(MEEGOTOUCH_BOOSTABLE REQUIRED meegotouch-boostable) add_definitions(${MEEGOTOUCH_BOOSTABLE_CFLAGS}) link_libraries(${MEEGOTOUCH_BOOSTABLE_LDFLAGS}) \endverbatim For Qt Declarative applications: \verbatim pkg_check_modules(QDECLARATIVE_BOOSTABLE REQUIRED qdeclarative-boostable) add_definitions(${QDECLARATIVE_BOOSTABLE_CFLAGS}) link_libraries(${QDECLARATIVE_BOOSTABLE_LDFLAGS}) \endverbatim For plain Qt applications: \verbatim pkg_check_modules(QT_BOOSTABLE REQUIRED qt-boostable) add_definitions(${QT_BOOSTABLE_CFLAGS}) link_libraries(${QT_BOOSTABLE_LDFLAGS}) \endverbatim If you do not want to use pkg-config for some reason, you can manually add the compiler and linker flags like this: \verbatim set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -fPIC -fvisibility=hidden -fvisibility-inlines-hidden") set(CMAKE_EXE_LINKER_FLAGS "-pie -rdynamic") \endverbatim Again, this requires you to update the flags if something changes. \page usingpkgconfig Automatic settings with pkg-config (any build system) To get Debian packages built correctly, make the package build-depend on libmeegotouch-dev for MeeGo Touch applications, and on applauncherd-dev for other cases. The correct flags can be automatically obtained with one of: \verbatim pkg-config --cflags meegotouch-boostable pkg-config --libs meegotouch-boostable \endverbatim \verbatim pkg-config --cflags qdeclarative-boostable pkg-config --libs qdeclarative-boostable \endverbatim \verbatim pkg-config --cflags qt-boostable pkg-config --libs qt-boostable \endverbatim \page invoker Launching your application using invoker The application to be launched must be "invoked" using the invoker executable. 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 invoker can also provide \li \subpage splash "A splash screen" \li \subpage singleinstance "Single instance behavior" \section commandline Launch from the command-line Use one of the following invoker options to identify what kind of application you are launching. In these examples --type=m is used. \li \c --type=m MeeGo Touch applications \li \c --type=d Qt Declarative applications \li \c --type=qt Qt applications and everything else (see section 7). Here is a launch example for a MeeGo Touch application: \verbatim /usr/bin/invoker --type=m \endverbatim \page usingboosters Using boosters The booster processes can speed up application startup by doing some application independent initialization beforehand. This section documents the use of the qdeclarativebooster (QML booster), see the MeeGo Touch documentation for boosting MeeGo Touch applications similarly. \section changesqml Changes to code with QML booster The application cannot directly instantiate QApplication and QDeclarativeView. Instead of writing e.g. \verbatim QApplication app; QDeclarativeView view; \endverbatim you need to pick up instances of QApplication and QDeclarativeView from a cache: \verbatim QApplication *app = MDeclarativeCache::qApplication(argc, argv); QDeclarativeView *window = MDeclarativeCache::qDeclarativeView(); \endverbatim See the MDeclarativeCache documentation for details. \page starting Starting applauncherd Applauncherd is usually started by UpStart (Harmattan) or uxlaunch (MeeGo) at boot, 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. \section bootmode 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. Boot mode can be activated also by sending SIGUSR2 Unix signal to the launcher. \section debuginfo Debug info Applauncherd logs to syslog. Additional debug messages and logging also to stdout can be enabled with --debug. \page dependencies Package Dependencies Applications using the launcher must depend on the applauncherd package. \page otherboosters 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. \page commandlineparams Command line parameters All parameters are listed by: \verbatim invoker --help \endverbatim \verbatim applauncherd --help \endverbatim \page moreinformation More information See MeeGo Touch documentation for fast application startup. */