Difference between revisions of "Development/Tutorials/D-Bus/Autostart Services"

Jump to: navigation, search
m (s/DBUS/D-Bus)
 
(19 intermediate revisions by 7 users not shown)
Line 1: Line 1:
== Abstract ==
 
  
The D-Bus systems provides a mechanism to autostart applications if they aren't already running when a D-Bus call is made to a service provided by that program. This tutorial demonstrates how to create a D-Bus autostart service and integrate it into your CMake build.
+
{{TutorialBrowser|
  
== Prerequisites ==
+
series=D-Bus|
Technologies:
+
* Qt4
+
* KDE4
+
* D-Bus
+
  
 +
name=Creating and Installing D-Bus Autostart Services|
  
Tutorials:
+
pre=[[../Introduction|Introduction]]<br>[[../Creating Interfaces|Creating Interfaces]]|
* [[Development/Tutorials/Introduction_To_D-Bus|Introduction To D-Bus]]
+
 
* [[Development/Tutorials/Creating D-Bus Interfaces|Creating D-Bus Interfaces]]
+
}}
 +
 
 +
== Abstract ==
 +
 
 +
The D-Bus systems provides a mechanism to autostart applications if they aren't already running when a D-Bus call is made to a service provided by that program. This tutorial demonstrates how to create a D-Bus autostart service and integrate it into your CMake build.
  
 
== The Basic Mechanics ==
 
== The Basic Mechanics ==
Line 24: Line 24:
 
== Creating a Service File ==
 
== Creating a Service File ==
  
