Add tutorial and makefile to build html documentation

author: Johannes Schanda <schanda@itestra.de> 2013-09-13 15:38:46 +0200
committer: Johannes Schanda <schanda@itestra.de> 2013-09-13 15:41:36 +0200
commit: d2b124232307905bdcda810fabb8bded4253199f (patch)
tree: ee8f2c1f912475a8a13807d95b4b7df2d9116744
parent: bf9ec5ec18591c61c60f8320221e7ebd17ee66f8 (diff)
download: genivi-common-api-runtime-d2b124232307905bdcda810fabb8bded4253199f.tar.gz
3 files changed, 421 insertions, 494 deletions
diff --git a/Makefile b/Makefile
new file mode 100644
index 0000000..672b75c
--- /dev/null
+++ b/Makefile
@@ -0,0 +1,9 @@
+doc:
+	mkdir -p doc/html
+	asciidoc -b html -o doc/html/README.html README
+	asciidoc -b html -o doc/html/Tutorial.html Tutorial
+
+clean:
+	rm doc/html/README.html doc/html/Tutorial.html
+	rmdir doc/html
+	rmdir doc
diff --git a/README.html b/README.html
deleted file mode 100644
index fb1fe5d..0000000
--- a/README.html
+++ /dev/null
@@ -1,494 +0,0 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
-    "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
-<head>
-<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
-<meta name="generator" content="AsciiDoc 8.4.5" />
-<title>GENIVI_CommonAPI-D-Bus</title>
-<style type="text/css">
-/* Debug borders */
-p, li, dt, dd, div, pre, h1, h2, h3, h4, h5, h6 {
-/*
-  border: 1px solid red;
-*/
-}
-
-body {
-  margin: 1em 5% 1em 5%;
-}
-
-a {
-  color: blue;
-  text-decoration: underline;
-}
-a:visited {
-  color: fuchsia;
-}
-
-em {
-  font-style: italic;
-  color: navy;
-}
-
-strong {
-  font-weight: bold;
-  color: #083194;
-}
-
-tt {
-  color: navy;
-}
-
-h1, h2, h3, h4, h5, h6 {
-  color: #527bbd;
-  font-family: sans-serif;
-  margin-top: 1.2em;
-  margin-bottom: 0.5em;
-  line-height: 1.3;
-}
-
-h1, h2, h3 {
-  border-bottom: 2px solid silver;
-}
-h2 {
-  padding-top: 0.5em;
-}
-h3 {
-  float: left;
-}
-h3 + * {
-  clear: left;
-}
-
-div.sectionbody {
-  font-family: serif;
-  margin-left: 0;
-}
-
-hr {
-  border: 1px solid silver;
-}
-
-p {
-  margin-top: 0.5em;
-  margin-bottom: 0.5em;
-}
-
-ul, ol, li > p {
-  margin-top: 0;
-}
-
-pre {
-  padding: 0;
-  margin: 0;
-}
-
-span#author {
-  color: #527bbd;
-  font-family: sans-serif;
-  font-weight: bold;
-  font-size: 1.1em;
-}
-span#email {
-}
-span#revnumber, span#revdate, span#revremark {
-  font-family: sans-serif;
-}
-
-div#footer {
-  font-family: sans-serif;
-  font-size: small;
-  border-top: 2px solid silver;
-  padding-top: 0.5em;
-  margin-top: 4.0em;
-}
-div#footer-text {
-  float: left;
-  padding-bottom: 0.5em;
-}
-div#footer-badges {
-  float: right;
-  padding-bottom: 0.5em;
-}
-
-div#preamble {
-  margin-top: 1.5em;
-  margin-bottom: 1.5em;
-}
-div.tableblock, div.imageblock, div.exampleblock, div.verseblock,
-div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
-div.admonitionblock {
-  margin-top: 1.5em;
-  margin-bottom: 1.5em;
-}
-div.admonitionblock {
-  margin-top: 2.5em;
-  margin-bottom: 2.5em;
-}
-
-div.content { /* Block element content. */
-  padding: 0;
-}
-
-/* Block element titles. */
-div.title, caption.title {
-  color: #527bbd;
-  font-family: sans-serif;
-  font-weight: bold;
-  text-align: left;
-  margin-top: 1.0em;
-  margin-bottom: 0.5em;
-}
-div.title + * {
-  margin-top: 0;
-}
-
-td div.title:first-child {
-  margin-top: 0.0em;
-}
-div.content div.title:first-child {
-  margin-top: 0.0em;
-}
-div.content + div.title {
-  margin-top: 0.0em;
-}
-
-div.sidebarblock > div.content {
-  background: #ffffee;
-  border: 1px solid silver;
-  padding: 0.5em;
-}
-
-div.listingblock > div.content {
-  border: 1px solid silver;
-  background: #f4f4f4;
-  padding: 0.5em;
-}
-
-div.quoteblock {
-  padding-left: 2.0em;
-  margin-right: 10%;
-}
-div.quoteblock > div.attribution {
-  padding-top: 0.5em;
-  text-align: right;
-}
-
-div.verseblock {
-  padding-left: 2.0em;
-  margin-right: 10%;
-}
-div.verseblock > div.content {
-  white-space: pre;
-}
-div.verseblock > div.attribution {
-  padding-top: 0.75em;
-  text-align: left;
-}
-/* DEPRECATED: Pre version 8.2.7 verse style literal block. */
-div.verseblock + div.attribution {
-  text-align: left;
-}
-
-div.admonitionblock .icon {
-  vertical-align: top;
-  font-size: 1.1em;
-  font-weight: bold;
-  text-decoration: underline;
-  color: #527bbd;
-  padding-right: 0.5em;
-}
-div.admonitionblock td.content {
-  padding-left: 0.5em;
-  border-left: 2px solid silver;
-}
-
-div.exampleblock > div.content {
-  border-left: 2px solid silver;
-  padding: 0.5em;
-}
-
-div.imageblock div.content { padding-left: 0; }
-span.image img { border-style: none; }
-a.image:visited { color: white; }
-
-dl {
-  margin-top: 0.8em;
-  margin-bottom: 0.8em;
-}
-dt {
-  margin-top: 0.5em;
-  margin-bottom: 0;
-  font-style: normal;
-  color: navy;
-}
-dd > *:first-child {
-  margin-top: 0.1em;
-}
-
-ul, ol {
-    list-style-position: outside;
-}
-ol.arabic {
-  list-style-type: decimal;
-}
-ol.loweralpha {
-  list-style-type: lower-alpha;
-}
-ol.upperalpha {
-  list-style-type: upper-alpha;
-}
-ol.lowerroman {
-  list-style-type: lower-roman;
-}
-ol.upperroman {
-  list-style-type: upper-roman;
-}
-
-div.compact ul, div.compact ol,
-div.compact p, div.compact p,
-div.compact div, div.compact div {
-  margin-top: 0.1em;
-  margin-bottom: 0.1em;
-}
-
-div.tableblock > table {
-  border: 3px solid #527bbd;
-}
-thead {
-  font-family: sans-serif;
-  font-weight: bold;
-}
-tfoot {
-  font-weight: bold;
-}
-td > div.verse {
-  white-space: pre;
-}
-p.table {
-  margin-top: 0;
-}
-/* Because the table frame attribute is overriden by CSS in most browsers. */
-div.tableblock > table[frame="void"] {
-  border-style: none;
-}
-div.tableblock > table[frame="hsides"] {
-  border-left-style: none;
-  border-right-style: none;
-}
-div.tableblock > table[frame="vsides"] {
-  border-top-style: none;
-  border-bottom-style: none;
-}
-
-
-div.hdlist {
-  margin-top: 0.8em;
-  margin-bottom: 0.8em;
-}
-div.hdlist tr {
-  padding-bottom: 15px;
-}
-dt.hdlist1.strong, td.hdlist1.strong {
-  font-weight: bold;
-}
-td.hdlist1 {
-  vertical-align: top;
-  font-style: normal;
-  padding-right: 0.8em;
-  color: navy;
-}
-td.hdlist2 {
-  vertical-align: top;
-}
-div.hdlist.compact tr {
-  margin: 0;
-  padding-bottom: 0;
-}
-
-.comment {
-  background: yellow;
-}
-
-@media print {
-  div#footer-badges { display: none; }
-}
-
-div#toctitle {
-  color: #527bbd;
-  font-family: sans-serif;
-  font-size: 1.1em;
-  font-weight: bold;
-  margin-top: 1.0em;
-  margin-bottom: 0.1em;
-}
-
-div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
-  margin-top: 0;
-  margin-bottom: 0;
-}
-div.toclevel2 {
-  margin-left: 2em;
-  font-size: 0.9em;
-}
-div.toclevel3 {
-  margin-left: 4em;
-  font-size: 0.9em;
-}
-div.toclevel4 {
-  margin-left: 6em;
-  font-size: 0.9em;
-}
-/* Workarounds for IE6's broken and incomplete CSS2. */
-
-div.sidebar-content {
-  background: #ffffee;
-  border: 1px solid silver;
-  padding: 0.5em;
-}
-div.sidebar-title, div.image-title {
-  color: #527bbd;
-  font-family: sans-serif;
-  font-weight: bold;
-  margin-top: 0.0em;
-  margin-bottom: 0.5em;
-}
-
-div.listingblock div.content {
-  border: 1px solid silver;
-  background: #f4f4f4;
-  padding: 0.5em;
-}
-
-div.quoteblock-attribution {
-  padding-top: 0.5em;
-  text-align: right;
-}
-
-div.verseblock-content {
-  white-space: pre;
-}
-div.verseblock-attribution {
-  padding-top: 0.75em;
-  text-align: left;
-}
-
-div.exampleblock-content {
-  border-left: 2px solid silver;
-  padding-left: 0.5em;
-}
-
-/* IE6 sets dynamically generated links as visited. */
-div#toc a:visited { color: blue; }
-</style>
-</head>
-<body>
-<div id="header">
-<h1>GENIVI_CommonAPI-D-Bus</h1>
-<span id="author">Juergen Gehring - juergen.gehring@bmw.de, Manfred Bathelt - manfred.bathelt@bmw.de</span><br />
-</div>
-<h2 id="_copyright">Copyright</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Copyright &#169; 2013, GENIVI Alliance, Inc.
-Copyright &#169; 2013, BMW AG</p></div>
-<div class="paragraph"><p>This file is part of GENIVI Project IPC Common API.</p></div>
-<div class="paragraph"><p>Contributions are licensed to the GENIVI Alliance under one or more
-Contribution License Agreements or MPL 2.0 .</p></div>
-<div class="paragraph"><p>&#169; 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 <a href="http://mozilla.org/MPL/2.0/">http://mozilla.org/MPL/2.0/</a>.</p></div>
-<div class="paragraph"><p>For further information see <a href="https://collab.genivi.org/wiki/display/genivi/SysInfraEGCommonIDLCommonAPIGuide">https://collab.genivi.org/wiki/display/genivi/SysInfraEGCommonIDLCommonAPIGuide</a></p></div>
-</div>
-<h2 id="_license">License</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>This project is licensed under MPL 2.0</p></div>
-<div class="paragraph"><p>Contribution is done under GENIVI CLA or MPL2.0.</p></div>
-</div>
-<h2 id="_version">Version</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The current version can be taken from the git.</p></div>
-</div>
-<h2 id="_common_api_overview">Common API Overview</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>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:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><tt>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 -&gt; Common API C++ code.
-                  (This is the current package.)
-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.
-CommonAPI-D-Bus-Tools - The eclipse based tools for CommonAPI D-Bus. This is the code generator for
-                        Franca -&gt; Common API D-Bus C++ code.</tt></pre>
-</div></div>
-</div>
-<h2 id="_usage_instructions">Usage Instructions</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The simplest way to use the CommonAPI Tools is to add the update site ZIP available in the CommonAPI-D-Bus-Tools project
-under org.genivi.commonapi.dbus.feature/org.genivi.commonapi.dbus.updatesite.zip to you Eclipse. This is available under:</p></div>
-<div class="paragraph"><p>Help&#8594;Install New Software&#8594;Add Button</p></div>
-<div class="paragraph"><p>There click Browse and navigate to the update site.</p></div>
-<div class="paragraph"><p>In order for dependencies to be resolved you must have a franca update site zip
-(available from <a href="https://code.google.com/a/eclipselabs.org/p/franca/downloads/list">https://code.google.com/a/eclipselabs.org/p/franca/downloads/list</a>) and the xtext update site url
-(<a href="http://download.eclipse.org/modeling/tmf/xtext/updates/composite/releases/">http://download.eclipse.org/modeling/tmf/xtext/updates/composite/releases/</a>) also added to your eclipse sources in the same manner.</p></div>
-<div class="paragraph"><p>Then select "All available sites" in the site selection dropdown box, and in the Software selection window,
-select the entire "GENIVI Common API" Tree.</p></div>
-<div class="paragraph"><p>After the software has been installed in Eclipse you can right-click on any .fidl file and generate C++ code for CommonAPI D-Bus
-by selecting the "CommonAPI&#8594;Generate Common API Code" option.</p></div>
-</div>
-<h2 id="_build_instructions">Build Instructions</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>These are Eclipse Plug-In projects which require Xtext2 and Franca as dependencies within Eclipse.</p></div>
-<div class="paragraph"><p>To build first import the three projects</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><tt>org.genivi.commonapi.core.
-org.genivi.commonapi.core.ui
-org.genivi.commonapi.core.feature</tt></pre>
-</div></div>
-<div class="paragraph"><p>in to Eclipse. Then simply build the workspace. Then right-click on the .feature project and select "Run as Eclipse Application" to launch
-the built projects.</p></div>
-</div>
-<h2 id="_working_on_the_code_amp_contribution">Working on the code &amp; contribution</h2>
-<div class="sectionbody">
-<div class="literalblock">
-<div class="title">First get the code from the git:</div>
-<div class="content">
-<pre><tt>git clone</tt></pre>
-</div></div>
-<div class="literalblock">
-<div class="title">Get an overview of all branches:</div>
-<div class="content">
-<pre><tt>git branch</tt></pre>
-</div></div>
-<div class="literalblock">
-<div class="title">Switch to the branch you want to work on (master is the feature branch) and verify that it has switched (* changed)</div>
-<div class="content">
-<pre><tt>git checkout &lt;your branch&gt;
-git branch</tt></pre>
-</div></div>
-<div class="literalblock">
-<div class="title">Best practice is to create a local branch based on the current branch:</div>
-<div class="content">
-<pre><tt>git branch working_branch</tt></pre>
-</div></div>
-<div class="paragraph"><p>Start working, best practice is to commit smaller, compilable pieces during the development process that makes it easier to handle later on.</p></div>
-<div class="literalblock">
-<div class="title">If you want to commit you changes, send them to the author, you can create a patch like this:</div>
-<div class="content">
-<pre><tt>git format-patch working_branch &lt;your branch&gt;</tt></pre>
-</div></div>
-<div class="paragraph"><p>This creates a set of patches that are published via the mailing list.The patches will be discussed and then merged &amp; uploaded on the git by the maintainer.</p></div>
-<div class="paragraph"><p>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 <a href="http://gerrit.googlecode.com/svn/documentation/2.0/user-signedoffby.html">http://gerrit.googlecode.com/svn/documentation/2.0/user-signedoffby.html</a></p></div>
-</div>
-<div id="footer">
-<div id="footer-text">
-Last updated 2013-01-21 14:53:03 CEST
-</div>
-</div>
-</body>
-</html>
diff --git a/Tutorial b/Tutorial
new file mode 100644
index 0000000..9a1e41f
--- /dev/null
+++ b/Tutorial
@@ -0,0 +1,412 @@
+GENIVI_CommonAPI
+================
+:Author: Juergen Gehring - juergen.gehring@bmw.de, Manfred Bathelt - manfred.bathelt@bmw.de
+:doctitle: GENIVI_CommonAPI_Tutorial
+
+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/SysInfraEGCommonIDLCommon APIGuide
+
+== 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
+RMI communication in a way independent of wich mechanism is used. The main intention is to ease porting your project to
+new communication mechanisms and to enable testing of your application way before setting it up on the precise environment
+and the communication mechanism it is meant to use.
+
+Common API consists of two main parts:
+* The Common API runtime, which is the basic library required to enable Common API functionality.
+* The Common API generator Eclipse plugin, which allows the generation of Common API proxy and stub code out of Franca IDL files.
+
+The application will use both the Common API runtime and the generated code to implement client and/or service.
+
+In order to enable communication via a specific communication mechanism, the corresponding Common API middleware library
+and middleware generator plugin is required in addition. However, both the middleware specific library and the middleware
+specific generated code will NEVER be seen or used by the application code. It is solely the responsibility of the basic
+Common API library to enable communication by using this specific middleware library and code.
+
+
+== Getting started with Common API
+
+The following subsections are meant as a step by step tutorial on how to set up Common API on your system. Additionally,
+the Common API middleware library for D-Bus will be installed and an example application will be created that will
+communicate via D-Bus.
+
+Note that you later can switch D-Bus for any other communication layer (provided it has Common API support)
+_without the need to touch your code or your binary at all!_.
+
+Further information on Common API and Common API D-Bus is provided in the individual README files accompanying both packages.
+
+
+=== Setting up the Environment
+
+==== Requirements
+
+First, make sure all requirements to build the CommonAPI runtime are installed and in the correct version.
+CommonAPI was developed using gcc 4.6 and gcc 4.7, but is feature compatible to gcc 4.5 and compiler compatible to gcc 4.4.
+
+
+==== Setting up Common API
+
+Download the Common API runtime via git from the download site of http://projects.genivi.org/commonapi/, then compile and install the library on your computer:
+----
+$ git clone git://git.projects.genivi.org/ipc/common-api-runtime.git
+$ cd common-api-runtime
+$ autoreconf -i
+$ ./configure
+$ make
+$ sudo make install (or alternative install process, eg. checkinstall on debian-based distributions, such as Ubuntu)
+----
+
+With this, the Common API runtime library will be installed in /usr/local/lib. The package is accessible for your application
+e.g. via pkgconfig. The pkgconfig data is located at /usr/local/lib/pkgconfig.
+
+
+==== Setting up Common API D-Bus
+
+To build Common API D-Bus, the Common API runtime and libdbus version 1.4.16 patched with the marshaling patch must be available through PkgConfig.
+The marshalling patch is provided within the Common API D-Bus package.
+
+Download the Common API D-Bus library via git from the download site of http://projects.genivi.org/commonapi/:
+----
+$ git clone git://git.projects.genivi.org/ipc/common-api-dbus-runtime.git
+----
+
+Download, patch and install version 1.4.16 of libdbus (*WARNING*: _Not_ following these instructions may result in corruption of the preinstalled libdbus
+library of your computer, thereby rendering your system unusable):
+----
+$ 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 < </your/download/path>/common-api-dbus-runtime/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 rest of the entire build process.
+If you followed the instructions above, both will be located in _/usr/local/lib/pkgconfig_, so you can just type:
+----
+$ export PKG_CONFIG_PATH="/usr/local/lib/pkgconfig:$PKG_CONFIG_PATH"
+----
+
+Now, compile and install the Common API D-Bus library on your computer
+----
+$ cd </your/download/path>/common-api-dbus-runtime
+$ autoreconf -i
+$ ./configure
+$ make
+$ sudo make install (or alternative install process, eg. checkinstall on debian-based distributions, such as Ubuntu)
+----
+
+With this, the libraries for Common API and Common API D-Bus are installed and ready for use. The next steps will provide you with the means
+to efficiently design and implement your Common API applications via Eclipse.
+
+
+==== Setting up Eclipse
+
+In order to generate the Common API code that will be used by your client and your service, the Common API generator plugin is
+required. This plugin is an Eclipse plugin, and is provided as an Eclipse update site. For convenience, the generator plugins
+for Common API and Common API D-Bus are packed together.
+
+First, get an appropriate Eclipse up and running. The version of the Common API generator plugin contained in this package was tested
+with the Eclipse Modeling Tools package of Eclipse Juno (4.1) and Eclipse Kepler (4.2). You can get one of them from www.eclipse.org:
+----
+Eclipse Juno: http://www.eclipse.org/downloads/packages/eclipse-modeling-tools/junosr1
+Eclipse Kepler: http://www.eclipse.org/downloads/packages/eclipse-modeling-tools/keplerrc3
+----
+
+Because the generator plugin generates code from Franca IDL files (https://code.google.com/a/eclipselabs.org/p/franca/),
+you will need to have installed the Franca IDL feature in your Eclipse. The plugin was created for Franca IDL version 0.8.9.
+Franca IDL is a language to efficiently design the RMI interface of your applications, independent from specific communication
+mechanisms and also independent from specific programming languages.
+
+Get the appropriate zipped Franca IDL update site (named site_franca_0.8.9.xxx.zip) from
+----
+https://code.google.com/a/eclipselabs.org/p/franca/downloads/list
+----
+Also, download the Common API D-Bus Tooling via git from the download site of http://projects.genivi.org/commonapi/:
+----
+$ git clone git://git.projects.genivi.org/ipc/common-api-dbus-tools.git
+----
+
+Install the Franca IDL plugin and the CommonAPI generator plugins in your Eclipse:
+----
+Help->Install New Software...->Add...->Archive...
+----
+From Franca IDL, you will only need to install the sub-category "Franca Feature" for the Common API and Common API D-Bus generators to work.
+The update site of the Common API generator plugin is located at
+----
+</your/download/path>/common-api-dbus-tools/org.genivi.commonapi.dbus.feature/org.genivi.commonapi.dbus.updatesite.zip
+----
+To develop your application, you will only need the _GENIVI Common API C++ Core Generator_. However, for this tutorial to work and/or if you
+intend to enable your Common API application to communicate via D-Bus, you will also need the _GENIVI Common API C++ D-Bus Generator_.
+
+Restart Eclipse when you are prompted to do so. Now you should be able to use the CommonAPI generators in your Eclipse.
+
+
+=== Creating the Example
+
+The example that will be created in this tutorial from now onwards is provided as ready-to-use source package in
+----
+</your/download/path>/common-api-dbus-tools/CommonAPI-Examples
+----
+The example found here is more verbose than the one we will create, but functionally it will be the same.
+
+It is assumed that you have created a C++ project in your Eclipse in which all further development will happen.
+
+
+==== Creating the RMI interface definition
+
+The first step in developing a Common API application likely will be the definition of the RMI interface the client will use to communicate with
+the server. In the context of CommonAPI, the definition of this interface always happens via the Franca IDL, regardless of which communication
+mechanism you intend to use in the end. For this tutorial, create an arbitrarily namend file ending in _.fidl_ in your Eclipse project. It is
+not relevant where in your project you have placed this file, as the the code generated from this file will always be put in the automatically
+created src-gen folder at the top level of the project hierarchy.
+
+Open your newly created _.fidl_-file, and type the following lines:
+----
+package commonapi.examples
+
+interface HelloWorldInterface {
+    version { major 1 minor 0 }
+
+    method sayHello {
+        in {
+            String name
+        }
+        out {
+            String message
+        }
+    }
+}
+----
+Note that the _version_ parameter in every interface is mandatory! No code will be generated if it is malformed or not present!
+
+Now, save the _.fidl_ file and right click it. As you have installed the Common API and Common API D-Bus generators, you will see
+a menu item saying _"Common API"_, with sub menu items for generating either the Common API level code only ("_Generate C++ Code_")
+or for generating both the Common API level code and the glue code required to run applications with using Common API D-Bus
+("_Generate D-Bus C++ Code_").
+
+
+==== Generating code
+
+We do want to use D-Bus as middleware, so we will need the D-Bus specific glue code as well as the Common API level code which we will
+program agains. Therefore, you might want to chose the latter of the two options provided by the generator plugin ("_Generate D-Bus C++ Code_").
+After having done so, you will see the newly created src-gen folder and it's contents. The files will be created according to their
+fully qualified names relative to src-gen as the top level folder, as defined in the _.fidl_-file:
+----
+HelloWorldInterface.h
+HelloWorldInterfaceProxy.h
+HelloWorldInterfaceProxyBase.h
+HelloWorldInterfaceStub.h
+HelloWorldInterfaceStubDefault.cpp
+HelloWorldInterfaceStubDefault.h
+
+HelloWorldInterfaceDBusProxy.cpp
+HelloWorldInterfaceDBusProxy.h
+HelloWorldInterfaceDBusStubAdapter.cpp
+HelloWorldInterfaceDBusStubAdapter.h
+----
+
+All files that have a "DBus" in their name are glue code required by the D-Bus binding and are not relevant while developing your application,
+they only need to be compiled with your application (there are ways to NOT compile these sources with your applications and include them at
+runtime instead; see the README of Common API D-Bus for details).
+
+All other files that have a _Proxy_ in their name are relevant for you if you develop a client, all other files that have a _Stub_ in their name
+are relevant for you if you develop a service.
+
+A proxy is a class that provides method calls that will result in remote method invocations on the service, plus registration methods for events
+that can be broadcasted by the service.
+
+A stub is the part of the service that will be called when a remote method invocation from a client arrives. It also contains methods to fire
+events (broadcasts) to several or all clients. The Stub comes in two flavors: One default stub that contains empty implementations of all methods,
+thereby allowing you to implement only the ones you are interested in, and a Stub skeleton where you have to implement everything yourself before
+you can use it. A service will have to implement a subclass of either of the two in order to make itself available to the outside world
+(or just use the default stub if your service should not be able to do anything except firing events).
+
+In this tutorial, we will create both a client and a service in order to be able to see some communication going on.
+
+
+==== Implement the Client
+
+Start by creating a new .cpp source file in your project (e.g. helloworld-proxy.cpp). Make sure you have a main method in order to start the client application.
+
+Here, you will need two includes in order to access the Common API client functionality:
+----
+#include <CommonAPI/CommonAPI.h>                           //Defined in the Common API Runtime library
+#include <commonapi/examples/HelloWorldInterfaceProxy.h>   //Part of the code we just generated
+
+#include <iostream>
+#include <future>
+----
+
+The first thing each and every Common API application will do is to load a runtime:
+----
+std::shared_ptr<CommonAPI::Runtime> runtime = CommonAPI::Runtime::load();
+----
+If you link the Common API DBus library to and compile the generated DBus specific code with your executable, this runtime "magically" will be a
+runtime that provides access to the DBus communication infrastructure via a strictly CommonAPI level interface. If you link the library and add
+the generated code of another Common API middleware binding instead, this runtime will provide access to this other communication infrastructure.
+To not interrupt this tutorial, further explanation on this mechanism is done below in a separate chapter in "Further Reading".
+
+In order to be able to communicate with a specific service, we need a proxy. We can create a proxy by using a factory, which in turn we can get from
+the runtime we just created:
+----
+std::shared_ptr<CommonAPI::Factory> factory = runtime->createFactory();
+const std::string& commonApiAddress = "local:commonapi.examples.HelloWorld:commonapi.examples.HelloWorld";
+std::shared_ptr<commonapi::examples::HelloWorldInterfaceProxy<>> helloWorldProxy = factory->buildProxy<commonapi::examples::HelloWorldInterfaceProxy>(commonApiAddress);
+----
+The parameter _commonApiAddress_ is the address at which the service that shall be accessed will be available. This address will be translated
+internally to an actual DBus-Address - or whatever format fits the communication infrastructure you use. Semantically, this address consists of three parts,
+separated by colons:
+* Domain:     The first part, defines in which domain the service is located. For DBus use cases, only "local" makes any sense, as no services that are more remote than
+              "on the same operating system" are accessible.
+* ServiceID:  The second part. This defines the name or type of the service that shall be accessed.
+* InstanceID: The third part. This defines the specific instance of this service that shall be accessed.
+
+There are ways to influence the translation of the Common API address to the specific address (of course once again without the need to change your code).
+Please have a look at the README of Common API DBus if you want to know more about this possibility in the context of DBus, or the corresponding documentation
+of the other middleware binding you are using.
+
+With this, the client is set up and ready to use. We should wait for the service to be available, then we can start issuing calls:
+----
+while (!helloWorldProxy->isAvailable()) {
+    usleep(10);
+}
+
+const std::string name = "World";
+CommonAPI::CallStatus callStatus;
+std::string helloWorldReturnMessage;
+
+helloWorldProxy->sayHello(name, callStatus, helloWorldReturnMessage);
+if (callStatus != CommonAPI::CallStatus::SUCCESS) {
+    std::cerr << "Remote call failed!\n";
+    return -1;
+}
+
+std::cout << "Got message: '" << helloWorldReturnMessage << "'\n";
+----
+
+
+==== Implement the Service
+
+Works about the same way as implementing the client. The includes that are required are the following:
+----
+#include <commonapi/examples/HelloWorldInterfaceStubDefault.h>
+#include <CommonAPI/CommonAPI.h>
+
+#include <iostream>
+#include <sstream>
+#include <thread>
+----
+
+And we also need a stub that actually does something when the method we call in the client gets called:
+----
+class MyHelloWorldStub: public commonapi::examples::HelloWorldInterfaceStubDefault {
+ public:
+    virtual void sayHello(std::string name, std::string& message) {
+        std::stringstream messageStream;
+
+        messageStream <<  "Hello " << name << "!";
+        message = messageStream.str();
+
+        std::cout << "sayHello('" << name << "'): '" << message << "'\n";
+    }
+};
+----
+
+The rest looks quite similar to the client side, with the difference that we do not issue calls via a proxy, but instead register a service that then
+will be provided to the outside world. The service is registered using the same Common API address, which allows the proxy to actually find the service.
+Afterwards, we just wait for calls:
+----
+std::shared_ptr<CommonAPI::Runtime> runtime = CommonAPI::Runtime::load();
+std::shared_ptr<CommonAPI::Factory> factory = runtime->createFactory();
+std::shared_ptr<CommonAPI::ServicePublisher> servicePublisher = runtime->getServicePublisher();
+
+const std::string& commonApiAddress = "local:commonapi.examples.HelloWorld:commonapi.examples.HelloWorld";
+std::shared_ptr<MyHelloWorldStub> helloWorldStub = std::make_shared<MyHelloWorldStub>();
+servicePublisher->registerService(helloWorldStub, commonApiAddress, factory);
+
+while(true) {
+    std::cout << "Waiting for calls... (Abort with CTRL+C)\n";
+    std::this_thread::sleep_for(std::chrono::seconds(60));
+}
+----
+
+
+=== Running the Demo
+
+Build the two applications using your favourite build system. If all worked well, you should see communication ongoing via DBus (e.g. via dbus-monitor),
+and you should get output from your client once, saying
+----
+"Got Message: 'Hello World'".
+----
+
+
+== Further reading
+
+Aside from the README files of Common API and the specific bindings.
+
+
+=== The middleware loading mechanism of Common API
+
+
+==== CommonAPI::Runtime::load() returns no runtime object, why?
+
+As it was mentioned before, when you call _CommonAPI::Runtime::load()_.
+you "magically" will have access to a specific middleware library. In a very basic case, the library and thereby communication mechanism you will have access to
+will be the only Common API middleware library you linked to your executable during compilation.
+
+However, this call to _load()_ most likely will *FAIL* if you have no generated middleware specific code that is compiled with your application. Why that?
+The reason is simple, once understood: Most linkers are lazy. They do not link libraries that seem to be unused. Due to the fact that there is no reference
+whatsoever from Common API (and therefore your application) to any of the middleware libraries, the linker considers any and all middleware libraries
+as unused if not referenced by middleware specific generated code, and therefore will not add them to the executable.
+
+You can disable this behavior by passing the linker flag _whole-archive_ during the build process. Note however that this behavior _normally_ is a good optimization
+without repercussions - except probably in the context of CommonAPI.
+
+
+==== Using more than one middleware binding
+
+CommonAPI provides the possibility to use more than one middleware binding at once. In this case, you should no longer use _CommonAPI::Runtime::load()_,
+but instead _CommonAPI::Runtime::load("NameOfSomeMiddleware")_.
+
+The "NameOfSomeMiddleware" is the well known name of the middleware you want to load. It is defined and made public by each of the middlewares that support
+Common API. For DBus, this name is simply "DBus".
+
+
+==== Fully dynamic loading and additional information
+
+This topic is handled in-depth in the README of Common API. Please refer to this file for any further information.
+
+
+=== Online Documentation and Guides
+
+For an in-depth introduction to Franca IDL, please refer to the current user manual found on
+----
+https://code.google.com/a/eclipselabs.org/p/franca/downloads/list
+----
+At the time of writing of this tutorial, _FrancaUserGuide-0.3.0.pdf_ is the most recent version.
author	Johannes Schanda <schanda@itestra.de>	2013-09-13 15:38:46 +0200
committer	Johannes Schanda <schanda@itestra.de>	2013-09-13 15:41:36 +0200
commit	d2b124232307905bdcda810fabb8bded4253199f (patch)
tree	ee8f2c1f912475a8a13807d95b4b7df2d9116744
parent	bf9ec5ec18591c61c60f8320221e7ebd17ee66f8 (diff)
download	genivi-common-api-runtime-d2b124232307905bdcda810fabb8bded4253199f.tar.gz