aiden
/
appmotor
mirror of https://github.com/cutefishos/appmotor
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Fixes: NB#267376 - [TASK] Defects found in applauncherd documentation after proof-reading should be corrected

Browse Source 
RevBy: Juha Lintula
pull/1/head
Olli Leppanen 15 years ago
parent 921e13c67c
commit 038b3b87b8
19 changed files with 278 additions and 264 deletions
Show Stats Download Patch File Download Diff File

4
debian/changelog vendored
Unescape Escape View File

@ -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 <juha.lintula@nokia.com> Mon, 20 Jun 2011 13:25:56 +0300
applauncherd (0.30.2) stable; urgency=low

29
doc/advancedapplauncherd.dox
Unescape Escape View File

@ -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: <tt> initctl stop xsession/applauncherd </tt>
\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

18
doc/aegis.dox
Unescape Escape View File

@ -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
<aegis>
@ -21,7 +21,7 @@ automatically generated application ID:
</aegis>
\endcode
If an application has a user-defined ID:
In the following example an application has a user-defined ID:
\code
<aegis>
@ -32,7 +32,7 @@ If an application has a user-defined ID:
</aegis>
\endcode
Finally, if an application has some security tokens:
In the following example an application has security tokens:
\code
<aegis>

16
doc/dbus.dox
Unescape Escape View File

@ -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.

15
doc/debianpackaging.dox
Unescape Escape View File

@ -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.
*/

13
doc/debug.dox
Unescape Escape View File

@ -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 <B>aegis-su</B> tool from <B>aegis-dss-tools</B> package.
See <A HREF="https://projects.maemo.org/trac/meego-security/wiki/DisablingAegisValidator#Useaegis-sutooltogranttcbtomodechange">Use aegis-su tool...</A>
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).
*/

34
doc/eboost.dox
Unescape Escape View File

@ -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

19
doc/invokerparameters.dox
Unescape Escape View File

@ -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.
*/

52
doc/libmeegotouchboost.dox
Unescape Escape View File

@ -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

71
doc/limitations.dox
Unescape Escape View File

@ -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 <tt> --delay 10 </tt> The invoker waits for 10 seconds before terminating
\li <tt>--wait-term </tt> 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

70
doc/mainpage.dox
Unescape Escape View File

@ -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.
*/

46
doc/qmlboost.dox
Unescape Escape View File

@ -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 <MDeclarativeCache>
\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

40
doc/qtboost.dox
Unescape Escape View File

@ -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

6
doc/singleinstance.dox
Unescape Escape View File

@ -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.
*/

45
doc/splash.dox
Unescape Escape View File

@ -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]

13
doc/tipsandtricks.dox
Unescape Escape View File

@ -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"
*/

12
doc/usingcmake.dox
Unescape Escape View File

@ -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.
*/

15
doc/usingpkgconfig.dox
Unescape Escape View File

@ -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

24
doc/usingqmake.dox
Unescape Escape View File

@ -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.
*/

Write Preview
Loading…
Cancel
Save