
  $Id: README 13220 2007-08-15 17:43:06Z guillem $


What is the maemo-launcher?
===========================

The maemo-launcher is a daemon to speedup applications startup time and
memory sharing between processes. It supports booster modules, which are
the ones in charge of preinitializing and keeping the interesting state.

The only current useful booster module is for gtk, with an option to
link against the hildon library to speedup symbol resolving. This module
preinitializes components like pango and cairo.

When an application is invoked, it forks, tries to restore the state it
might have saved during the preinitialization step and the environment as
if it had been started directy, dynamically opens the application, and
afterwards launches the application by calling the "main" function. The
maemo-invoker will proxy the application exit status back by default.

The launcher is listening to a unix socket for notifications of new
applications to be launched. The maemo-invoker is the program in charge to
notify the launcher of which application to run.

Read the man pages for further information.


Current known issues
====================

If maemo-invoker has been told not to wait for the application to exit and
use a delay instead and that application takes too much time to register the
DBUS service the maemo-invoker may have exited already, so dbus will not
allow the application to register it after the process it has started has
finished already.

Binaries intended to be run by maemo-launcher must be linked with the
"-pie -rdynamic" linker flags if they should transparently work as
executables and dlopen()-able objects. If running them as executable is not
a requirement, "-rdynamic" or "-shared" is good enough.

gnome_vfs_init() cannot be called by the daemon because it opens a pipe to
the vfs daemon.

Children using GThread should use

  if (!g_thread_supported())
    g_thread_init(NULL);

to be safe against possible future changes in maemo-launcher.

The children are dlopen()ed using RTLD_LAZY, so symbol relocation errors are
not caught at the time we call dlopen(). Instead, the child will crash
randomly at any later point if the libraries it depends on are somehow messed.


Integrating the maemo-launcher painlessly
=========================================

These are the detailed changes needed to add support for the new
maemo-launcher.

The changes are meant for normal Maemo packages using automake. If yours
differ feel free to contact me (Guillem Jover <guillem.jover@nokia.com>)
and I can help you on the process.


Upstream Changes
----------------

On configure.ac (or the deprecated configure.in) add something like:

---X<---
AC_ARG_ENABLE([maemo-launcher],
              [AS_HELP_STRING([--enable-maemo-launcher],
                              [build with maemo-launcher support])],
                              [case "${enableval}" in
                               yes) maemo_launcher=true ;;
                               no)  maemo_launcher=false ;;
                               *) AC_MSG_ERROR([bad value ${enableval} for --enable-maemo-launcher]) ;;
                               esac], [maemo_launcher=false])

if test x$maemo_launcher = xtrue
then
	PKG_CHECK_MODULES(MAEMO_LAUNCHER, [maemo-launcher-app])
	AC_SUBST(MAEMO_LAUNCHER_CFLAGS)
	AC_SUBST(MAEMO_LAUNCHER_LIBS)
fi
---X<---

On the Makefile.am that is creating the final application binary, add to
the application_CFLAGS variable:

	$(MAEMO_LAUNCHER_CFLAGS)

And to the the application_LDFLAGS variable:

	$(MAEMO_LAUNCHER_LDFLAGS)


Debian Changes
--------------

* debian/control:

  - Add 'maemo-launcher-dev (>= 0.23-1)' to Build-Depends.

  - Add a "${launcher:Depends} to the "Depends:" line of the package
    containing the application to be launched.

* debian/rules:

  - At the top of the file around other code processing DEB_BUILD_OPTIONS,
    add:

---X<---
ifeq (,$(findstring nolauncher,$(DEB_BUILD_OPTIONS)))
       conf_opt := --enable-maemo-launcher
endif
---X<---

  - On the configure call, add $(conf_opt), so that it becomes something
    like:

---X<---
	./configure --enable-foo --enable-bar $(conf_opt)
---X<---

  - On the binary target producing the package with launcherized files,
    add a call to dh_maemolauncher.

  - Add a debian/package.launcher or debian/launcher (for sources producing
    single binary package) with the list of binaries that are being built
    with maemo-launcher support. Some example content:

---X<---
/usr/bin/application-foo
/usr/bin/application-bar
---X<---


Development and testing
=======================


Testing w/o launcher support
----------------------------

Sometimes during development, or in some cases when bugs appear, and one
wants to discard the launcher from the diangosis, it's useful to be able
to disable it. This can be done by building with the following command
line:

	DEB_BUILD_OPTIONS=nolauncher dpkg-buildpackage -us -uc -b

