From 038b3b87b882d08fb86164fabdfef8c00d052521 Mon Sep 17 00:00:00 2001 From: Olli Leppanen Date: Mon, 20 Jun 2011 16:19:17 +0300 Subject: [PATCH] Fixes: NB#267376 - [TASK] Defects found in applauncherd documentation after proof-reading should be corrected RevBy: Juha Lintula --- debian/changelog | 4 +- doc/advancedapplauncherd.dox | 29 ++++++++------- doc/aegis.dox | 18 ++++----- doc/dbus.dox | 16 ++++---- doc/debianpackaging.dox | 15 ++++---- doc/debug.dox | 13 +++---- doc/eboost.dox | 34 ++++++++--------- doc/invokerparameters.dox | 19 +++++----- doc/libmeegotouchboost.dox | 52 +++++++++++++------------- doc/limitations.dox | 71 +++++++++++++++++++----------------- doc/mainpage.dox | 70 +++++++++++++++++------------------ doc/qmlboost.dox | 46 +++++++++++------------ doc/qtboost.dox | 40 ++++++++++---------- doc/singleinstance.dox | 6 +-- doc/splash.dox | 45 ++++++++++++----------- doc/tipsandtricks.dox | 13 +++---- doc/usingcmake.dox | 12 +++--- doc/usingpkgconfig.dox | 15 ++++++-- doc/usingqmake.dox | 24 ++++++------ 19 files changed, 278 insertions(+), 264 deletions(-) diff --git a/debian/changelog b/debian/changelog index 9a8da48..9dd0f70 100644 --- a/debian/changelog +++ b/debian/changelog @@ -1,7 +1,9 @@ applauncherd (0.30.3) unstable; urgency=low * Changes: single-instance documentation updated - + * Changes: Documentation updated according proof-reading results. + * Fixes: NB#267376 - [TASK] Defects found in applauncherd documentation after proof-reading should be corrected + -- Juha Lintula Mon, 20 Jun 2011 13:25:56 +0300 applauncherd (0.30.2) stable; urgency=low diff --git a/doc/advancedapplauncherd.dox b/doc/advancedapplauncherd.dox index e105041..230abe8 100644 --- a/doc/advancedapplauncherd.dox +++ b/doc/advancedapplauncherd.dox @@ -1,25 +1,28 @@ /*!\page advancedapplauncherd Advanced applauncherd usage -Applauncherd is usually started by \c upstart (Harmattan) or \c 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. +In MeeGo 1.2 Harmattan, applauncherd is usually started by \c upstart at +boot, but it can be also started manually in the device by the +/usr/bin/applauncherd script. Applauncherd does not daemonise itself +by default. If daemonising is wanted, use --daemon command-line +parameter. -In Harmattan, \c applauncherd can be started and stopped with the \c -initctl command, e.g. \c "initctl stop xsession/applauncherd". +In MeeGo 1.2 Harmattan, \c applauncherd can be started and stopped +with the \c initctl command, for example: initctl stop xsession/applauncherd \section bootmode Boot mode -There is a special boot mode that can be used to speed up device boots when -applauncherd is used. +There is a special boot mode that you can use 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. +In boot mode, no booster caches are initialised 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. +To activate the boot mode, start applauncherd with --boot-mode. To +enter normal mode, send SIGUSR1 Unix signal to the launcher. -Boot mode can be activated also by sending SIGUSR2 Unix signal to the launcher. +You can also activate boot mode by sending SIGUSR2 Unix signal to the +launcher. \section debuginfo Debug info diff --git a/doc/aegis.dox b/doc/aegis.dox index 5601c9f..73b1568 100644 --- a/doc/aegis.dox +++ b/doc/aegis.dox @@ -1,16 +1,16 @@ -/*! \page aegis Platform Security and Applauncherd +/*! \page aegis Requesting protected resources for the launcher -\section setup Setting up Aegis security tokens +\section setup Setting up aegis security tokens If your application does not have an aegis manifest file, no actions are needed for platform security. -If your application has a manifest file, something needs to be added -there: everything that is requested for the application binary must be -requested to the application launcher binary as well. +If your application has a manifest file, everything that is requested +for the application binary must be requested to the application +launcher binary as well. -For instance, manifest file for an application that needs only an -automatically generated application ID: +In the following example a manifest file for an application needs only +an automatically generated application ID: \code @@ -21,7 +21,7 @@ automatically generated application ID: \endcode -If an application has a user-defined ID: +In the following example an application has a user-defined ID: \code @@ -32,7 +32,7 @@ If an application has a user-defined ID: \endcode -Finally, if an application has some security tokens: +In the following example an application has security tokens: \code diff --git a/doc/dbus.dox b/doc/dbus.dox index 2f384a6..fe7e2af 100644 --- a/doc/dbus.dox +++ b/doc/dbus.dox @@ -1,10 +1,10 @@ -/*! \page dbus How To Use Launcher With D-Bus +/*! \page dbus Using launcher with D-Bus \section dbuslaunching Launching with D-Bus -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. \c .desktop and D-Bus \c .service files can be modified so that +If you are using D-Bus to launch your application, you can launch it +directly in the .service-file, without any wrapper scripts slowing +things down. The \c .desktop and D-Bus \c .service files can be modified so that normal execution is replaced with the following: \code @@ -14,11 +14,11 @@ Exec=/usr/bin/invoker --type=d /usr/bin/myApp By default, invoker waits for the application to terminate and exits with the same exit code. Most Unix signals received by invoker are forwarded to the application. -Note 1: Do not use --no-wait in D-Bus service files, otherwise D-Bus daemon may think that the application just died before registering its service. +Note: Do not use --no-wait in D-Bus service files, otherwise D-Bus daemon may think that the application just died before registering its service. -Note 2: When .desktop file contains the X-Maemo-Service field, the application -is started by default through D-Bus. This might cause some delay for -application start-up time. Therefore it is recommended not to have the +Note: When .desktop file contains the X-Maemo-Service field, the application +is started by default through D-Bus. This can delay the +application start-up. Therefore it is recommended not to have the X-Maemo-Service field inside .desktop files with launched applications, unless it is really needed for some other reason. diff --git a/doc/debianpackaging.dox b/doc/debianpackaging.dox index b825036..45b1fa5 100644 --- a/doc/debianpackaging.dox +++ b/doc/debianpackaging.dox @@ -1,13 +1,14 @@ -/*! \page debianpackaging Debian Packaging +/*! \page debianpackaging Packaging boosted applications Applications using the launcher must depend on the \c applauncherd package. For applications that use the exec booster, this is the only -dependency that is needed. Applications that use the QML booster or -the Qt booster need to add a build dependency to the \c -applauncherd-dev package, and applications that use the MeeGo Touch -booster should build-depend on the \c libmeegotouch-dev package. +dependency that is needed. For applications that use the QML booster +or the Qt booster, add a build dependency to the \c applauncherd-dev +package. For applications that use the MeeGo Touch booster, add a +build dependency to the \c libmeegotouch-dev package. + +When packaging applications for MeeGo 1.2 Harmattan, you may also need to +\ref aegis "modify the aegis manifest file" of the application. -When packaging applications for Harmattan, it may also be necessary to -\ref aegis "modify the Aegis manifest" of the application. */ diff --git a/doc/debug.dox b/doc/debug.dox index a9a3a01..14b349a 100644 --- a/doc/debug.dox +++ b/doc/debug.dox @@ -1,12 +1,11 @@ -/*! \page debug How To Debug Boosted Applications +/*! \page debug Debugging boosted applications \section debugging Debugging To debug a launched application, the debugger must be attached to an already running booster process. Due to security limitations -it's required to use aegis-su tool from aegis-dss-tools package. -See Use aegis-su tool... - +it's required to use \c aegis-su tool from \c aegis-dss-tools package. +For instance: 1. Run the following command: @@ -38,7 +37,7 @@ invoker --type=d /usr/bin/myApp If you use the \c pkg-config when building your binaries, they are linked with the \c -pie flag. The \c -pie flag makes your binaries -\e position \e independent \e executables. This means that the executables +\e position-independent \e executables. This means that the executables can be either used as a normal shared library or run, for example, from the command line. @@ -49,7 +48,7 @@ To use gdb 7.0 or earlier, link your binaries as libraries by using \c -shared instead of \c -pie. After this, you cannot execute your binaries directly, you have to use \c invoker. -Setting correct linker flags with QMake: +Setting correct linker flags with qmake: \code QMAKE_CXXFLAGS += -fPIC -fvisibility=hidden -fvisibility-inlines-hidden @@ -57,6 +56,6 @@ QMAKE_LFLAGS += -shared -rdynamic \endcode Remember to remove the CONFIG += qdeclarative-boostable, if used -(ditto for meegotouch-boostable or qt-boostable). +(the same applies for meegotouch-boostable or qt-boostable). */ diff --git a/doc/eboost.dox b/doc/eboost.dox index 07a478e..82d10bb 100644 --- a/doc/eboost.dox +++ b/doc/eboost.dox @@ -1,27 +1,27 @@ -/*! \page eboost Using the Exec Booster +/*! \page eboost Using the exec booster -Exec Booster is a generic booster for all kinds of applications. Unlike -the other boosters (Meegotouch, QML and QT boosters) this booster does -not help in quick startup of the application. It is basically a booster +The exec booster is a generic booster for all kinds of applications. Unlike +the other boosters (MeeGo Touch, QML and Qt boosters), this booster does +not help to start up the application more quickly. It is basically a booster that only exec()'s the given binary. It can be used to launch any application even if the application is not a library. -\section eboosterpurpose Purpose of Exec Booster +\section eboosterpurpose Purpose of exec booster -Applauncherd supports showing of a splash screen for applications. All -those applications which can be boosted using the other boosters can show -splash screen as described \ref splash "here". For those applications -which cannot be boosted and require to have a splash screen can use the -Exec Booster. Hence for launching a splash screen for any application the Exec -Booster can be used. Also the non boosted applications can be launched as a -\ref singleinstance "Single Instance" application using the Exec Booster. +Applauncherd allows applications to show a splash screen. For instructions +on showing the splash screen in applications boosted using the other +boosters, see \ref splash "here". If you want to have a splash screen in an +application that cannot be boosted, use the exec booster. Thus, you can use +exec booster for launching a splash screen for any application. You can +also launch non-boosted applications as \ref singleinstance "single-instance" +applications with the exec booster. -\section runebooster Running application using Exec Booster +\section runebooster Running an application with exec booster -One can launch any application binary using the Exec Booster. Before launching -any application one should check that applauncherd package is installed and -applauncherd daemon and the booster-e is running. Now one can launch the application -using Exec Booster as: +You can launch any application binary using the exec booster. Before launching +an application, check that applauncherd package is installed and applauncherd +daemon and the booster-e are running. You can then launch the application +with exec booster as follows: \code diff --git a/doc/invokerparameters.dox b/doc/invokerparameters.dox index a811198..d59a227 100644 --- a/doc/invokerparameters.dox +++ b/doc/invokerparameters.dox @@ -1,23 +1,24 @@ -/*! \page invokerparameters Advanced Invoker Command Line Parameters +/*! \page invokerparameters Advanced invoker command line parameters This section describes some of the invoker command line parameters. For a full list, use \c invoker \c --help. \section type --type TYPE -TYPE chooses the type of booster used. Qt-booster may be used to launch anything. Possible values for TYPE: +TYPE chooses the type of booster used. Qt booster may be used to +launch anything. Possible values for TYPE: - m = Launch a MeeGo Touch application. - q = Launch a Qt application. - d = Launch a Qt Declarative (QML) application. -- e = Launch any application, even if it's not a library. +- e = Launch any application even if it is not a library. \section delay -d, --delay SECS -After invoking sleep for SECS seconds (default 0). +After invoking, sleep for SECS seconds (default 0). \section respawn -r, --respawn SECS -After invoking respawn new booster after SECS seconds (default 3, max 10). -This can be used if the application is very slow to start up, and respawning the booster interferes +After invoking, respawn new booster after SECS seconds (default 3, max 10). +This can be used if the application is very slow to start up, and respawning the booster interferes. \section waitterm -w, --wait-term @@ -29,11 +30,11 @@ application again. \section nowait -n, --no-wait -Do not wait for launched process to terminate. +Do not wait for the launched process to terminate. \section globalsyms -G, --global-syms -Places symbols in the application binary and its libraries to the global scope. See RTLD_GLOBAL in the dlopen manual page. +Place symbols in the application binary and its libraries to the global scope. See RTLD_GLOBAL in the dlopen manual page. If your application loads a plugin that needs to access symbols defined in the main application, you need this parameter. You also @@ -43,7 +44,7 @@ need to explicitly export the symbols using \c M_EXPORT or \c Q_DECL_EXPORT. Notify invoker that the launched process is a daemon. This resets the oom_adj of the process. The flag is not needed if something like -Upstart already takes care of daemonization. +Upstart already takes care of daemonisation. */ diff --git a/doc/libmeegotouchboost.dox b/doc/libmeegotouchboost.dox index 353811b..a4e1c44 100644 --- a/doc/libmeegotouchboost.dox +++ b/doc/libmeegotouchboost.dox @@ -1,4 +1,4 @@ -/*! \page libmeegotouchboost Using the MeeGo Touch Booster +/*! \page libmeegotouchboost Using the MeeGo Touch booster This section describes how to use the MeeGo Touch booster. The booster provides the application with the key libraries already @@ -7,28 +7,28 @@ present in the process, and instances of \c MApplication and \section mtboostprereq Prerequisites -The launcher can start an application if the following pre-requisites are met: +The launcher can start an application if the following prerequisites are met: \li MApplication and MApplicationWindow instances are taken into use from MComponentCache -\li application is compiled and linked to a position independent binary +\li application is compiled and linked to a position-independent binary (executable or library) \li application is started with the \c invoker command instead of executing the -executable file. +executable file \section mtboostcompiling 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 +If you intend to run a binary with \c applauncherd, compile it +with \c -fPIC option to produce position independent code. It is +recommended to link them either as shared libraries, or, preferably, 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 +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 \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 @@ -48,7 +48,7 @@ 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 +Normally you do not need to worry about the compiler and linker flags, as the \c libmeegotouch-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 @@ -56,10 +56,10 @@ libmeegotouch-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 usingqmake "Using qmake", \ref usingcmake "Using CMake", or \ref usingpkgconfig "Using pkg-config". -\section mtboostcache 2. Utilizing the booster cache' +\section mtboostcache 2. Utilising the booster cache Instantiating \c MApplication and \c MApplicationWindow is a relatively expensive operation. The MeeGo Touch booster helps reduce application startup @@ -67,14 +67,14 @@ latency by creating instances of the classes in \c MComponentCache. MApplication instance must be taken from the MComponentCache. It is recommended to take MApplicationWindow from the cache as well. Thus, -if the classes are instantiated in the application as +if the classes are instantiated in the application as follows: \code MApplication application(argc, argv); MApplicationWindow window; \endcode -the code needs to be modified to: +Modify the code as follows: \code MApplication* application = MComponentCache::mApplication(argc, argv); @@ -92,11 +92,11 @@ MApplicationWindow instance is known to cause crashes. \section mtboostexit 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 +Making use of the cache is typically the only modification that you need to +make in the application. However, if the application has explicit calls to \c +exit(), change these 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 +libraries to be performed multiple times. For more details, see \ref limitations "Limitations and known issues". \section mtboostinvoker 4. Launching the application @@ -122,8 +122,8 @@ case, you can do: $ ps ax | grep booster-m \endcode -If you don't see the booster process, you need to start \c -applauncherd manually. In Harmattan and MeeGo, \c applauncherd should +If you do not see the booster process, you need to start \c +applauncherd manually. In MeeGo 1.2 Harmattan, \c applauncherd should be running as part of the UI session. Once you have verified that the booster process is running, you can @@ -134,12 +134,12 @@ your application: invoker --type=m /usr/bin/myApp \endcode -\section mtboostfinishingtouch 5. Finishing touches. +\section mtboostfinishingtouch 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." +The invoker can also provide single instance behaviour and a splash +screen for your application as follows. For more details, see +\ref singleinstance "Enabling single instance support for an application" and +\ref splash "Enabling a splash screen for an application". \code /usr/bin/invoker --single-instance --splash=/usr/share/myApp/splash.jpg --type=m /usr/bin/myApp diff --git a/doc/limitations.dox b/doc/limitations.dox index e21f6ee..a886095 100644 --- a/doc/limitations.dox +++ b/doc/limitations.dox @@ -1,35 +1,38 @@ /*! \page limitations Limitations and known issues -\section issue-exit Using \c _exit() instead of \c exit() +\section issue-exit Using _exit() instead of exit() -\c _exit() should be used instead of \c exit() with every other booster than exec-booster +Use \c _exit() instead of \c exit() with QML, Qt, and MeeGo Touch +boosters. However, do not use it with exec booster. The basic difference between \c exit() and \c _exit() is that the former -performs clean-up related to user-mode constructs in the library, and +performs cleanup related to user-mode constructs in the library and calls user-supplied cleanup-functions, whereas the latter performs only the kernel cleanup for the process. -The function \c _exit() terminates the calling process "immediately". Any +The function \c _exit() terminates the calling process immediately. Any open file descriptors belonging to the process are closed; any children of the process are inherited by process. The \c exit() function causes normal process termination and the value of -status is returned to the parent. A child process should strictly use +status is returned to the parent. A child process must strictly use \c _exit() instead of a simple \c exit(). -The user level initializations of the libraries are done once when the -launcher daemon loads the libraries. The launched applications are -child processes of the launcher, and every time exit() is called, the -corresponding cleanup actions are executed. The root problem is that -the cleanup actions get done multiple times, and libraries may not be -designed to tolerate this. By calling _exit() in the applications, -the problem is avoided. +The user-level initialisations of the libraries are done once when the +launcher daemon loads the libraries. The launched applications are +child processes of the launcher, and every time \c exit() is called, the +corresponding cleanup actions are executed. The root problem is that +the cleanup actions are carried out multiple times, and libraries may +not be designed to tolerate this. By calling \c _exit() in the +applications, the problem is avoided. -\section issue-cmdline Issues with command line arguments +\section issue-cmdline Command line arguments -Current launcher implementation does not support following Qt and -MeeGo Touch command line options (see QApplication and MApplication -docs for more information about command options usage): +Current launcher implementation does not support the following Qt and +MeeGo Touch command line options. For more information on QApplication +command line options, see MeeGo 1.2 Harmattan API reference +library. For more information on MApplication command line options, +see Platform API reference library. \li \c -style \li \c -stylesheet @@ -74,37 +77,37 @@ M_EXPORT int main(int argc, char **argv) { ... \endcode -\section issue-watchdog Issues with scripts, D-Bus, and process monitoring +\section issue-watchdog Scripts, D-Bus, and process monitoring By default, invoker processes terminate before or right after booster -processes have called main(). This may confuse shell scripts and -process monitoring in D-Bus daemon and Upstart, for instance. To help -solving these issues invoker accepts parameters - -\li \c --delay \c 10 invoker waits for 10 seconds before terminating -\li \c --wait-term invoker will not terminate until the launched -application terminates. Invoker will return the same return value as -the application did, or it will be terminated by the same signal as -the launched application. Signals received by the invoker process will -be forwarded to the launched application. +processes have called main(). This can confuse shell scripts and +process monitoring in D-Bus daemon and Upstart, for instance. To solve +these issues, you can use the following parameters supported by the +invoker: + + \li --delay 10 The invoker waits for 10 seconds before terminating + \li --wait-term The invoker does not terminate until the launched + application terminates. The invoker returns the same return + value as the application did, or it is terminated by the same + signal as the launched application. Signals received by the + invoker process are forwarded to the launched application. \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(). +It is not possible to use MComponentCache or MDeclarativeCache in the child +process if you fork() in your application. This is due to the fact that +X11 connections are disrupted after fork(). \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 -main(). This can cause crashes, if the application has installed a -custom debug message handler and didn't uninstall it before exit. +main(). This can cause crashes if the application has installed a +custom debug message handler and does not uninstall it before exit. -\section splashlimitations Splash screen limitations +\section splashlimitations Splash screen Splash screen functionality needs support from the \c mcompositor window manager. -Versions after 0.9.6 include splash screen support. \section wm_class_value WM_CLASS value diff --git a/doc/mainpage.dox b/doc/mainpage.dox index 959f8eb..931a5c3 100644 --- a/doc/mainpage.dox +++ b/doc/mainpage.dox @@ -1,10 +1,10 @@ -/*! \mainpage Optimizing Application Startup +/*! \mainpage Optimising application startup \section introduction 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 +applications launch faster and save memory through shared resources and +application type specific initialisations. 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 @@ -27,63 +27,61 @@ of applications. 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). +of the UI session (for example, \c upstart in MeeGo 1.2 Harmattan). 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. +is reduced by doing some initialisations 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 +application independent initialisation 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 +process, along with data on its running environment (for example, command line arguments and environment variables). The booster process loads the -binary, initializes its environment, and finally calls the \c main() +binary, initialises 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 +\section gettingstarted Getting started This section gives a quick introduction on \c invoker usage and boosting applications. -\subsection gettingstartedebooster Splash Screen and Single Instance +\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 +and to implement single instance behaviour. 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 \ref eboost "the exec booster documentation" and -\ref splash "the splash documentation". +follows. For more details, see \ref eboost "Using the exec booster" and +\ref splash "Enabling a splash screen for an application". \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: +To request single instance behaviour, use the following command line option: \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 -\ref singleinstance "the single instance documentation" for more -information. +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 \ref singleinstance +"Enabling single instance support for an application" 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: @@ -92,7 +90,7 @@ only shown when a new instance of the application is started: invoker --type=e --single-instance --splash=/usr/share/images/myAppSplash.jpg /usr/bin/myApp \endcode -\subsection boostingqtquick Boosting Qt Quick Applications +\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 @@ -101,7 +99,7 @@ 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 +In the following example a QML application 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 @@ -134,30 +132,30 @@ The \c --type=d command parameter specifies that this is a QML application. invoker --type=d ./qml-helloworld \endcode -Normally the compiler and linker flags would be provided automatically +Normally the compiler and linker flags are provided automatically either by using \ref usingpkgconfig "pkg-config" directly, or using it -via \ref usingcmake "cmake" or \ref usingqmake "qmake". +via \ref usingcmake "CMake" or \ref 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 \ref qmlboost "the QML booster documentation" -and \ref libmeegotouchboost "the MeeGo Touch booster documentation". +application binary to speed up opening it in the booster. For instructions, +see \ref qmlboost "Using the QML booster" +and \ref libmeegotouchboost "Using the MeeGo Touch booster". -\section reference Reference documentation +\section reference Further information - How to enable boosted startup for different types of applications: - - \subpage qmlboost "QML" - - \subpage qtboost "Qt" - - \subpage libmeegotouchboost "MeeGo Touch" - - \subpage eboost "Generic booster for all applications" + - \subpage qmlboost "Using the QML booster" + - \subpage qtboost "Using the Qt booster" + - \subpage libmeegotouchboost "Using the MeeGo Touch booster" + - \subpage eboost "Using the exec booster" -- \subpage splash "How to enable splash screen for the application" +- \subpage splash "Enabling a splash screen for an application" -- \subpage singleinstance "How to enable single instance support for the application" +- \subpage singleinstance "Enabling single instance support for an application" \section tipsntricks Tips and tricks -See separate page for \subpage tipsandtricks +See \subpage tipsandtricks. */ diff --git a/doc/qmlboost.dox b/doc/qmlboost.dox index 970c362..5e5b452 100644 --- a/doc/qmlboost.dox +++ b/doc/qmlboost.dox @@ -7,23 +7,23 @@ QDeclarativeView waiting in the cache. \section qmlboostprereq Prerequisites -The launcher can start an application if the following pre-requisites are met: +The launcher can start an application if the following prerequisites 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. + - The QML application uses a C++-based runner. + - The runner uses \c QApplication and \c QDeclarativeView directly, that is, 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 +If you intend to run a binary with \c applauncherd, compile it +with \c -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 \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 +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 \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 @@ -43,7 +43,7 @@ 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 +Normally you do 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 @@ -51,31 +51,31 @@ 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 usingqmake "Using qmake", \ref usingcmake "Using CMake", or \ref usingpkgconfig "Using pkg-config". -\section qmlboostcache 2. Utilizing the booster cache +\section qmlboostcache 2. Utilising 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 +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 +instantiates the classes as follows: \code QApplication app(argc, argv); QDeclarativeView view; \endcode -it needs to be modified into: +Modify it as follows: \code QApplication *app = MDeclarativeCache::qApplication(argc, argv); QDeclarativeView *window = MDeclarativeCache::qDeclarativeView(); \endcode -You also need to: +You also need to add: \code #include \endcode @@ -121,8 +121,8 @@ case, you can do: $ 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 +If you do not see the booster process, you need to start \c +applauncherd manually. In MeeGo 1.2 Harmattan, \c applauncherd should be running as part of the UI session. Once you have verified that the booster process is running, you can @@ -138,12 +138,12 @@ 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. +\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." +The invoker can also provide single instance behaviour and a splash +screen for your application as follows. For more details, see +\ref singleinstance "Enabling single instance support for an application" +and \ref splash "Enabling a splash screen for an application". \code /usr/bin/invoker --single-instance --splash=/usr/share/myApp/splash.jpg --type=d /usr/bin/myApp diff --git a/doc/qtboost.dox b/doc/qtboost.dox index ef7f8a7..bb57528 100644 --- a/doc/qtboost.dox +++ b/doc/qtboost.dox @@ -1,12 +1,12 @@ -/*! \page qtboost Using the Qt Booster +/*! \page qtboost Using the Qt booster This section describes how to use the Qt booster. The booster provides the application with the key libraries already present in the process, -but no other initializations are done in the booster. +but no other initialisations are done in the booster. \section intro Prerequisites -The launcher can start an application if the following pre-requisites are met: +The launcher can start an application if the following prerequisites are met: \li The application is compiled and linked to a position independent binary (executable or library) @@ -15,15 +15,15 @@ The launcher can start an application if the following pre-requisites are met: \section qtboostcompiling 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 +If you intend to run a binary with \c applauncherd, compile it +with \c -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 \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 +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 \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 @@ -45,22 +45,22 @@ 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 +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 usingqmake "Using qmake", \ref usingcmake "Using CMake", or \ref usingpkgconfig "Using pkg-config". \section qtboostexit 2. Adapting application source code No modifications are typically needed when the Qt booster is used. 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 +change them to use \c _exit() instead. This +prevents cleanup actions related to shared +libraries to be performed multiple times. For more details, see \ref limitations "Limitations and known issues". @@ -74,12 +74,12 @@ running. You can now run your application as usual as invoker --type=q /usr/bin/myApp \endcode -\section qtboostfinishingtouch 4. Finishing touches. +\section qtboostfinishingtouch 4. 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." +The invoker can also provide single instance behaviour and a splash +screen for your application as follows. For more details, see +\ref singleinstance "Enabling single instance support for an application" +and \ref splash "Enabling a splash screen for an application." \code /usr/bin/invoker --single-instance --splash=/usr/share/myApp/splash.jpg --type=q /usr/bin/myApp diff --git a/doc/singleinstance.dox b/doc/singleinstance.dox index 94a5ff0..7365ae8 100644 --- a/doc/singleinstance.dox +++ b/doc/singleinstance.dox @@ -1,6 +1,6 @@ -/*! \page singleinstance How To Enable Single Instance Support For the Application +/*! \page singleinstance Enabling single instance support for an application -Usually user wants his application to be run as a single instance. This means, +Usually a user wants an application to be run as a single instance. This means that if the launched application is already running, the existing application window is activated and no new application processes are started. @@ -26,6 +26,6 @@ plugin's window XProperty WM_COMMAND is manually set to correspond with the appl name used in the single-instance lock file. Consider using --single-instance instead of the single instance functionality -provided by D-Bus, because it very likely is much faster. +provided by D-Bus, because --single-instance is much faster in most cases. */ diff --git a/doc/splash.dox b/doc/splash.dox index df835f8..3c76bf4 100644 --- a/doc/splash.dox +++ b/doc/splash.dox @@ -1,9 +1,9 @@ -/*! \page splash How To Enable Splash Screen For the Application +/*! \page splash Enabling a splash screen for an application -\section splashsec Enabling splash screen +\section splashsec Enabling a splash screen -Applauncherd supports showing a splash screen if there is mcompositor -(the MeeGo window manager) running. +Applauncherd allows an application to show a splash screen if the +mcompositor (the MeeGo 1.2 Harmattan window manager) is running. The splash screen is not shown by default. If an application wants it to be shown, it must pass --splash, and optionally --splash-landscape @@ -11,15 +11,15 @@ arguments to the invoker. System default splash images can be obtained by giving \c default or \c default-landscape in place of image file names. -For instance, +For instance, the following shows the splash screen with splash.jpg +as its content when the device is in the portrait orientation: \verbatim /usr/bin/invoker --splash=/usr/share/application_name/splash.jpg --splash-landscape=/usr/share/application_name/splash-l.jpg --type=d /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 -only --splash is given, that image is shown in both orientations. +Otherwise splash-l.jpg is shown. If only --splash is given, that +image is shown in both orientations. Invoker passes the splash request to the booster. The booster sends the splash request to the window manager by setting a window property @@ -28,16 +28,16 @@ to window manager's window. If the filenames do not include absolute paths, the window manager looks for the files from a default location. -The file should be in a format recognized by QPixmap, preferably JPEG +The file should be in a format recognised by QPixmap, preferably JPEG as it is fast to load. The size of the image should not be larger than -the screen. If it is smaller, it will be stretched. +the screen. If it is smaller, it is stretched. \subsection splashndbus Splash and D-Bus interaction -Some care needs to be taken if the application is to be invoked via -D-Bus as well as from the application grid. The single instance -behavior provided by \c MApplication falls under this category as -well, so you may be using D-Bus even if there is no D-Bus related code +If you want to invoke the application through D-Bus as well as from +the application grid, follow the instructions in this section. This +also applies to single instance behaviour provided by \c MApplication, +so you may be using D-Bus even if there is no D-Bus related code in your application. If splash is not used, the \c Exec line in the application's \c @@ -50,7 +50,7 @@ launch() D-Bus method of the existing application instance and then exits. The end result is that the existing instance is brought to the foreground and there is just one instance of the application running. -Things change when the \c --splash option is used in an invoker command +This changes when the \c --splash option is used in an invoker command in the \c Exec line of the \c .desktop file. When the application is started from the grid and there is already an instance of the application running, the following sequence of events takes place: @@ -66,15 +66,16 @@ application running, the following sequence of events takes place: \li The compositor ignores this window, because it has a different pid from the one specified in the splash request. \li The compositor finally gives up waiting for the specified pid to - map a window, and fades away the splash screen, revealing the + map a window, and fades out the splash screen, revealing the application window. \subsection splashndbusdeploy Deployment with splash and D-Bus on Harmattan -There are basically two ways around the D-Bus related problem outlined -above. One is to use the single instance support of the invoker, and -the other one is to use a D-Bus service in the \c .desktop file. The -following examples demonstrate how to do this with the \c helloworld application. +There are two ways to solve the D-Bus related problem described in the +previous section. Firstly, you can use the single instance support of +the invoker, and, secondly, you can use a D-Bus service in the +\c .desktop file. The following examples demonstrate how to do this with +the \c helloworld application. In the first approach, there is an \c Exec line with \c invoker command in both the \c .desktop file and the \c .service file. Both @@ -98,8 +99,8 @@ Exec=/usr/bin/invoker --single-instance --splash /usr/share/helloworld/helloworl In the second approach, the \c .desktop file specifies the D-Bus service, and the invoker command is in the \c Exec line of the \c .service file. In this case there is no need for the \c ---single-instance flag. A small wrinkle is that the \c Exec line seems -to be required even if it is not used. +--single-instance flag. A minor problem is that the \c Exec line is +required even if it is not used. \code [Desktop Entry] diff --git a/doc/tipsandtricks.dox b/doc/tipsandtricks.dox index 32e366f..7b84e25 100644 --- a/doc/tipsandtricks.dox +++ b/doc/tipsandtricks.dox @@ -1,6 +1,5 @@ /*! \page tipsandtricks Tips and tricks - -This page contains miscellaneous tips and triks for using \c invoker and \c applauncherd +This section contains miscellaneous tips and tricks for using \c invoker and \c applauncherd. - \subpage invokerparameters "Advanced \c invoker command line parameters" @@ -8,18 +7,18 @@ This page contains miscellaneous tips and triks for using \c invoker and \c appl - How to compile and link applications with different build systems: - \subpage usingcmake "CMake" - - \subpage usingqmake "QMake" + - \subpage usingqmake "qmake" - \subpage usingpkgconfig "pkg-config" -- \subpage debug "How to debug boosted applications" +- \subpage debug "Debugging boosted applications" -- \subpage dbus "How to use applauncherd with D-Bus" +- \subpage dbus "Using the launcher with D-Bus" -- \subpage aegis "Aegis platform security and applauncherd" +- \subpage aegis "Requesting protected resources for the launcher" - \subpage limitations "Limitations and known issues" -- \subpage debianpackaging "Debian packaging" +- \subpage debianpackaging "Packaging boosted applications" */ diff --git a/doc/usingcmake.dox b/doc/usingcmake.dox index f40e73e..d0ca63f 100644 --- a/doc/usingcmake.dox +++ b/doc/usingcmake.dox @@ -1,12 +1,12 @@ /*! \page usingcmake Using CMake - You can utilize pkg-config in CMake by including FindPkgConfig in CMakeLists.txt: + You can utilise 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 + To ensure that Debian packages are 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. @@ -34,14 +34,14 @@ 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: + If you do not want to use pkg-config, you can manually add the + compiler and linker flags as follows: \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. + + Note: You must update the flags if something changes. */ diff --git a/doc/usingpkgconfig.dox b/doc/usingpkgconfig.dox index e0aa950..defdc44 100644 --- a/doc/usingpkgconfig.dox +++ b/doc/usingpkgconfig.dox @@ -1,19 +1,26 @@ -/*!\page usingpkgconfig Automatic settings with pkg-config (any build system) +/*!\page usingpkgconfig Using pkg-config - 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: + To build Debian packages correctly, add a build-dependency for + libmeegotouch-dev for MeeGo Touch applications and for + applauncherd-dev for other cases. The correct flags can be + automatically obtained as follows. + +For MeeGo Touch applications: \verbatim pkg-config --cflags meegotouch-boostable pkg-config --libs meegotouch-boostable \endverbatim +For QML applications: + \verbatim pkg-config --cflags qdeclarative-boostable pkg-config --libs qdeclarative-boostable \endverbatim +For Qt applications: + \verbatim pkg-config --cflags qt-boostable pkg-config --libs qt-boostable diff --git a/doc/usingqmake.dox b/doc/usingqmake.dox index 2e02508..209fefc 100644 --- a/doc/usingqmake.dox +++ b/doc/usingqmake.dox @@ -1,21 +1,21 @@ -/*! \page usingqmake Using QMake +/*! \page usingqmake Using qmake - If you are using QMake, making your application boostable is just a - matter of adding a suitable configuration option. + If you are using qmake, you can make your application boostable by + 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 + libmeegotouch-dev to build correctly. Add the following line to your .pro file (the meegotouch-boostable configuration option includes the meegotouch - option so you should not specify it explicitly): + option so you do not need to 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: + For Qt Declarative (QML) applications and plain Qt applications, the configuration + option is provided by the applauncherd-dev package. Note that a build dependency is + required for the correct building of Debian packages. The configuration options are: \verbatim CONFIG += qdeclarative-boostable @@ -24,8 +24,8 @@ 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 + If you want to use pkg-config directly (for instance, to receive the + error messages), you can add explicit pkg-config calls to the appropriate flags. For MeeGo Touch, the flags are: @@ -49,14 +49,14 @@ QMAKE_LFLAGS += `pkg-config --libs qt-boostable` \endverbatim - You can also manually set the options in your .pro file like this: + You can also manually set the options in your .pro file as follows: \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 + Note: You must update the flags manually if there are any changes in the required flags. */