From 8b1ceee52ac6f1a8543b8cc7aeaa4941555a9273 Mon Sep 17 00:00:00 2001 From: Olli Leppanen Date: Fri, 18 Mar 2011 10:27:59 +0200 Subject: [PATCH] Fixes: NB#234213 - The documentation of QML Booster is not good RevBy:Pertti Kellomaki --- CMakeLists.txt | 11 +- README => README.dox | 269 ++++++++++++++++--------- debian/changelog | 2 + debian/control | 2 +- debian/rules | 1 + doc/{Doxyfile => doxygen-impldoc.conf} | 2 +- 6 files changed, 192 insertions(+), 95 deletions(-) rename README => README.dox (76%) rename doc/{Doxyfile => doxygen-impldoc.conf} (99%) diff --git a/CMakeLists.txt b/CMakeLists.txt index 10c1dcf..408247e 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -105,13 +105,18 @@ endif ($ENV{BUILD_TESTS}) # Target for documentation (make doc) find_program(Doxygen NAMES doxygen) if (EXISTS ${Doxygen}) - add_custom_target(doc COMMAND ${Doxygen} doc/Doxyfile) + add_custom_target(doc COMMAND ${Doxygen} doc/doxygen-impldoc.conf COMMAND ${Doxygen} doc/doxygen-userdoc.conf) else (EXISTS ${Doxygen}) message(STATUS "Doxygen not found: you're not able to build documentation.") endif (EXISTS ${Doxygen}) -# Install README -install(FILES README DESTINATION /usr/share/doc/applauncherd) +# Install README.dox +install(FILES README.dox DESTINATION /usr/share/doc/applauncherd) + +# Install html documentation +install(DIRECTORY doc/implementation-documentation DESTINATION /usr/share/doc/applauncherd OPTIONAL) +install(DIRECTORY doc/user-documentation DESTINATION /usr/share/doc/applauncherd OPTIONAL) + # Install examples install(DIRECTORY examples diff --git a/README b/README.dox similarity index 76% rename from README rename to README.dox index e406649..f105454 100644 --- a/README +++ b/README.dox @@ -1,27 +1,46 @@ -THIS FILE -========= +/*! \mainpage Applauncherd usage -This README file describes only the idea behind the launcher and the basic -usage, it's not the user documentation for MeeGo Touch. Please refer to the -MeeGo Touch documentation for instructions on MComponentCache and how to enable -it in your application. - -What is applauncherd? -============================== +\section intro Introduction Applauncherd is a daemon that helps to launch applications faster by preloading dynamically linked libraries and caching stuff (MComponentCache, MDeclarativeCache). It also saves memory, because -all launched applications share certain resources. +all launched applications share certain resources. + +This documentation describes the idea behind the launcher and the +basic usage. It also explains some of the \subpage technical +"Technical details" of the implementation. + +\subsection howto How to... + +\li \subpage compilinglinking "Compile and link your application to be usable with the launcher" + +\li \subpage invoker "Launch your application using the invoker" + +\li \subpage usingboosters "Reduce startup time with cached object instances" + +\li \subpage splash "Show a splash screen during application launch" + +\li \subpage singleinstance "Ensure that only one instance of the application is running" + +\li \subpage starting "Starting applauncherd" + +\li \subpage security "Platform security" + +\li \subpage dependencies "Package Dependencies" + +\li \subpage knownissues "Current known issues" -In addition to the fast launch, applauncherd enables +\li \subpage otherboosters "Other boosters" -* a simple single-instance support for applications (see 2.3) +\li \subpage commandlineparams "Command line parameters" -* showing a splash screen during the launch (see 2.4) +\li \subpage moreinformation "More information" -Technical overview -============================== +For details of how to use MComponentCache and how to enable it in your +application, please refer to the MeeGo Touch documentation. + +\page technical Technical overview In Harmattan, the applauncherd daemon is started by UpStart as part of XSession, that is, at the same level as the desktop (MeeGo Touch @@ -44,8 +63,7 @@ with applauncherd must be compiled as a shared library or a position independent executable (-pie) and it must always export main(). -Technical details -============================== +\section techdetails Technical details Before loading an application binary, a booster process changes its security credentials so that the code in the application binary will be executed with @@ -78,11 +96,7 @@ the information about which application should be launched. With MeeGo Touch booster and Qt Declarative 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 +\page compilinglinking Compiling and linking you 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 @@ -93,15 +107,52 @@ To improve linking and loading times of shared object libraries the size of dyna 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 -1.1 Build configuration +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. - Using QMake - ----------- +\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. @@ -112,15 +163,20 @@ you have to creatively apply the instructions if you are doing RPM packaging. 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 @@ -128,33 +184,42 @@ you have to creatively apply the instructions if you are doing RPM packaging. 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. - Using CMake - --------------------------- +\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 @@ -162,106 +227,98 @@ you have to creatively apply the instructions if you are doing RPM packaging. 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: - set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -fPIC -fvisibility=hidden - -fvisibility-inlines-hidden") +\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. - Automatic settings with pkg-config (any build system) - ----------------------------------------------------- +\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 -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 - - M_EXPORT int main(int argc, char **argv) - { - ... - } - -or like this (Qt): - - #include - - 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) - { - ... - } - - -2. LAUNCHING YOUR APPLICATION USING INVOKER +\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]. -2.1 Launch from the command-line +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. - --type=m MeeGo Touch applications - --type=d Qt Declarative applications - --type=qt Qt applications and everything else (see section 7). + \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 -2.2 D-Bus launch +\section dbus 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: +\verbatim [D-BUS Service] Name=com.nokia. Exec=/usr/bin/invoker --type=m /usr/bin/ +\endverbatim By default, invoker waits for the application to terminate and exits with the same exit code. Unix signals are also forwarded. @@ -284,7 +341,7 @@ inside .desktop. Singe instance launch should be used instead (see below). See invoker --help for all possible command-line parameters. -2.3 Single instance launch +\page singleinstance 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 @@ -292,12 +349,14 @@ window is activated and no new application processes are started. This can be achieved by adding --single-instance to the invoker command: +\verbatim [D-BUS Service] Name=com.nokia. Exec=/usr/bin/invoker --single-instance --type=m /usr/bin/ - +\endverbatim + As a result, a lock file -/tmp/single-instance-locks//instance.lock is created. +\c /tmp/single-instance-locks/\/instance.lock is created. If applauncherd cannot acquire the lock, it tries to find the corresponding window and activates it. @@ -305,14 +364,16 @@ 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: +\verbatim /usr/bin/single-instance +\endverbatim 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 it very likely is much faster. -2.4 Splash screen +\page splash Splash screen Applauncherd supports showing a splash screen if there is mcompositor (the MeeGo window manager) running. @@ -323,10 +384,9 @@ arguments to the invoker. For instance, -/usr/bin/invoker --splash=/usr/share/application_name/splash.jpg \ - --splash-landscape=/usr/share/application_name/splash-l.jpg \ - --type=m \ - /usr/bin/application_name +\verbatim +/usr/bin/invoker --splash=/usr/share/application_name/splash.jpg --splash-landscape=/usr/share/application_name/splash-l.jpg --type=m /usr/bin/application_name +\endverbatim shows the splash screen with splash.jpg as its content when the device is in the portrait orientation. Otherwise splash-l.jpg is shown. If @@ -339,14 +399,40 @@ to window manager's window. If the filenames do not include absolute paths, the window manager looks for the files from a default location. -3. STARTING APPLAUNCHERD +\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. -3.1 Boot mode +\section bootmode Boot mode There is a special boot mode that can be used to speed up device boots when applauncherd is used. @@ -359,13 +445,13 @@ 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. -3.2 Debug info +\section debuginfo Debug info Applauncherd logs to syslog. Additional debug messages and logging also to stdout can be enabled with --debug. -4. PLATFORM SECURITY (AEGIS) +\page security Platform security (Aegis) If your application does not have an Aegis manifest file, no actions are required. @@ -373,20 +459,19 @@ All security tokens requested for the application must be requested also for applauncherd.bin in the application's Aegis manifest file. -5. PACKAGE DEPENDENCIES +\page dependencies Package Dependencies Applications using the launcher must depend on the applauncherd package. +\page knownissues Current known issues -6. CURRENT KNOWN ISSUES - -6.1 Forking +\section forking Forking It's not possible to use MComponentCache or MDeclarativeCache in the child process if you fork() in your application. This is just due to the fact that X11 connections get messed up after fork(). -6.2 Crashes after application's main() +\section crashes 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 @@ -394,7 +479,7 @@ 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 +\page otherboosters Other boosters Warning: behavior of these boosters is subject to change. @@ -405,15 +490,19 @@ 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 +\page commandlineparams Command line parameters All parameters are listed by: +\verbatim invoker --help -applauncherd --help +\endverbatim +\verbatim +applauncherd --help +\endverbatim -9. MORE INFORMATION +\page moreinformation More information See MeeGo Touch documentation for fast application startup. - +*/ diff --git a/debian/changelog b/debian/changelog index e6a4f06..a41595d 100644 --- a/debian/changelog +++ b/debian/changelog @@ -3,7 +3,9 @@ applauncherd (0.23.0) unstable; urgency=low * Changes: Removed extra prctl(PR_SET_DUMPABLE, ...) * Changes: e-booster refactoring * Changes: removed compilation warnings + * Changes: added user and api documentation as html in doc package * Fixes: NB#236033 - applauncherd does not build with gcc-4.5 + * Fixes: NB#234213 - The documentation of QML Booster is not good -- Alexey Shilov Thu, 10 Mar 2011 14:52:40 +0200 diff --git a/debian/control b/debian/control index 318441f..b875ada 100644 --- a/debian/control +++ b/debian/control @@ -2,7 +2,7 @@ Source: applauncherd Section: admin Priority: important Maintainer: Jussi Lind -Build-Depends: cmake (>= 2.6.0), debhelper (>= 7), libqt4-dev (>= 4.5.0), libmeegotouch-dev, libcreds2-dev [arm armel], aegis-builder (>= 1.4) [arm armel], libxtst-dev, libxext-dev, libxi-dev +Build-Depends: cmake (>= 2.6.0), debhelper (>= 7), libqt4-dev (>= 4.5.0), libmeegotouch-dev, libcreds2-dev [arm armel], aegis-builder (>= 1.4) [arm armel], libxtst-dev, libxext-dev, libxi-dev, doxygen Standards-Version: 3.8.0 Package: applauncherd diff --git a/debian/rules b/debian/rules index 40beff2..6760180 100755 --- a/debian/rules +++ b/debian/rules @@ -27,6 +27,7 @@ build: build-stamp build-stamp: configure-stamp dh_testdir make + make doc touch build-stamp clean: diff --git a/doc/Doxyfile b/doc/doxygen-impldoc.conf similarity index 99% rename from doc/Doxyfile rename to doc/doxygen-impldoc.conf index 053ffda..54dda51 100644 --- a/doc/Doxyfile +++ b/doc/doxygen-impldoc.conf @@ -763,7 +763,7 @@ GENERATE_HTML = YES # If a relative path is entered the value of OUTPUT_DIRECTORY will be # put in front of it. If left blank `html' will be used as the default path. -HTML_OUTPUT = html +HTML_OUTPUT = implementation-documentation # The HTML_FILE_EXTENSION tag can be used to specify the file extension for # each generated HTML page (for example: .htm,.php,.asp). If it is left blank