The service files are simple ".ini style" configuration files, much like standard [http://www.freedesktop.org/wiki/Standards_2fdesktop_2dentry_2dspec .desktop file].
+
The service files are simple ".ini style" configuration files, much like standard [http://www.freedesktop.org/wiki/Standards_2fdesktop_2dentry_2dspec .desktop files].
  
 
A valid service file:
 
A valid service file:
Line 33: Line 33:
 
The contents of an example service file for an application called MyApp might look like this:
 
The contents of an example service file for an application called MyApp might look like this:
  
<code>
+
<syntaxhighlight lang="ini">
 
[D-BUS Service]
 
[D-BUS Service]
 
Name=org.kde.myapp
 
Name=org.kde.myapp
 
Exec=/usr/bin/myapp
 
Exec=/usr/bin/myapp
</code>
+
</syntaxhighlight>
  
 
The Name and Exec keys will be familiar to anyone who has worked with .desktop files before. Unlike .desktop files, though, the Exec line must contain the full path to the application that is to be started.
 
The Name and Exec keys will be familiar to anyone who has worked with .desktop files before. Unlike .desktop files, though, the Exec line must contain the full path to the application that is to be started.
Line 49: Line 49:
 
We will be using a simple CMake directive to perform the customization and installation. Since the install prefix is not known until build time, we need to adjust our service file slightly. Using the myapp example again, we might create a file called '''org.kde.myapp.service''' that contains the following content:
 
We will be using a simple CMake directive to perform the customization and installation. Since the install prefix is not known until build time, we need to adjust our service file slightly. Using the myapp example again, we might create a file called '''org.kde.myapp.service''' that contains the following content:
  
<code>
+
<syntaxhighlight lang="ini">
 
[D-BUS Service]
 
[D-BUS Service]
 
Name=org.kde.myapp
 
Name=org.kde.myapp
Exec=@CMAKE_INSTALL_PREFIX@/myapp
+
Exec=@CMAKE_INSTALL_PREFIX@/bin/myapp
</code>
+
</syntaxhighlight>
  
 
In the CMakeLists.txt file we will then add these two lines:
 
In the CMakeLists.txt file we will then add these two lines:
  
<code>
+
<syntaxhighlight lang="text">
 
include(DBusMacros)
 
include(DBusMacros)
 
dbus_add_activation_service(org.kde.myapp.service.in)
 
dbus_add_activation_service(org.kde.myapp.service.in)
</code>
+
</syntaxhighlight>
 
+
As of CMake 2.4.4, this macro does not exist. However, you can put [[this CMake module file]] in the '''cmake/''' directory of your application.
+
  
When '''make install''' is run, a properly formed service file will be generated and installed to the correct location on disk. Your application is now set to be automatically activated when needed.
+
As of CMake 2.6.1, this macro does not exist natively. To make it exist, you can place [[../Accessing_Interfaces/PkgConfigGetVar.cmake|this CMake module file]] in the '''cmake/''' directory of your application, and then you can use the above command.  
  
== Other Resources ==
+
For example, if your application is somewhere in kdebase/workspace, you have to make sure that this cmake module file (which is linked above), exists at kdebase/workspace/cmake/modules/PkgConfigGetVar.cmake.
  
[http://raphael.slinckx.net/blog/documents/dbus-tutorial/ Raphaël Slinckx's D-Bus Auto-activation tutorial]
+
When '''make install''' is run, a properly formed service file will be generated (using the .service file that you have just created), and installed to the correct location on disk. Your application is now set to be automatically activated when needed.

Latest revision as of 13:37, 13 July 2012

Creating and Installing D-Bus Autostart Services
Tutorial Series   D-Bus
Previous   Introduction
Creating Interfaces
What's Next   n/a
Further Reading   n/a

Contents

[edit] Abstract

The D-Bus systems provides a mechanism to autostart applications if they aren't already running when a D-Bus call is made to a service provided by that program. This tutorial demonstrates how to create a D-Bus autostart service and integrate it into your CMake build.

[edit] The Basic Mechanics

Whenever a D-Bus message arrives for the D-Bus server to deliver, it looks for the corresponding service that the message is addressed to on the bus it was sent on.

If no such service is currently registered, it then falls back to looking through files kept in the services directory in the D-Bus data path, e.g. /usr/share/dbus-1/services. It looks through each *.service file one by one for a matching service name. It then uses this file to determine what application to launch, waits for the application to finish launching and then (if all goes well) delivers the message.

All of this happens transparently to the application the message originated with.

[edit] Creating a Service File

The service files are simple ".ini style" configuration files, much like standard .desktop files.

A valid service file:

  • ends with the suffix .service
  • has a [D-BUS Service] group
  • has a Name and Exec key

The contents of an example service file for an application called MyApp might look like this:

[D-BUS Service]
Name=org.kde.myapp
Exec=/usr/bin/myapp

The Name and Exec keys will be familiar to anyone who has worked with .desktop files before. Unlike .desktop files, though, the Exec line must contain the full path to the application that is to be started.

In the above example, if a message was sent to the org.kde.myapp service but such a service had not yet been registered on the bus, then /usr/bin/myapp will be launched. It is then up to myapp to register the proper service on the bus.

[edit] Installing a Service File

Once you have created a service file for your application, place it somewhere in the source tree and add a suffix, such as .in to it. This will allow us to process the file during the build to customize the Exec entry without the risk of overwriting the source file.

We will be using a simple CMake directive to perform the customization and installation. Since the install prefix is not known until build time, we need to adjust our service file slightly. Using the myapp example again, we might create a file called org.kde.myapp.service that contains the following content:

[D-BUS Service]
Name=org.kde.myapp
Exec=@CMAKE_INSTALL_PREFIX@/bin/myapp

In the CMakeLists.txt file we will then add these two lines:

include(DBusMacros)
dbus_add_activation_service(org.kde.myapp.service.in)

As of CMake 2.6.1, this macro does not exist natively. To make it exist, you can place this CMake module file in the cmake/ directory of your application, and then you can use the above command.

For example, if your application is somewhere in kdebase/workspace, you have to make sure that this cmake module file (which is linked above), exists at kdebase/workspace/cmake/modules/PkgConfigGetVar.cmake.

When make install is run, a properly formed service file will be generated (using the .service file that you have just created), and installed to the correct location on disk. Your application is now set to be automatically activated when needed.


This page was last modified on 13 July 2012, at 13:37. This page has been accessed 20,589 times. Content is available under Creative Commons License SA 3.0 as well as the GNU Free Documentation License 1.2.
KDE® and the K Desktop Environment® logo are registered trademarks of KDE e.V.Legal