IPC CommonAPI C++ Tools
-----------------------
:Author: Juergen Gehring - juergen.gehring@bmw.de, Manfred Bathelt - manfred.bathelt@bmw.de
:doctitle: IPC CommonAPI C++ Tools
:version:

Copyright
+++++++++
Copyright (C) 2014, BMW AG.
Copyright (C) 2014, GENIVI Alliance, Inc.
This file is part of GENIVI Project IPC Common API C++ Tools.
 
Contributions are licensed to the GENIVI Alliance under one or more Contribution License Agreements or MPL 2.0.

License
+++++++ 
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/.

Version
+++++++
{version}

Further information
+++++++++++++++++++
Source code and latest news can be found at http://projects.genivi.org/commonapi/.

Common API Overview
~~~~~~~~~~~~~~~~~~~

Common API C++ 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 which mechanism is used. It currently consists of four sub-projects:

*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 the generation of C++ code from Franca IDL. 

*CommonAPI-D-Bus* - This is the D-Bus binding C++ library, which provides the necessary code to communicate over D-Bus. This is invisible to the application code, and simply needs to be linked against. 

*CommonAPI-D-Bus-Tools* - The eclipse based tools for CommonAPI D-Bus. This is the code generator for Franca IDL to Common API D-Bus C++ code.

Usage Instructions
~~~~~~~~~~~~~~~~~~

The simplest way to use the CommonAPI Tools is to add the update site available on the GENIVI project servers to your Eclipse. This is available under:

Help->Install New Software->Add Button

Enter the following URL: http://docs.projects.genivi.org/yamaica-update-site/CommonAPI/updatesite/ and confirm. 

This provides CommonAPI, CommonAPI-D-Bus and all dependencies.

Then select the newly added site in the site selection dropdown box, and in the Software selection window, select the entire "GENIVI Common API" Tree.

After the software has been installed in Eclipse you can right-click on any .fidl file and generate C++ code for CommonAPI by selecting the "CommonAPI->Generate Common API Code" option.

Build Instructions
~~~~~~~~~~~~~~~~~~

These are Eclipse Plug-In projects which require Xtext2 and Franca as dependencies within Eclipse. 

An automated build process via Maven for the update-site and the command line interface is provided.

As a first step to build the update-site and the commandline generator, make sure that everything is configured correctly, i.e. the dependencies between CommonAPI-D-Bus and CommonAPI itself are set correctly (see the dependencies tab in the MANIFEST.MF file of org.genivi.commonapi.dbus and accordingly in org.genivi.commonapi.dbus.ui). If you don't want to build the CommonAPI-D-Bus-Tools components, you have to adjust the update-site category.xml and the "modules" section in the pom.xml of the org.genivi.commonapi.parent.releng accordingly. 

To build, change into the org.genivi.commonapi.parent.releng directory and run:

----
mvn tycho-versions:set-version -DnewVersion=<version-you-want-to-set>-SNAPSHOT
----

e.g. mvn tycho-versions:set-version -DnewVersion=2.1.4-SNAPSHOT. If the version is already set correctly you can skip this step.

Next, to build the updatesite and the commandline generator, adjust your category.xml in the org.genivi.commonapi.updatesite project to the new version and run

----
mvn clean verify
----

in the org.genivi.commonapi.parent.releng directory. Now every project will be built and the update site will be created in org.genivi.commonapi.updatesite/target/repository/.

If no configuration files are changed, the features

----
org.genivi.commonapi.core
org.genivi.commonapi.validator
org.genivi.commonapi.dbus
org.genivi.commonapi.dbus.validator
----

will be included in the updatesite.

The command line interface will be built for different platforms, with zip-files as generated output. These zip-files can be found in org.genivi.commonapi.cli.product/target/products/.

An osgi based application will be contained in the zip-files. This application should be called as:

----
commonapi_generator [options] file [file...]
                            Valid Options are:
                            -dbus -> to generate files with the FrancaDBUSGenerator
                            -dest path/to/output/folder -> the generated files will be saved at this Location
                            -pref path/to/header/file -> here you can set the text which will be placed as a comment
                            on each generated file (for example your license)
----

Working on the code & contribution
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

- First get the code from the git:
----
git clone
---- 

- Get an overview of all branches:
----
git branch
----

- 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
----

- Best practice is to create a local branch based on the current branch:
----
git branch working_branch
----

Start working, best practice is to commit smaller, compilable pieces during the development process that makes it easier to handle later on.

- 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>
----

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.

Patches can be accepted under 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