diff --git a/doc/aegis.dox b/doc/aegis.dox
new file mode 100644
index 0000000..5601c9f
--- /dev/null
+++ b/doc/aegis.dox
@@ -0,0 +1,50 @@
+/*! \page aegis Platform Security and Applauncherd
+
+\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.
+
+For instance, manifest file for an application that needs only an
+automatically generated application ID:
+
+\code
+
+
+
+
+
+
+\endcode
+
+If an application has a user-defined ID:
+
+\code
+
+
+
+
+
+
+\endcode
+
+Finally, if an application has some security tokens:
+
+\code
+
+
+
+
+
+
+
+
+
+\endcode
+
+*/
+
diff --git a/doc/customboosters.dox b/doc/customboosters.dox
new file mode 100644
index 0000000..47d5d8b
--- /dev/null
+++ b/doc/customboosters.dox
@@ -0,0 +1,3 @@
+/*! \page customboosters How To Write Custom Boosters
+*/
+
diff --git a/doc/dbus.dox b/doc/dbus.dox
new file mode 100644
index 0000000..a22469a
--- /dev/null
+++ b/doc/dbus.dox
@@ -0,0 +1,29 @@
+/*! \page dbus How To Use 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
+normal execution is replaced with the following:
+
+\code
+Exec=/usr/bin/invoker --type=m /usr/bin/
+\endcode
+
+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 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
+X-Maemo-Service field inside .desktop files with launched applications,
+unless it is really needed for some other reason.
+
+Application packages that use the launcher depend on the applauncherd
+package.
+
+*/
+
diff --git a/doc/debug.dox b/doc/debug.dox
new file mode 100644
index 0000000..dda594b
--- /dev/null
+++ b/doc/debug.dox
@@ -0,0 +1,58 @@
+/*! \page debug How To Debug Boosted Applications
+
+\section debugging Debugging
+
+To debug a launched application, the debugger must be attached
+to an already running booster process. For instance:
+
+1. Run the following command:
+
+\code
+gdb /usr/bin/applauncherd.bin $(pgrep booster-m)
+\endcode
+
+2. Set a breakpoint to the application code and let the process
+continue to that point:
+
+\code
+(gdb) break main.cpp:42
+No source file named main.cpp.
+Make breakpoint pending on future shared library load? (y or [n]) y
+
+Breakpoint 1 (main.cpp:42) pending.
+(gdb) c
+Continuing.
+\endcode
+
+3. Invoke the application with the booster to which the debugger
+is attached:
+
+\code
+invoker --type=m /usr/bin/application_binary
+\endcode
+
+\subsection pie-binaries PIE binaries and debugging
+
+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
+can be either used as a normal shared library or run, for example, from
+the command line.
+
+This creates problems when debugging your application with gdb older than
+version 7.1 which introduced the support for PIE binaries.
+
+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:
+
+\code
+QMAKE_CXXFLAGS += -fPIC -fvisibility=hidden -fvisibility-inlines-hidden
+QMAKE_LFLAGS += -shared -rdynamic
+\endcode
+
+Remember to remove the CONFIG += meegotouch-boostable, if used.
+
+*/
diff --git a/doc/doxygen-userdoc.conf b/doc/doxygen-userdoc.conf
index eb70684..6baa5bf 100644
--- a/doc/doxygen-userdoc.conf
+++ b/doc/doxygen-userdoc.conf
@@ -564,7 +564,22 @@ WARN_LOGFILE =
# directories like "/usr/src/myproject". Separate the files or directories
# with spaces.
-INPUT = doc/mainpage.dox src/qdeclarativebooster/mdeclarativecache.h
+INPUT = doc/mainpage.dox \
+ doc/qmlboost.dox \
+ doc/libmeegotouchboost.dox \
+ doc/qtboost.dox \
+ doc/eboost.dox \
+ doc/aegis.dox \
+ doc/howdoesitwork.dox \
+ doc/technical.dox \
+ doc/debug.dox \
+ doc/limitations.dox \
+ doc/invokerparameters.dox \
+ doc/singleinstance.dox \
+ doc/splash.dox \
+ doc/dbus.dox \
+ doc/customboosters.dox \
+ src/qdeclarativebooster/mdeclarativecache.h
# This tag can be used to specify the character encoding of the source files
# that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is
diff --git a/doc/eboost.dox b/doc/eboost.dox
new file mode 100644
index 0000000..75d7712
--- /dev/null
+++ b/doc/eboost.dox
@@ -0,0 +1,3 @@
+/*! \page eboost Using the Exec Booster
+*/
+
diff --git a/doc/howdoesitwork.dox b/doc/howdoesitwork.dox
new file mode 100644
index 0000000..56d435c
--- /dev/null
+++ b/doc/howdoesitwork.dox
@@ -0,0 +1,13 @@
+/*! \page howdoesitwork How Does the Launcher Work?
+
+\section Introduction
+
+In a nutshell, applauncherd is a daemon that forks \c booster processes, which in turn are transformed into real applications when user launches a boosted application.
+
+Booster processes do application-type specific initializations. For instance, the MeeGo Touch booster instantiates MApplication and MApplicationWindow objects and stores them to MComponentCache. Then the booster process waits for a connection from the \c invoker.
+
+An application is always launched by using the \c invoker program. The invoker sends the name and location of the application binary and
+data on its running environment to the desired booster process. This makes the booster process to load the binary, initialize its environment, and finally call the \c main() function in the binary.
+
+*/
+
diff --git a/doc/invokerparameters.dox b/doc/invokerparameters.dox
new file mode 100644
index 0000000..912abcc
--- /dev/null
+++ b/doc/invokerparameters.dox
@@ -0,0 +1,6 @@
+/*! \page invokerparameters Advanced Invoker Command Line Parameters
+
+See invoker --help for all possible command-line parameters.
+
+*/
+
diff --git a/doc/libmeegotouchboost.dox b/doc/libmeegotouchboost.dox
new file mode 100644
index 0000000..1b9cbe9
--- /dev/null
+++ b/doc/libmeegotouchboost.dox
@@ -0,0 +1,173 @@
+/*! \page libmeegotouchboost Using the MeeGo Touch Booster
+
+Launcher makes it possible to start up various types of applications very
+quickly. Launcher uses a different booster for each of the
+application types. This section concentrates on launching MeeGo Touch
+applications with the MeeGo Touch booster.
+
+\section intro Introduction
+
+The launcher can start an application if the following pre-requisites are met:
+
+\li MApplication and MApplicationWindow instances are taken into use from
+MComponentCache
+
+\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.
+
+\section howitworks How the launcher can help MeeGo Touch applications
+
+Applauncherd daemon makes it possible to launch applications faster. First of all, it preloads a number of
+libraries, including MeeGo Touch and Qt libraries. This makes it faster to load application binaries
+when needed. Secondly, it initialises certain components before an
+application is loaded and makes the results available to applications
+when they start.
+
+Boosted MeeGo Touch applications pick up and use the already
+instantiated MApplication and MApplicationWindow objects from
+MComponentCache instead of creating new ones.
+
+
+\section source Modifying source code
+
+MApplication instance must be taken from the MComponentCache. It is
+recommended to take MApplicationWindow from the cache as well. Thus, the main program should have:
+
+\code
+MApplication* application = MComponentCache::mApplication(argc, argv);
+MApplicationWindow* window = MComponentCache::mApplicationWindow();
+\endcode
+
+Note: Applications that use MComponentCache can be run without the
+launcher/invoker as well. In that case, MComponentCache
+instantiates new MApplication and MApplicationWindow objects on the
+fly.
+
+The launcher needs to find the symbol \c main in an application binary
+in order to start executing the application. However, unnecessary
+symbols in the application binary cause unnecessary overhead, so the
+recommended flags for compiling for the launcher hide symbols
+by default. When the flags are used, the main function must be
+explicitly exported as follows:
+
+\code
+#include
+
+M_EXPORT int main(int argc, char **argv)
+{
+...
+}
+\endcode
+
+
+\section compilation Compiling and linking
+
+To compile binaries that can be run with applauncherd, use
+\c -fPIC option to produce position-independent code. To
+produce a position-independent executable, \c -pie option and \c
+-rdynamic options can be used in linking. This makes it possible to execute the result both
+traditionally and with the invoker.
+
+To improve linking and load times of shared object libraries the size
+of dynamic export table it is encouraged to hide the unnecessary
+symbols from the resulting binary by using \c -fvisibility=hidden and
+\c -fvisibility-inlines-hidden flags in compilation as well.
+
+\subsection qmaketips Building with QMake
+
+\subsubsection qmakepreferred Building in the preferred way
+
+Once you have installed the \c libmeegotouch-dev package, simply use QMake configuration option
+\c meegotouch-boostable:
+
+\code
+CONFIG += meegotouch-boostable
+\endcode
+
+This tells qmake to use the \c meegotouch-boostable feature, which
+includes the \c meegotouch feature and ultimately uses \c pkg-config for the
+flags. Unfortunately qmake does not complain if you add the line but
+have not installed \c libmeegotouch-dev, so if the QMake magic does
+not seem to work, double-check that the package is indeed installed.
+
+\subsubsection qmakeother Building with pkg-config
+
+Use the \c pkg-config to get the correct flags:
+
+\code
+QMAKE_CXXFLAGS += `pkg-config --cflags meegotouch-boostable`
+QMAKE_LFLAGS += `pkg-config --libs meegotouch-boostable`
+\endcode
+
+If \c libmeegotouch-dev is not installed, \c pkg-config
+complains when you run \c make.
+
+\subsubsection qmakelastresort The last resort
+
+Manually define the following variables in the .pro file:
+
+\code
+QMAKE_CXXFLAGS += -fPIC -fvisibility=hidden -fvisibility-inlines-hidden
+QMAKE_LFLAGS += -pie -rdynamic
+\endcode
+
+It is then up to you to modify the .pro file if there are changes to the
+required compiler and linker flags.
+
+\subsection cmaketips Building with CMake
+
+1. Use \c pkg-config in CMake by including \c FindPkgConfig in \c CMakeLists.txt:
+
+\code
+include(FindPkgConfig)
+\endcode
+
+2. To obtain the compiler and linker flags, add the following lines:
+
+\code
+pkg_check_modules(MEEGOTOUCH_BOOSTABLE REQUIRED meegotouch-boostable)
+add_definitions(${MEEGOTOUCH_BOOSTABLE_CFLAGS})
+link_libraries(${MEEGOTOUCH_BOOSTABLE_LDFLAGS})
+\endcode
+
+If you do not want to use \c pkg-config for some reason, you can manually add the
+compiler and linker flags as follows:
+
+\code
+set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -fPIC -fvisibility=hidden -fvisibility-inlines-hidden")
+set(CMAKE_EXE_LINKER_FLAGS "-pie -rdynamic")
+\endcode
+
+Again, you need to update the flags if something changes.
+
+\subsection pkgconfig Obtaining flags with pkg-config
+
+The package \c libmeegotouch-dev provides the necessary files for
+\c pkg-config to get the appropriate compiler and linker flags.
+
+1. To get the compiler flags, use the following:
+
+\code
+pkg-config --cflags meegotouch-boostable
+\endcode
+
+2. To get the linker flags, use the following:
+
+\code
+pkg-config --libs meegotouch-boostable
+\endcode
+
+\section running Running boosted application
+
+Check that applauncherd package is installed and applancherd daemon is
+running. You can now run your application as usual as
+/usr/bin/application_binary, or use the mboosted launching by running:
+
+\code
+invoker --type=m /usr/bin/application_binary
+\endcode
+*/
+
diff --git a/doc/limitations.dox b/doc/limitations.dox
new file mode 100644
index 0000000..c244acd
--- /dev/null
+++ b/doc/limitations.dox
@@ -0,0 +1,80 @@
+/*! \page limitations Limitations and known issues
+
+\section issue-cmdline Issues with 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):
+
+\li \c -style
+\li \c -stylesheet
+\li \c -session
+\li \c -widgetcount
+\li \c -reverse
+\li \c -graphicssystem
+\li \c -display
+\li \c -geometry
+\li \c -fn
+\li \c -font
+\li \c -bg
+\li \c -background
+\li \c -fg
+\li \c -foreground
+\li \c -btn
+\li \c -button
+\li \c -name
+\li \c -title
+\li \c -visual
+\li \c -ncols
+\li \c -cmap
+\li \c -im
+\li \c -inputstyle
+\li \c -genimglist
+\li \c -remote-theme
+\li \c -fullscreen
+\li \c -disable-m-input-context
+
+QCoreApplication::arguments() returns a QStringList that containing at
+most 32 arguments and drops the rest. The full list of arguments is
+accessible through \c argc and \c argv. They can be converted into
+QStringList similar to returned by QCoreApplication::arguments() as
+follows:
+
+\code
+M_EXPORT int main(int argc, char **argv) {
+ QStringList arguments;
+ for (int a = 0; a < argc; ++a) {
+ arguments << QString::fromLocal8Bit(argv[a]);
+ }
+ ...
+\endcode
+
+\section issue-watchdog Issues with 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.
+
+\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().
+
+\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.
+
+*/
+
diff --git a/doc/mainpage.dox b/doc/mainpage.dox
index 94504fe..c77a372 100644
--- a/doc/mainpage.dox
+++ b/doc/mainpage.dox
@@ -1,107 +1,41 @@
-/*! \mainpage Applauncherd usage UNDER CONSTRUCTION!
+/*! \mainpage Applauncherd Usage UNDER CONSTRUCTION!
\section intro Introduction
Invoker (front-end binary) and applauncherd (daemon) are tools that helps applications launch faster and save memory via shared resources. This is achieved by preloading a set of dynamically linked libraries and caching stuff
(MComponentCache, MDeclarativeCache). There's a also a possibility to configure an application-specific splash screen, which is shown before the application is started. Also a single-instance support is provided to allow only one instance of an application at a time.
-This documentation describes the idea behind this functionality and how to utilize it. It also explains some of the \subpage technical "Technical details" of the implementation.
+This documentation describes the idea behind this functionality and how to utilize it.
\section contents Contents
-- \subpage howdoesitwork "How does it work?"
+- \ref howdoesitwork "How does it work?"
- How to enable boosted startup for different types of applications:
- - \subpage qmlboost "QML"
- - \subpage qtboost "Qt"
- - \subpage libmeegotouchboost "MeeGo Touch"
+ - \ref qmlboost "QML"
+ - \ref qtboost "Qt"
+ - \ref libmeegotouchboost "MeeGo Touch"
+ - \ref eboost "Generic booster for all applications"
-- \subpage splash "How to enable splash screen for the application"
+- \ref splash "How to enable splash screen for the application"
-- \subpage singleinstance "How to enable single instance support for the application"
+- \ref singleinstance "How to enable single instance support for the application"
-- \subpage tipsandtricks "Tips and tricks"
+- \ref debug "How to debug boosted applications"
-- \subpage technical "Technical overview"
+- \ref dbus "How to use applauncherd with D-Bus"
-- \subpage ownboosterplugin "Write your own booster for other application types"
+- \ref aegis "Aegis platform security and applauncherd"
-\section howdoesitwork How does it work?
+- \ref limitations "Limitations and known issues"
-In a nutshell, applauncherd is a daemon that forks \c booster processes, which in turn are transformed into real applications when user launches a boosted application.
+- \ref invokerparameters "Advanced invoker command line parameters"
-Booster processes do application-type specific initializations. For instance, the MeeGo Touch booster instantiates MApplication and MApplicationWindow objects and stores them to MComponentCache. Then the booster process waits for a connection from the \c invoker.
+- \ref customboosters "How to write custom boosters"
-An application is always launched by using the \c invoker program. The invoker sends the name and location of the application binary and
-data on its running environment to the desired booster process. This makes the booster process to load the binary, initialize its environment, and finally call the \c main() function in the binary.
+- \ref technical "Technical overview"
-\section tipsandtricks Tips and tricks
-
-- \subpage debug "Debugging boosted applications"
-
-- \subpage security "Security issues"
-
-- \subpage platform "Platform spesific limitations"
-
-- \subpage invokercommandline "Advanced invoker command line parameters"
-
-\page technical Technical overview
-
-In Harmattan, the applauncherd daemon is started by UpStart as part of
-XSession, that is, at the same level as the desktop (MeeGo Touch
-homescreen). In MeeGo, applaucherd is started by uxlaunch which is the
-program that brings up X and the ui.
-
-Applauncherd forks will-be-application processes, "boosters", before knowing
-which application is going to be launched next. Different boosters are
-optimized for different kinds of applications, e.g. Qt, Meego Touch, Qt
-Declarative. Boosters are loaded as plugins. Applauncherd searches for plugin
-libraries in /usr/lib/applaucherd/lib*booster.so and forks a new process for
-each booster to wait for launch commands from the user.
-
-The user uses the launcher always through a special invoker program. The
-invoker (/usr/bin/invoker) uses a socket connection to tell a booster process
-to load an application binary.
-
-In addition to possible source code changes, an application which is to be used
-with applauncherd must be compiled as a shared library or a position
-independent executable (-pie) and it must always export main().
-
-
-\section techdetails Technical details
-
-Before loading an application binary, a booster process changes its security
-credentials so that the code in the application binary will be executed with
-the correct credentials. The process also sets environment variables to the
-values sent by the invoker. Loading the binary is done with dlopen(), and
-therefore the application needs to be compiled and linked as a shared library
-or a position independent executable. Finally, the booster process finds the
-main function in the application binary with dlsym() and calls the main() with
-the command line arguments given by the invoker.
-
-The launcher itself is a library that is loaded by a small C-program (/usr/bin/applauncherd.bin).
-The idea behind this is to avoid linking the launcher binary to any
-libraries. This gives full control over the flags with which the preloaded
-libraries are opened with dlopen().
-
-In Harmattan, Aegis platform security is used to protect the socket connection
-between the invoker and boosters. This works only for ARM target. It is
-automatically disabled by the build scripts when compiling on x86.
-
-Each application type (currently Qt, Qt Declarative and MeeGo Touch) has its own booster process.
-When booster launches the application by calling the "main()" function,
-applauncherd will create new booster process of that type.
-
-Booster processes do some initializations that cannot be shared among other
-processes and therefore have to be done after forking. This allows, for instance,
-instantiating an MApplication (QApplication) before knowing the name of the
-application. Then the booster process waits for a connection from the invoker with
-the information about which application should be launched.
-
-With MeeGo Touch booster and Qt Declarative booster, applications can fetch certain objects from a cache.
-This will significantly reduce the startup time of an application.
-
-\page compilinglinking Compiling and linking you application
+\page compilinglinking Compiling and linking your application
Binaries intended to be run with applauncherd should be compiled with -fPIC option
to produce position independent code. In order to produce a position independent
@@ -313,103 +247,6 @@ Here is a launch example for a MeeGo Touch application:
/usr/bin/invoker --type=m
\endverbatim
-\section dbus D-Bus launch
-
-If you are using D-Bus to launch your application, it can be done
-straightly in the .service-file and without any wrapper scripts slowing
-things down:
-
-\verbatim
- [D-BUS Service]
- Name=com.nokia.
- Exec=/usr/bin/invoker --type=m /usr/bin/
-\endverbatim
-
-By default, invoker waits for the application to terminate and exits with
-the same exit code. Unix signals are also forwarded.
-
-Note 1: If --no-wait and --delay is used, it is important to add enough delay to
-invoker so that it won't exit before the launched application gets its
-(possible) D-Bus service registered. Otherwise D-Bus daemon may think that the
-application just died.
-
-Note 2: There is a slight difference in the application start-up time if you use a
-wrapper script instead of the actual binary in Exec-field of .desktop and .service files.
-Therefore, it is recommended that you always use the actual invoker call with the
-binary name as presented above.
-
-Note 3: 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 for simple applications that do not
-provide D-Bus services, it is not recommended to have the X-Maemo-Service field
-inside .desktop. Singe instance launch should be used instead (see below).
-
-See invoker --help for all possible command-line parameters.
-
-\page singleinstance Single instance launch
-
-Usually user wants his application to be run as a single instance. This means,
-that if the launched application is already running, the existing application
-window is activated and no new application processes are started.
-
-This can be achieved by adding --single-instance to the invoker command:
-
-\verbatim
- [D-BUS Service]
- Name=com.nokia.
- Exec=/usr/bin/invoker --single-instance --type=m /usr/bin/
-\endverbatim
-
-As a result, a lock file
-\c /var/run/single-instance-locks/\/instance.lock is created.
-If applauncherd cannot acquire the lock, it tries to find the corresponding
-window and activates it.
-
-This functionality is implemented in a position-independent executable called
-single-instance. Applauncherd uses this executable as a library, but it can be
-used as an ordinary program to start anything as a single instance:
-
-\verbatim
- /usr/bin/single-instance
-\endverbatim
-
-Note, that in this case the launcher is not used.
-
-Consider using --single-instance instead of the single instance functionality
-provided by D-Bus, because it very likely is much faster.
-
-\page splash Splash screen
-
-Applauncherd supports showing a splash screen if there is mcompositor
-(the MeeGo window manager) 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
-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,
-
-\verbatim
-/usr/bin/invoker --splash=/usr/share/application_name/splash.jpg --splash-landscape=/usr/share/application_name/splash-l.jpg --type=m /usr/bin/application_name
-\endverbatim
-
-shows the splash screen with splash.jpg as its content when the device
-is in the portrait orientation. Otherwise splash-l.jpg is shown. If
-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
-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
-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.
-
\page usingboosters Using boosters
The booster processes can speed up application startup by doing some
@@ -461,35 +298,10 @@ Boot mode can be activated also by sending SIGUSR2 Unix signal to the launcher.
Applauncherd logs to syslog.
Additional debug messages and logging also to stdout can be enabled with --debug.
-
-\page security Platform security (Aegis)
-
-If your application does not have an Aegis manifest file, no actions are required.
-
-All security tokens requested for the application must be requested also for
-applauncherd.bin in the application's Aegis manifest file.
-
-
\page dependencies Package Dependencies
Applications using the launcher must depend on the applauncherd package.
-\page knownissues Current known issues
-
-\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().
-
-\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.
-
-
\page otherboosters Other boosters
Warning: behavior of these boosters is subject to change.
@@ -517,192 +329,4 @@ applauncherd --help
See MeeGo Touch documentation for fast application startup.
-\page qmlboost Using the QML booster
-
-This is a step by step guide to using \c applauncherd to boost your QML application.
-
-\section qmlboostprereq Prerequisites
-
- - 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.
- - \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
-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
-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
-visible. This can be done as follows:
-
-\code
- #include
-
- Q_DECL_EXPORT int main(int argc, char **argv)
- {
- ...
- }
-\endcode
-
-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
-a Debian package, make your package build-depend on \c
-applauncherd-dev.
-
-\subsection qmlboostqmake Using QMake
-
-If you are using \c QMake, obtaining the correct compiler and linker
-flags is just a matter of adding a suitable configuration option:
-
-\code
- CONFIG += qdeclarative-boostable
-\endcode
-
-If you want to use \c pkg-config directly for some reason (like getting
-error messages), you can add explicit \c pkg-config calls in the appropriate
-flags:
-
-\code
- QMAKE_CXXFLAGS += `pkg-config --cflags qdeclarative-boostable`
- QMAKE_LFLAGS += `pkg-config --libs qdeclarative-boostable`
-\endcode
-
-You can also manually set the options in your .pro file like this:
-
-\code
- QMAKE_CXXFLAGS += -fPIC -fvisibility=hidden -fvisibility-inlines-hidden
- QMAKE_LFLAGS += -pie -rdynamic
-\endcode
-
-Note that you have to update the flags manually if there are any changes in
-the required flags.
-
-\subsection qmlboostcmake Using CMake
-
-You can utilize \c pkg-config in \c CMake by including \c FindPkgConfig in \c CMakeLists.txt:
-
-\code
- include(FindPkgConfig)
-\endcode
-
-To obtain the compiler and linker flags, add the following lines in \c CMakeLists.txt:
-
-\code
- pkg_check_modules(QDECLARATIVE_BOOSTABLE REQUIRED qdeclarative-boostable)
- add_definitions(${QDECLARATIVE_BOOSTABLE_CFLAGS})
- link_libraries(${QDECLARATIVE_BOOSTABLE_LDFLAGS})
-\endcode
-
-If you do not want to use \c pkg-config for some reason, you can manually add the
-compiler and linker flags like this:
-
-\code
- set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -fPIC -fvisibility=hidden
- -fvisibility-inlines-hidden")
- set(CMAKE_EXE_LINKER_FLAGS "-pie -rdynamic")
-\endcode
-
-Again, this requires you to update the flags if something changes.
-
-\subsection qmlboostpkgconfig Automatic settings with pkg-config (any build system)
-
-The correct flags can be automatically obtained with:
-
-\code
- pkg-config --cflags qdeclarative-boostable
- pkg-config --libs qdeclarative-boostable
-\endcode
-
-\section qmlboostcache 2. Utilizing 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
-pick up the instances from the cache. Thus, if the application code
-instantiates the classes as
-
-\code
- QApplication app;
- QDeclarativeView view;
-\endcode
-
-It needs to be modified into:
-
-\code
- QApplication *app = MDeclarativeCache::qApplication(argc, argv);
- QDeclarativeView *window = MDeclarativeCache::qDeclarativeView();
-\endcode
-
-You also need to:
-\code
- #include
-\endcode
-
-The cache class works both with the booster and without it. In the
-non-boosted case there are no pre-created instances, so the cache
-class simply creates the instances on the fly.
-
-The ownership of the instances is transferred from the cache to the
-application code. The instances need to be deleted in the correct
-order, deleting the \c QApplication instance before the \c
-QDeclarativeView instance is known to cause crashes.
-
-\section qmlboostinvoker 3. Launching the application
-
-Now everything should be in place for launching the application. The
-linker flags create a Position Independent Binary (PIE), so the
-application can still be invoked from the command line. In order to
-verify that the modifications done to the application and the build
-scripts have not broken anything, it is a good idea at this point to
-check that the application still starts and functions normally from
-the command line:
-
-\code
-$ ./myApp
-\endcode
-
-The next step is to use the \c invoker to launch the application. In
-order for this to work, you need to have \c applauncherd and \c
-booster-d (the QML booster process) running. To check that this is the
-case, you can do:
-
-\code
-$ 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
-be running as part of the UI session.
-
-Once you have verified that the booster process is running, you can
-use the following command line to ask the booster process to turn into
-your application:
-
-\code
-/usr/bin/invoker --type=d ./myApp
-\endcode
-
-Your application should start exactly as if it had been invoked from
-the command line, just a little bit faster. You can now proceed to
-change the \c .desktop file or \c .service file that launches the
-application to use the invoker command.
-
-\section qmlboostsplas 4. Adding a splash screen
-
-The invoker can also provide a splash screen for you application as follows. For more details on splash screen, see \subpage splash "the splash screen documentation."
-
-\code
-/usr/bin/invoker --splash=/usr/share/myApp/splash.jpg --type=d /usr/bin/myApp
-\endcode
-
*/
diff --git a/doc/qmlboost.dox b/doc/qmlboost.dox
new file mode 100644
index 0000000..034ee00
--- /dev/null
+++ b/doc/qmlboost.dox
@@ -0,0 +1,188 @@
+/*! \page qmlboost Using the QML booster
+
+\section qmlboostprereq Prerequisites
+
+ - 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.
+ - \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
+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
+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
+visible. This can be done as follows:
+
+\code
+ #include
+
+ Q_DECL_EXPORT int main(int argc, char **argv)
+ {
+ ...
+ }
+\endcode
+
+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
+a Debian package, make your package build-depend on \c
+applauncherd-dev.
+
+\subsection qmlboostqmake Using QMake
+
+If you are using \c QMake, obtaining the correct compiler and linker
+flags is just a matter of adding a suitable configuration option:
+
+\code
+ CONFIG += qdeclarative-boostable
+\endcode
+
+If you want to use \c pkg-config directly for some reason (like getting
+error messages), you can add explicit \c pkg-config calls in the appropriate
+flags:
+
+\code
+ QMAKE_CXXFLAGS += `pkg-config --cflags qdeclarative-boostable`
+ QMAKE_LFLAGS += `pkg-config --libs qdeclarative-boostable`
+\endcode
+
+You can also manually set the options in your .pro file like this:
+
+\code
+ QMAKE_CXXFLAGS += -fPIC -fvisibility=hidden -fvisibility-inlines-hidden
+ QMAKE_LFLAGS += -pie -rdynamic
+\endcode
+
+Note that you have to update the flags manually if there are any changes in
+the required flags.
+
+\subsection qmlboostcmake Using CMake
+
+You can utilize \c pkg-config in \c CMake by including \c FindPkgConfig in \c CMakeLists.txt:
+
+\code
+ include(FindPkgConfig)
+\endcode
+
+To obtain the compiler and linker flags, add the following lines in \c CMakeLists.txt:
+
+\code
+ pkg_check_modules(QDECLARATIVE_BOOSTABLE REQUIRED qdeclarative-boostable)
+ add_definitions(${QDECLARATIVE_BOOSTABLE_CFLAGS})
+ link_libraries(${QDECLARATIVE_BOOSTABLE_LDFLAGS})
+\endcode
+
+If you do not want to use \c pkg-config for some reason, you can manually add the
+compiler and linker flags like this:
+
+\code
+ set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -fPIC -fvisibility=hidden
+ -fvisibility-inlines-hidden")
+ set(CMAKE_EXE_LINKER_FLAGS "-pie -rdynamic")
+\endcode
+
+Again, this requires you to update the flags if something changes.
+
+\subsection qmlboostpkgconfig Automatic settings with pkg-config (any build system)
+
+The correct flags can be automatically obtained with:
+
+\code
+ pkg-config --cflags qdeclarative-boostable
+ pkg-config --libs qdeclarative-boostable
+\endcode
+
+\section qmlboostcache 2. Utilizing 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
+pick up the instances from the cache. Thus, if the application code
+instantiates the classes as
+
+\code
+ QApplication app;
+ QDeclarativeView view;
+\endcode
+
+It needs to be modified into:
+
+\code
+ QApplication *app = MDeclarativeCache::qApplication(argc, argv);
+ QDeclarativeView *window = MDeclarativeCache::qDeclarativeView();
+\endcode
+
+You also need to:
+\code
+ #include
+\endcode
+
+The cache class works both with the booster and without it. In the
+non-boosted case there are no pre-created instances, so the cache
+class simply creates the instances on the fly.
+
+The ownership of the instances is transferred from the cache to the
+application code. The instances need to be deleted in the correct
+order, deleting the \c QApplication instance before the \c
+QDeclarativeView instance is known to cause crashes.
+
+\section qmlboostinvoker 3. Launching the application
+
+Now everything should be in place for launching the application. The
+linker flags create a Position Independent Binary (PIE), so the
+application can still be invoked from the command line. In order to
+verify that the modifications done to the application and the build
+scripts have not broken anything, it is a good idea at this point to
+check that the application still starts and functions normally from
+the command line:
+
+\code
+$ ./myApp
+\endcode
+
+The next step is to use the \c invoker to launch the application. In
+order for this to work, you need to have \c applauncherd and \c
+booster-d (the QML booster process) running. To check that this is the
+case, you can do:
+
+\code
+$ 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
+be running as part of the UI session.
+
+Once you have verified that the booster process is running, you can
+use the following command line to ask the booster process to turn into
+your application:
+
+\code
+/usr/bin/invoker --type=d ./myApp
+\endcode
+
+Your application should start exactly as if it had been invoked from
+the command line, just a little bit faster. You can now proceed to
+change the \c .desktop file or \c .service file that launches the
+application to use the invoker command.
+
+\section qmlboostsplas 4. Adding a splash screen
+
+The invoker can also provide a splash screen for you application as follows. For more details on splash screen, see \subpage splash "the splash screen documentation."
+
+\code
+/usr/bin/invoker --splash=/usr/share/myApp/splash.jpg --type=d /usr/bin/myApp
+\endcode
+
+*/
+
diff --git a/doc/qtboost.dox b/doc/qtboost.dox
new file mode 100644
index 0000000..4274343
--- /dev/null
+++ b/doc/qtboost.dox
@@ -0,0 +1,3 @@
+/*! \page qtboost Using the Qt Booster
+*/
+
diff --git a/doc/singleinstance.dox b/doc/singleinstance.dox
new file mode 100644
index 0000000..5eca9b8
--- /dev/null
+++ b/doc/singleinstance.dox
@@ -0,0 +1,34 @@
+/*! \page singleinstance How to enable single instance support for the application
+
+Usually user wants his application to be run as a single instance. This means,
+that if the launched application is already running, the existing application
+window is activated and no new application processes are started.
+
+This can be achieved by adding --single-instance to the invoker command:
+
+\verbatim
+ [D-BUS Service]
+ Name=com.nokia.
+ Exec=/usr/bin/invoker --single-instance --type=m /usr/bin/
+\endverbatim
+
+As a result, a lock file
+\c /var/run/single-instance-locks/\/instance.lock is created.
+If applauncherd cannot acquire the lock, it tries to find the corresponding
+window and activates it.
+
+This functionality is implemented in a position-independent executable called
+single-instance. Applauncherd uses this executable as a library, but it can be
+used as an ordinary program to start anything as a single instance:
+
+\verbatim
+ /usr/bin/single-instance
+\endverbatim
+
+Note, that in this case the launcher is not used.
+
+Consider using --single-instance instead of the single instance functionality
+provided by D-Bus, because it very likely is much faster.
+
+*/
+
diff --git a/doc/splash.dox b/doc/splash.dox
new file mode 100644
index 0000000..a83e49d
--- /dev/null
+++ b/doc/splash.dox
@@ -0,0 +1,34 @@
+/*! \page splash How To Enable Splash Screen For The Application
+
+Applauncherd supports showing a splash screen if there is mcompositor
+(the MeeGo window manager) 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
+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,
+
+\verbatim
+/usr/bin/invoker --splash=/usr/share/application_name/splash.jpg --splash-landscape=/usr/share/application_name/splash-l.jpg --type=m /usr/bin/application_name
+\endverbatim
+
+shows the splash screen with splash.jpg as its content when the device
+is in the portrait orientation. Otherwise splash-l.jpg is shown. If
+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
+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
+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.
+
+*/
+
diff --git a/doc/technical.dox b/doc/technical.dox
new file mode 100644
index 0000000..353322a
--- /dev/null
+++ b/doc/technical.dox
@@ -0,0 +1,57 @@
+/*! \page technical Technical Overview
+
+!! TODO: Do something to this mess !!
+
+In Harmattan, the applauncherd daemon is started by UpStart as part of
+XSession, that is, at the same level as the desktop (MeeGo Touch
+homescreen). In MeeGo, applaucherd is started by uxlaunch which is the
+program that brings up X and the ui.
+
+Applauncherd forks will-be-application processes, "boosters", before knowing
+which application is going to be launched next. Different boosters are
+optimized for different kinds of applications, e.g. Qt, Meego Touch, Qt
+Declarative. Boosters are loaded as plugins. Applauncherd searches for plugin
+libraries in /usr/lib/applaucherd/lib*booster.so and forks a new process for
+each booster to wait for launch commands from the user.
+
+The user uses the launcher always through a special invoker program. The
+invoker (/usr/bin/invoker) uses a socket connection to tell a booster process
+to load an application binary.
+
+In addition to possible source code changes, an application which is to be used
+with applauncherd must be compiled as a shared library or a position
+independent executable (-pie) and it must always export main().
+
+Before loading an application binary, a booster process changes its security
+credentials so that the code in the application binary will be executed with
+the correct credentials. The process also sets environment variables to the
+values sent by the invoker. Loading the binary is done with dlopen(), and
+therefore the application needs to be compiled and linked as a shared library
+or a position independent executable. Finally, the booster process finds the
+main function in the application binary with dlsym() and calls the main() with
+the command line arguments given by the invoker.
+
+The launcher itself is a library that is loaded by a small C-program (/usr/bin/applauncherd.bin).
+The idea behind this is to avoid linking the launcher binary to any
+libraries. This gives full control over the flags with which the preloaded
+libraries are opened with dlopen().
+
+In Harmattan, Aegis platform security is used to protect the socket connection
+between the invoker and boosters. This works only for ARM target. It is
+automatically disabled by the build scripts when compiling on x86.
+
+Each application type (currently Qt, Qt Declarative and MeeGo Touch) has its own booster process.
+When booster launches the application by calling the "main()" function,
+applauncherd will create new booster process of that type.
+
+Booster processes do some initializations that cannot be shared among other
+processes and therefore have to be done after forking. This allows, for instance,
+instantiating an MApplication (QApplication) before knowing the name of the
+application. Then the booster process waits for a connection from the invoker with
+the information about which application should be launched.
+
+With MeeGo Touch booster and Qt Declarative booster, applications can fetch certain objects from a cache.
+This will significantly reduce the startup time of an application.
+
+*/
+