README

   1 GENIVI_CommonAPI-D-Bus
   2 ======================
   3 :Author: Juergen Gehring - juergen.gehring@bmw.de, Manfred Bathelt - manfred.bathelt@bmw.de
   4 :doctitle: GENIVI_CommonAPI-D-Bus
   5
   6 Copyright
   7 ---------
   8 Copyright (C) 2013, GENIVI Alliance, Inc.
   9 Copyright (C) 2013, BMW AG
  10
  11 This file is part of GENIVI Project IPC Common API.
  12
  13 Contributions are licensed to the GENIVI Alliance under one or more
  14 Contribution License Agreements or MPL 2.0 .
  15
  16 (C) Copyright
  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/.
  20
  21 For further information see https://collab.genivi.org/wiki/display/genivi/SysInfraEGCommonIDLCommonAPIGuide
  22
  23 == License
  24 This project is licensed under MPL 2.0
  25
  26 Contribution is done under GENIVI CLA or MPL2.0.
  27
  28 == Version
  29 The current version can be taken from the git.
  30
  31 == Common API Overview
  32
  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:
  35 ----
  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.
  45 ----
  46 == Build Instructions
  47
  48 === Requirements
  49
  50 To build this package the CommonAPI library and a version of libdbus patched with the marshaling patch must be available through PkgConfig.
  51
  52 Instructions for making a patched version of libdbus available in /usr/local:
  53 ----
  54 # wget http://dbus.freedesktop.org/releases/dbus/dbus-1.4.16.tar.gz
  55
  56 # tar -xzf dbus-1.4.16.tar.gz
  57
  58 # cd dbus-1.4.16
  59
  60 # patch -p1 < /path/to/dbus-DBusMessage-add-support-for-custom-marshaling.patch
  61
  62 # ./configure --prefix=/usr/local
  63
  64 # make -C dbus
  65
  66 # sudo make -C dbus install
  67 # sudo make install-pkgconfigDATA
  68 ----
  69 The path to CommonAPI and patched libdbus pkgconfig files must be added to the PKG_CONFIG_PATH for the entire build process.
  70
  71 For example, if CommonAPI and patched dbus are available in /usr/local, set the PKG_CONFIG_PATH variable as follows:
  72 ----
  73 # export PKG_CONFIG_PATH="/usr/local/lib/pkgconfig:$PKG_CONFIG_PATH"
  74 ----
  75
  76 === Instructions
  77 Use autotools to build this package withthe above requirements available through Pkgconfig :
  78 ----
  79 # autoreconf -i
  80 # ./configure
  81 # make
  82 # sudo make install (or alternative install process, eg. checkinstall on debian-based distributions, such as Ubuntu)
  83 ----
  84 To build the Windows version with Visual Studio, you can use the solution file CommonAPI-DBus.sln. It is configured to build CommonAPI-DBus as a static library.
  85 Set the environment variable DBUS_DIR to the directory containing your patched DBus sources.
  86 Set the environment variable DBUS_BUILD_DIR to the directory containing your built DBus.
  87 Add the path of CommonAPI.lib to "Additional Library Directories"
  88
  89 To run the tests, you need to add the location of your built dbus-1d.dll to the PATH environment variable
  90
  91 == Linking against CommonAPI-D-Bus
  92
  93 CommonAPI-D-Bus requires successful activation of all static initialization code on library load. Therefore it is necessary to
  94 activate certain linker flags to ensure this is always the case. These are specified in the pkg-config files, but are also
  95 listed here. In case of dynamic linking (.so) --no-as-needed must be specified for the CommonAPI-D-Bus library:
  96 ----
  97 -Wl,--no-as-needed -lCommonAPI-DBus -Wl,--as-needed
  98 ----
  99
 100 In case of static linking --whole-archive must be specified:
 101 ----
 102 -Wl,--whole-archive libCommonAPI-DBus.a -Wl,--no-whole-archive
 103 ----
 104
 105 === Linking generated proxies & stubs
 106
 107 Generated proxies and stubs also require successful activation of all static initialization code on load.
 108 If they are provided in either a static or dynamic library to the application they must also be linked wrapped in the
 109 flags described above.
 110
 111 === Building and executing the Unit Tests
 112 ----
 113 # export GTEST_CONFIG=/path/to/gtest-1.6.0/scripts/gtest-config
 114 # autoreconf -i
 115 # ./configure
 116 # make check
 117 ----
 118 In order to execute the unit tests, the test framework "Google Test" (available at https://code.google.com/p/googletest/)
 119 needs to be available on your system. Google Test comes with a subfolder called "scripts", there you will find a file called
 120 "gtest-config". The path to this script has to be set via the environment variable GTEST_CONFIG. After having done so,
 121 CommonAPI and CommonAPI-D-Bus can be built and the make command "check" can be executed.
 122
 123 "make check" builds and executes all tests. As the tests are developed as regression tests, the test output is limited to
 124 "OK" and "ERROR" for each test performed.
 125
 126
 127 == Configuring the D-Bus middleware binding
 128
 129 === Well known name
 130 The well known name that may be used to identify and dynamically load the D-Bus middleware binding is "DBus".
 131
 132
 133 === Defining D-Bus Service Parameters
 134 Normally, a CommonAPI address, format
 135 ----
 136 <Domain>:<ServiceID>:<InstanceID>
 137 ----
 138
 139 is mapped to a D-Bus address the following way:
 140 ----
 141 # D-Bus Interface Name = ServiceID
 142 # D-Bus Connection Name = InstanceID
 143 # D-Bus Object Path = InstanceID with a preceding '/' and all '.' replaced with '/'
 144 ----
 145 For Domain, only the value "local" is allowed in this context, and it has no influence on the associated D-Bus service address values.
 146
 147 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
 148 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
 149 per binary or globally for all binaries. If more than one config file is defined and a CommonAPI address is defined more than once
 150 across several config files, the locally defined values override the global ones. If a CommonAPI address is defined more than once
 151 within a single file, the first definition found will be the only definition used.
 152
 153 Note: Only one managing interface can be defined per D-Bus object path!
 154
 155 CommonAPI D-Bus Config files have to be named this way:
 156 ----
 157 # Binary local: "<FqnOfBinary>_dbus.conf", e.g. "/usr/bin/myBinary_dbus.conf" if the binary is "/usr/bin/myBinary"
 158 # Binary global: "/etc/CommonApiDBus/<NameOfBinary>_dbus.conf", e.g. "/etc/CommonApiDBus/myBinary_dbus.conf"
 159 # Global: "/etc/CommonApiDBus/dbusAddresses.conf"
 160 ----
 161
 162 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:
 163 ----
 164 [<CommonAPI Address>]
 165 dbus_connection=<valid D-Bus Connection Name>
 166 dbus_object=<valid D-Bus Object Path>
 167 dbus_interface=<valid D-Bus Interface Name>
 168 dbus_predefined=<true/false>
 169 ----
 170 All "dbus_*"-values are optional. For each such omitted value the default value as described above will be used. For "dbus_predefined",
 171 the default value is "false".
 172
 173 "dbus_predefined" should be used if the associated service of a proxy is a legacy service that does not provide the
 174 "org.freedesktop.DBus.ObjectManager" interface.
 175 ----
 176 # If "dbus_predefined" is set to "false" (which is default), a proxy will try to verify the existence of the specific interface
 177   at the specific connection name and object path, using the "org.freedesktop.DBus.ObjectManager" interface, before it is marked as available.
 178 # If "dbus_predefined" is set to "true", a proxy is marked as available as soon as the connection name of the associated
 179   service is visible. No further checks will be performed.
 180 ----
 181
 182 === Defining D-Bus Factory Parameters
 183 If a section in a config file starts with "factory$", it defines a factory configuration, which can be referred to at factory creation.
 184 The name of the factory configuration follows the $ sign.
 185 ----
 186 [factory$<Factory Name>]
 187 dbus_bustype=<valid D-Bus Bustype>
 188 ----
 189 All "dbus_*"-values are optional. For each such omitted value the default value as described below will be used.
 190
 191 # dbus_bustype may be set to "session" or "system" for communication on the user's session bus or on the system wide bus. The default value is "session"
 192
 193 == Remarks on Windows version
 194
 195 On Windows systems there are some drawbacks:
 196 # Calling disconnect and later connect on the same DBusConnection somehow damages the libdbus connection. On Linux
 197 implementation this all works fine.
 198 # The DBusLoadTest revealed that a number of more than about 50 proxies slows down the dbus communication
 199 significantly. That's why we run the DBusLoadTest on windows with just 50 instead of 100 proxies.
 200
 201 == Working on the code & contribution
 202
 203 .First get the code from the git:
 204         git clone
 205
 206 .Get an overview of all branches:
 207         git branch
 208
 209 .Switch to the branch you want to work on (master is the feature branch) and verify that it has switched (* changed)
 210         git checkout <your branch>
 211         git branch
 212
 213 .Best practice is to create a local branch based on the current branch:
 214         git branch working_branch
 215
 216 Start working, best practice is to commit smaller, compilable pieces during the development process that makes it easier to handle later on.
 217
 218 .If you want to commit you changes, send them to the author, you can create a patch like this:
 219         git format-patch working_branch <your branch>
 220
 221 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.
 222
 223 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