-Build Instructions
-==================
+GENIVI_CommonAPI-D-Bus
+======================
+:Author: Juergen Gehring - juergen.gehring@bmw.de, Manfred Bathelt - manfred.bathelt@bmw.de
+:doctitle: GENIVI_CommonAPI-D-Bus
-To build this package CommonAPI and a version of libdbus patched with the marshaling patch must be available.
+Copyright
+---------
+Copyright (C) 2013, GENIVI Alliance, Inc.
+Copyright (C) 2013, BMW AG
+
+This file is part of GENIVI Project IPC Common API.
+
+Contributions are licensed to the GENIVI Alliance under one or more
+Contribution License Agreements or MPL 2.0 .
+
+(C) Copyright
+This Source Code Form is subject to the terms of the
+Mozilla Public License, v. 2.0. If a copy of the MPL was not distributed with
+this file, You can obtain one at http://mozilla.org/MPL/2.0/.
+
+For further information see https://collab.genivi.org/wiki/display/genivi/SysInfraEGCommonIDLCommonAPIGuide
+
+== License
+This project is licensed under MPL 2.0
+
+Contribution is done under GENIVI CLA or MPL2.0.
+
+== Version
+The current version can be taken from the git.
+
+== Common API Overview
+
+Common API and its mechanism specific bindings (e.g. Common API D-Bus) provide a set of libraries and tools to work with
+RPC communication in a way independent of wich mechanism is used. It consist currently consists of four subprojects:
+----
+CommonAPI - This is the base C++ library, which provides the application interface for users and can
+ load runtime bindings such as dbus.
+CommonAPI-Tools - The eclipse based tools for CommonAPI. This is essentially the code generator for
+ Franca -> Common API C++ code.
+CommonAPI-D-Bus - This is the D-Bus binding C++ library, which provides the necesary code to communicate
+ over D-Bus. This is invisible to the application code, and simply needs to be linked against.
+ (This is the current package.)
+CommonAPI-D-Bus-Tools - The eclipse based tools for CommonAPI D-Bus. This is the code generator for
+ Franca -> Common API D-Bus C++ code.
+----
+== Build Instructions
+
+=== Requirements
+
+To build this package the CommonAPI library and a version of libdbus patched with the marshaling patch must be available through PkgConfig.
Instructions for making a patched version of libdbus available in /usr/local:
+----
+# wget http://dbus.freedesktop.org/releases/dbus/dbus-1.4.16.tar.gz
+
+# tar -xzf dbus-1.4.16.tar.gz
+
+# cd dbus-1.4.16
+
+# patch -p1 < /path/to/dbus-DBusMessage-add-support-for-custom-marshaling.patch
+
+# ./configure --prefix=/usr/local
+
+# make -C dbus
+
+# sudo make -C dbus install
+# sudo make install-pkgconfigDATA
+----
+The path to CommonAPI and patched libdbus pkgconfig files must be added to the PKG_CONFIG_PATH for the entire build process.
+
+For example, if CommonAPI and patched dbus are available in /usr/local, set the PKG_CONFIG_PATH variable as follows:
+----
+# export PKG_CONFIG_PATH="/usr/local/lib/pkgconfig:$PKG_CONFIG_PATH"
+----
+
+=== Instructions
+Use autotools to build this package withthe above requirements available through Pkgconfig :
+----
+# autoreconf -i
+# ./configure
+# make
+# sudo make install (or alternative install process, eg. checkinstall on debian-based distributions, such as Ubuntu)
+----
+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.
+
+----
+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.
+Add the path of CommonAPI.lib to "Additional Library Directories"
+
+=== Defining D-Bus Service Parameters
+Normally, a CommonAPI address, format
+----
+<Domain>:<ServiceID>:<InstanceID>
+----
+
+is mapped to a D-Bus address the following way:
+----
+# D-Bus Interface Name = ServiceID
+# D-Bus Connection Name = InstanceID
+# D-Bus Object Path = InstanceID with a preceding '/' and all '.' replaced with '/'
+----
+For Domain, only the value "local" is allowed in this context, and it has no influence on the associated D-Bus service address values.
+
+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
+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
+per binary or globally for all binaries. If more than one config file is defined and a CommonAPI address is defined more than once
+across several config files, the locally defined values override the global ones. If a CommonAPI address is defined more than once
+within a single file, the first definition found will be the only definition used.
+
+Config files have to be named this way:
+----
+# Binary local: "<FqnOfBinary>_dbus.conf", e.g. "/usr/bin/myBinary_dbus.conf" if the binary is "/usr/bin/myBinary"
+# Binary global: "/etc/CommonApiDBus/<NameOfBinary>_dbus.conf", e.g. "/etc/CommonApiDBus/myBinary_dbus.conf"
+# Global: "/etc/CommonApiDBus/dbusAddresses.conf"
+----
+
+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:
+----
+[<CommonAPI Address>]
+dbus_connection=<valid D-Bus Connection Name>
+dbus_object=<valid D-Bus Object Path>
+dbus_interface=<valid D-Bus Interface Name>
+dbus_predefined=<true/false>
+----
+All "dbus_*"-values are optional. For each such omitted value the default value as described above will be used. For "dbus_predefined",
+the default value is "false".
+
+"dbus_predefined" should be used if the associated service of a proxy is a legacy service that does not provide the
+"org.freedesktop.DBus.ObjectManager" interface.
+----
+# If "dbus_predefined" is set to "false" (which is default), a proxy will try to verify the existence of the specific interface
+ at the specific connection name and object path, using the "org.freedesktop.DBus.ObjectManager" interface, before it is marked as available.
+# If "dbus_predefined" is set to "true", a proxy is marked as available as soon as the connection name of the associated
+ service is visible. No further checks will be executed.
+----
+
+
+== Working on the code & contribution
-$ wget http://dbus.freedesktop.org/releases/dbus/dbus-1.4.16.tar.gz
+.First get the code from the git:
+ git clone
-$ tar -xzf dbus-1.4.16.tar.gz
+.Get an overview of all branches:
+ git branch
-$ cd dbus-1.4.16
+.Switch to the branch you want to work on (master is the feature branch) and verify that it has switched (* changed)
+ git checkout <your branch>
+ git branch
-$ patch -p1 <
-/path/to/dbus-DBusMessage-add-support-for-custom-marshaling.patch
+.Best practice is to create a local branch based on the current branch:
+ git branch working_branch
-$ ./configure --prefix=/usr/local
+Start working, best practice is to commit smaller, compilable pieces during the development process that makes it easier to handle later on.
-$ make -C dbus
+.If you want to commit you changes, send them to the author, you can create a patch like this:
+ git format-patch working_branch <your branch>
-$ sudo make -C dbus install
-$ sudo make install-pkgconfigDATA
+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.
-The path to CommonAPI and patched libdbus pkgconfig files must be added to the PKG_CONFIG_PATH for the entire build process.
\ No newline at end of file
+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
projects / profile / ivi / common-api-dbus-runtime.git / blobdiff