3 :Author: Juergen Gehring - juergen.gehring@bmw.de, Manfred Bathelt - manfred.bathelt@bmw.de
4 :doctitle: GENIVI_CommonAPI-D-Bus
8 Copyright (C) 2013, GENIVI Alliance, Inc.
9 Copyright (C) 2013, BMW AG
11 This file is part of GENIVI Project IPC Common API.
13 Contributions are licensed to the GENIVI Alliance under one or more
14 Contribution License Agreements or MPL 2.0 .
17 This Source Code Form is subject to the terms of the
18 Mozilla Public License, v. 2.0. If a copy of the MPL was not distributed with
19 this file, You can obtain one at http://mozilla.org/MPL/2.0/.
21 For further information see https://collab.genivi.org/wiki/display/genivi/SysInfraEGCommonIDLCommonAPIGuide
24 This project is licensed under MPL 2.0
26 Contribution is done under GENIVI CLA or MPL2.0.
29 The current version can be taken from the git.
31 == Common API Overview
33 Common API and its mechanism specific bindings (e.g. Common API D-Bus) provide a set of libraries and tools to work with
34 RPC communication in a way independent of wich mechanism is used. It consist currently consists of four subprojects:
36 CommonAPI - This is the base C++ library, which provides the application interface for users and can
37 load runtime bindings such as dbus.
38 CommonAPI-Tools - The eclipse based tools for CommonAPI. This is essentially the code generator for
39 Franca -> Common API C++ code.
40 CommonAPI-D-Bus - This is the D-Bus binding C++ library, which provides the necesary code to communicate
41 over D-Bus. This is invisible to the application code, and simply needs to be linked against.
42 (This is the current package.)
43 CommonAPI-D-Bus-Tools - The eclipse based tools for CommonAPI D-Bus. This is the code generator for
44 Franca -> Common API D-Bus C++ code.
50 To build this package the CommonAPI library and a version of libdbus patched with the marshaling patch must be available through PkgConfig.
52 Instructions for making a patched version of libdbus available in /usr/local:
54 # wget http://dbus.freedesktop.org/releases/dbus/dbus-1.4.16.tar.gz
56 # tar -xzf dbus-1.4.16.tar.gz
60 # patch -p1 < /path/to/dbus-DBusMessage-add-support-for-custom-marshaling.patch
62 # ./configure --prefix=/usr/local
66 # sudo make -C dbus install
67 # sudo make install-pkgconfigDATA
69 The path to CommonAPI and patched libdbus pkgconfig files must be added to the PKG_CONFIG_PATH for the entire build process.
71 For example, if CommonAPI and patched dbus are available in /usr/local, set the PKG_CONFIG_PATH variable as follows:
73 # export PKG_CONFIG_PATH="/usr/local/lib/pkgconfig:$PKG_CONFIG_PATH"
77 Use autotools to build this package withthe above requirements available through Pkgconfig :
82 # sudo make install (or alternative install process, eg. checkinstall on debian-based distributions, such as Ubuntu)
84 If the environment variable GTEST_CONFIG is set to the path of the gtest-config script in a Gtest tree test will also be built.
86 === Defining D-Bus Service Parameters
87 Normally, a CommonAPI address, format
89 <Domain>:<ServiceID>:<InstanceID>
92 is mapped to a D-Bus address the following way:
94 # D-Bus Interface Name = ServiceID
95 # D-Bus Connection Name = InstanceID
96 # D-Bus Object Path = InstanceID with a preceding '/' and all '.' replaced with '/'
98 For Domain, only the value "local" is allowed in this context, and it has no influence on the associated D-Bus service address values.
100 In case a proxy or a service should not use the default mapping, it is possible to define config files that use the CommonAPI Address
101 as a key in order to map any combination of D-Bus address values to it. The config files can be defined locally per binary, globally
102 per binary or globally for all binaries. If more than one config file is defined and a CommonAPI address is defined more than once
103 across several config files, the locally defined values override the global ones. If a CommonAPI address is defined more than once
104 within a single file, the first definition found will be the only definition used.
106 Config files have to be named this way:
108 # Binary local: "<FqnOfBinary>_dbus.conf", e.g. "/usr/bin/myBinary_dbus.conf" if the binary is "/usr/bin/myBinary"
109 # Binary global: "/etc/CommonApiDBus/<NameOfBinary>_dbus.conf", e.g. "/etc/CommonApiDBus/myBinary_dbus.conf"
110 # Global: "/etc/CommonApiDBus/dbusAddresses.conf"
113 Each config file may have an arbitrary number of entries of the following format, with each entry being separated from the others by a newline:
115 [<CommonAPI Address>]
116 dbus_connection=<valid D-Bus Connection Name>
117 dbus_object=<valid D-Bus Object Path>
118 dbus_interface=<valid D-Bus Interface Name>
119 dbus_predefined=<true/false>
121 All "dbus_*"-values are optional. For each such omitted value the default value as described above will be used. For "dbus_predefined",
122 the default value is "false".
124 "dbus_predefined" should be used if the associated service of a proxy is a legacy service that does not provide the
125 "org.freedesktop.DBus.ObjectManager" interface.
127 # If "dbus_predefined" is set to "false" (which is default), a proxy will try to verify the existence of the specific interface
128 at the specific connection name and object path, using the "org.freedesktop.DBus.ObjectManager" interface, before it is marked as available.
129 # If "dbus_predefined" is set to "true", a proxy is marked as available as soon as the connection name of the associated
130 service is visible. No further checks will be executed.
134 == Working on the code & contribution
136 .First get the code from the git:
139 .Get an overview of all branches:
142 .Switch to the branch you want to work on (master is the feature branch) and verify that it has switched (* changed)
143 git checkout <your branch>
146 .Best practice is to create a local branch based on the current branch:
147 git branch working_branch
149 Start working, best practice is to commit smaller, compilable pieces during the development process that makes it easier to handle later on.
151 .If you want to commit you changes, send them to the author, you can create a patch like this:
152 git format-patch working_branch <your branch>
154 This creates a set of patches that are published via the mailing list.The patches will be discussed and then merged & uploaded on the git by the maintainer.
156 Patches can be accepted either under GENIVI Cla or MPL 2.0 (see section License). Please be sure that the signed-off-by is set correctly. For more, check out http://gerrit.googlecode.com/svn/documentation/2.0/user-signedoffby.html