gitgit.projects.genivi.org / ipc / common-api-dbus-tools.git / blob
? search: re
0544e985b6e4a6c83ddf08969f6475099461bd1e
[ipc/common-api-dbus-tools.git] / docx / CommonAPIDBusCppUserGuide
1 = CommonAPI D-Bus C++ User Guide
2
3 :doctitle: CommonAPI D-Bus C++ User Guide
4 :website: http://projects.genivi.org/commonapi/
5 :version:
6 :date:
7 :toc:
8 :revdate:
9 :imagedir:
10 :cppstr: c++
11
12 == Introduction
13
14 === Aim of this document
15
16 This document complements the CommonAPI tutorial with D-Bus specific information. Please read the base tutorial first.
17
18 == Integration Guide for CommonAPI users
19
20 The following descriptions assume that host and target platform are Linux platforms. However CommonAPI D-Bus supports also Windows as host and target platform. All you need to know for Windows concerning CommonAPI you find in the separate Windows paragraph below at the end of this Integration Guide.
21
22 === Requirements
23
24 CommonAPI was developed for GENIVI and will run on most Linux platforms. Additionally it is possible to run it under Windows for test and development purposes. Please note:
25
26 - CommonAPI uses a lot of C++11 features, as variadic templates, std::bind, std::function and so on. Make sure that the compiler of your target platform is able to compile it (e.g. gcc 4.8).
27 - The build system of CommonAPI is CMake; please make sure that it is installed on your host.
28 - Do not use earlier versions of Eclipse as Luna; it could work but there is no warranty.
29 - The build tool chain for the code generators is Maven; make sure that at least Maven 3 is available. If you use eclipse make sure that the maven plug-in is installed.
30
31 The CommonAPI D-Bus binding requires the D-Bus (_libdbus_ at compile time for linking and the running D-Bus daemon at runtime). The D-Bus version should be at least 1.6.x.
32
33 === Dependencies
34 .CommonAPI-D-Bus Dependencies
35 image::{imagedir}/CommonAPI-DBus-Dependencies.png[CommonAPI D-Bus Dependencies image]
36
37 === Restrictions
38
39 - The signature of D-Bus data must not be longer than 255 characters.
40
41 === Compile Runtime
42
43 ==== Patching libdbus
44
45 CommonAPI-D-Bus needs some API functions of libdbus which are not available in actual libdbus versions. For these additional API functions it is necessary to patch the required libdbus version with all the patches provided in the directory src/dbus-patches.
46
47 [NOTE]
48 Use autotools to build libdbus.
49
50 ----
51 $ wget http://dbus.freedesktop.org/releases/dbus/dbus-<VERSION>.tar.gz
52 $ tar -xzf dbus-<VERSION>.tar.gz
53 $ cd dbus-<VERSION>
54 $ patch -p1 < </path/to/CommonAPI-D-Bus/src/dbus-patches/patch-names>.patch
55 $ ./configure --prefix=</path to your preferred installation folder for patched libdbus>
56 $ make -C dbus
57 $ make -C dbus install
58 $ make install-pkgconfigDATA
59 ----
60
61 You can change the installation directory by the prefix option or you can let it uninstalled (skip the +make install+ commands).
62 WARNING: Installing the patched libdbus to /usr/local can prevent your system from booting correctly at the next reboot.
63
64 ==== Command-line
65
66 In order to build the CommonAPI-D-Bus Runtime library the pkgconfig files of the patched libdbus library must be added to the +PKG_CONFIG_PATH+.
67
68 For example, if the patched libdbus library is available in /usr/local, set the +PKG_CONFIG_PATH+ variable as follows:
69
70 ----
71 $ export PKG_CONFIG_PATH="/usr/local/lib/pkgconfig:$PKG_CONFIG_PATH"
72 ----
73
74 Now use CMake to build the CommonAPI D-Bus runtime library. We assume that your source directory is +common-api-dbus-runtime+:
75
76 ----
77 $ cd common-api-dbus-runtime
78 $ mkdir build
79 $ cd build
80 $ cmake -DUSE_INSTALLED_COMMONAPI=ON -DCMAKE_INSTALL_PREFIX=/usr/local ..
81 $ make
82 $ make install
83 ----
84
85 You can change the installation directory by the CMake variable +CMAKE_INSTALL_PREFIX+ or you can let it uninstalled (skip the +make install+ command). If you want to use the uninstalled version of CommonAPI set the CMake variable USE_INSTALLED_COMMONAPI to OFF.
86
87 This is the standard procedure and will hopefully create the shared CommonAPI D-Bus runtime library libCommonAPI-DBus.so in the build directory. Note that CMake checks if doxygen and asciidoc are installed. These tools are only necessary if you want to generate the documentation of your own. The unit tests of CommonAPI D-Bus are implemented by using the Google C++ Testing Framework. If you want to build and run the unit tests the environment variable +GTEST_ROOT+ must point to the correct directory (see the contributor's guide below).
88
89 [NOTE]
90 If you prefer to install CommonAPI D-Bus from a tar file you can get the actual tar file from:
91 http://docs.projects.genivi.org/yamaica-update-site/CommonAPI/runtime/
92
93 There are several options for calling CMake and make targets.
94
95 If you do not want to use nor the installed dbus library and neither the installed CommonAPI library:
96 ----
97 $ cmake -DUSE_INSTALLED_DBUS=OFF -DUSE_INSTALLED_COMMONAPI=OFF ..
98 ----
99
100 Generate makefile for building a static CommonAPI library (default is a shared library). The library will be in _/build/src/CommonAPI/DBus_.
101 ----
102 $ cmake -DBUILD_SHARED_LIBS=OFF ..
103 ----
104
105 Generate makefile for building the release version of CommonAPI D-Bus (default is debug).
106 ----
107 $ cmake -DCMAKE_BUILD_TYPE=Release ..
108 ----
109
110 Without any further settings +make install+ will copy CommonAPI D-Bus libraries and header files to _/usr/local_. You can change this destination directory by changing the installation prefix (e.g. to test).
111 ----
112 $ cmake -DCMAKE_INSTALL_PREFIX=/test ..
113 ----
114
115 Make targets:
116
117 [width="80%",cols="4,10"]
118 |=========================================================
119
120 |+make all+ |
121 Same as make. Will compile and link CommonAPI.
122
123 |+make clean+ |
124 Deletes binaries, but not the files which has been generated by CMake.
125
126 |+make maintainer-clean+ |
127 Deletes everything in the build directory.
128
129 |+make install+ |
130 Copies libraries to _/user/local/lib/commonapiX.X.X_ and header files to _/user/local/include/commonapiX.X.X/CommonAPI_.
131
132 |+make DESTDIR=< install_dir > install+ |
133 The destination directory for the installation can be influenced by +DESTDIR+.
134
135 |=========================================================
136
137 Further make targets will be described in the contributor's guide below.
138
139 ==== Eclipse
140
141 Follow the instructions in the CommonAPI User Guide.
142
143 === Compile tools
144
145 Like the CommonAPI core code generators you can build the D-Bus generator by calling maven from the command-line. Open a console and change in the directory org.genivi.commonapi.dbus.releng of your CommonAPI-D-Bus-Tools directory. Then call:
146
147 ----
148 mvn clean verify –DCOREPATH=<path to your CommonAPI-Tools dir> -Dtarget.id=org.genivi.commonapi.dbus.target
149 ----
150
151 COREPATH is the directory, that contains the target definition folder: org.genivi.commonapi.core.target.
152
153 After the successful build you will find the commond-line generators archived in org.genivi.commonapi.dbus.cli.product/target/products/commonapi_dbus_generator.zip and the update-sites in org.genivi.commonapi.dbus.updatesite/target.
154
155 === Build DBus Glue Code
156
157 The glue code library contains the binding specific, generated code. It depends on your specific project how exactly this library is built (with or without skeleton code, divided up into several libraries, e.g. for services and clients, and so on). The glue code for the verification tests can be built by means of the binding specific verification project (for D-Bus it is _org.genivi.commonapi.dbus.verification_ in CommonAPI-D-Bus-Tools):
158
159 . The cmake call below generates CommonAPI code for all requested fidl files using the CommonAPI- core and DBus code generator. The fidl files for the verification tests can be found in _org.genivi.commonapi.core.verification/fidl_.
160 . Create a build directory for an out of source build.
161 . Call cmake as described below with additional parameters (in eclipse create a make target).
162
163 CMake parameters:
164
165 [width="90%",cols="10,10"]
166 |=========================================================
167
168 |+USE_INSTALLED_COMMONAPI+ |
169 ON or OFF
170
171 |+COMMONAPI_CMAKE_INSTALL_PATH+ |
172 Path to the build directory of CommonAPI (e.g. CommonAPI/build)
173
174 |+COMMONAPI_TOOL_GENERATOR+ |
175 Core code generator executable with path
176
177 |+COMMONAPI_DBUS_TOOL_GENERATOR+ |
178 DBus Code generator executable with path
179
180 |=========================================================
181
182
183 Example to build DBus glue code for the verification tests:
184
185 ----
186 export PKG_CONFIG_PATH=path/to/patched/libdbus:$PKG_CONFIG_PATH
187
188 cd CommonAPI-D-Bus-Tools/org.genivi.commonapi.dbus.verification/
189 mkdir build
190 cd build
191
192 cmake
193 -DCOMMONAPI_TOOL_GENERATOR=myworkpath/CommonAPI-Tools/org.genivi.commonapi.core.cli.product/target/products/org.genivi.commonapi.core.cli.product/linux/gtk/MYARCH/commonapi-generator-linux-MYARCH
194 -DCOMMONAPI_DBUS_TOOL_GENERATOR=myworkpath/CommonAPI-D-Bus-Tools/org.genivi.commonapi.dbus.cli.product/target/products/org.genivi.commonapi.dbus.cli.product/linux/gtk/MYARCH/commonapi-dbus-generator-linux-MYARCH
195 -DCommonAPI_DIR=myworkpath/CommonAPI/build
196 -DCommonAPI-DBus_DIR=myworkpath/CommonAPI-D-Bus/build
197 -DCOMMONAPI_TEST_FIDL_PATH=myworkpath/CommonAPI-Tools/org.genivi.commonapi.core.verification/fidl ..
198
199 make -j4
200 ----
201
202 === Project Setup
203
204 ==== Configuration
205
206 CommonAPI-D-Bus can be configured as CommonAPI itself by an ini-file. The name of this configuration file is +commonapi-dbus.ini+. There are three places where CommonAPI D-Bus Runtime tries to find this file (in the following order):
207
208 1. in the directory of the current executable. If there is a +commonapi-dbus.ini+ file, it has the highest priority.
209 2. in the directory which is specified by the environment variable +COMMONAPI_DBUS_CONFIG+.
210 3. in the global default directory +/etc+.
211
212 The configuration file has 2 possible kinds of sections; all sections are optional.
213
214 ===== Address Translation Sections
215
216 This kind of section determines how CommonAPI addresses are translated into D-Bus addresses (object path, interface name and so on). The name of the section is the CommonAPI address and the parameters are:
217
218 - +service+
219 - +path+
220 - +interface+
221
222 Example:
223
224 ----
225 [local:de.ABC:de.app1]
226 service=de.ABC_de.app1
227 path=/de/app1
228 interface=de.ABC
229 ----
230
231 If there is no address configuration for a certain CommonAPI address available the CommonAPI address will be translated by default as shown in the following picture:
232
233 .D-Bus Addresses
234 image::{imagedir}/DBusAddresses.png[D-Bus Addresses image]
235
236 There might be some confusion concerning the terms and definitions:
237
238 - Franca IDL and CommonAPI define interfaces; these interfaces can be instantiated once or several times in one or several services. The CommonAPI term _interfaceID_ and the D-Bus term _interface name_ are equivalent.
239 - The D-Bus _object path_ is a name used to refer to an object instance. The _object names_ are organized into a filesystem-style hierarchy. The _object path_ corresponds to the CommonAPI _instanceIDs_.
240 - Additionally D-Bus services are "connected" to the bus with an automatically created internal so-called unique bus name (e.g. :1.25). For this bus name one or several well-known names may be defined (here it is called service name). The parameter _service_ in the configuration file defines this well-known name; the default name is _interfaceID___instanceID_.
241
242 ===== Connections
243
244 Section for assigning a certain D-Bus bus segment (Session, System, Starter) to the connection name.
245
246 ==== Deployment
247
248 The D-Bus code generator can generate code completely without any deployment settings. But for the combination of CommonAPI applications and D-Bus applications which are written without CommonAPI there are some deployment parameters necessary.
249
250 [source,java]
251 ----
252 import "platform:/plugin/org.genivi.commonapi.core/deployment/CommonAPI_deployment_spec.fdepl"
253
254 specification org.genivi.commonapi.dbus.deployment extends org.genivi.commonapi.core.deployment {
255 for interfaces {
256 PropertiesType: {CommonAPI, freedesktop} (default: CommonAPI);
257 }
258 }
259 ----
260
261 Use the deployment parameter _PropertiesType_ for the support of implementations of the _org.freedesktop.DBus.Properties_ interface.
262
263 === Windows
264
265 ==== Build D-Bus
266
267 To build the Windows version of D-Bus the following steps have to be done:
268
269 - Download D-Bus from http://www.freedesktop.org/wiki/Software/dbus/ e.g. dbus-1.8.0.tar.gz and unpack the archive into a directory.
270 - For building D-Bus, CMake is needed. Download CMake from http://cmake.org/cmake/resources/software.html. The result of the download is e.g. cmake-2.8.12.2-win32-x86.zip. Unpack the archive into a directory.
271 - Furthermore +expat+ is needed. +Expat+ can be downloaded from http://expat.sourceforge.net. Example: download expat-win32bin-2.1.0.exe from http://sourceforge.net/projects/expat/files/expat_win32/2.1.0 and install it.
272
273
274
275 - Now the Windows D-Bus patch is needed. Download the patch from http://gnuwin32.sourceforge.net/packages/patch.htm e.g. patch-2.5.9-7-setup.exe and install the patch.
276
277 - Apply all the CommonAPI D-Bus patches (located in _CommonAPI-D-Bus/src/dbus-patches_ ) e.g. call
278
279 ----
280 cd dbus-1.8.0
281 find ../CommonAPI-D-Bus/src/dbus-patches/*.patch | xargs -n1 patch -p1 -F3 -i
282 ----
283 (assuming that _CommonAPI-D-Bus_ is on same folder level as _dbus-1.8.0_)
284
285 - Build D-Bus via the CMake command line tool:
286 -- Open the developer command line for VS2013.
287 -- Change into root directory of the unpacked D-Bus archive e.g. dbus-1.8.0.
288 -- Create a new directory dbus-build-dir e.g. +mkdir dbus-build-dir+.
289 -- Change into this new created directory e.g. +cd dbus-build-dir+.
290 -- Create the Visual Studio files for building the D-Bus:
291
292 ----
293 cmake -DEXPAT_INCLUDE_DIR="<expat-path>Sourcelib"
294 -DEXPAT_LIBRARY="<expat-path>Binlibexpat.lib" -G "Visual Studio 12" <DBusSourcenPath>cmake
295 ----
296
297 Example:
298 ----
299 C:Workcmake-2.8.12.2-win32-x86incmake.exe
300 -DEXPAT_INCLUDE_DIR="C:Program Files (x86)Expat 2.1.0Sourcelib"
301 -DEXPAT_LIBRARY="C:Program Files (x86)Expat 2.1.0Binlibexpat.lib"
302 -G "Visual Studio 12" C:Workdbus-1.8.0cmake
303 ----
304
305 The Visual Studio files are created in the directory dbus-build-dir. Open the solution dbus.sln and build all projects. Info for dbus-1.8.0: In file printf.c the #include "test-utils.h" must be changed to #include "test/test-utils.h".
306
307 ==== Build CommonAPI
308
309 To build now the Windows version with Visual Studio 2013, you can use the solution file CommonAPI-DBus.sln. It is configured to build CommonAPI-D-Bus as a static library.
310
311 Before opening the solution file CommonAPI-DBus.sln the following environment variables must be set:
312
313 - DBUS_DIR: directory containing the patched D-Bus sources e.g. <path_to_folder>dbus-1.8.0
314 - DBUS_BUILD_DIR: directory containing the build DBus e.g. <path_to_folder>dbus-1.8.0dbus-build-dir
315 - COMMONAPI_DIR: directory containing the CommonAPI e.g. <path_to_folder>CommonAPI
316
317 To run the tests, you need to add the location of your built dbus-1d.dll or dbus-1.dll (depending on Debug or Release built) to the PATH environment variable.
318
319 ==== Restrictions
320
321 - Calling disconnect and later connect on the same DBusConnection somehow damages the libdbus connection. On Linux implementation this all works fine.
322 - The DBusLoadTest revealed that a number of more than about 50 proxies slows down the dbus communication significantly. That's why we run the DBusLoadTest on windows with just 50 instead of 100 proxies.
323
324
325
326
327
328
Common API for Dbus tools
RSS Atom