1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
|
GENIVI_CommonAPI
================
:Author: Juergen Gehring - juergen.gehring@bmw.de, Manfred Bathelt - manfred.bathelt@bmw.de
:doctitle: GENIVI_CommonAPI
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 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. (This is the current package.)
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.
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
Use autotools to build this package:
----
# 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 of CommonAPI with Visual Studio, you can use the solution file CommonAPI.sln. It is configured to build CommonAPI as a static library.
To build the Tests project you have to set an environment variable called GTEST pointing to your gtest directory (e.g. C:\gtest-1.7.0), and if applicable restart your
Visual Studio.
Information for building of gtest:
Download gtest from https://code.google.com/p/googletest/ e.g. gtest-1.7.0.zip
Unpack the archiv into a directory
Open the solution gtest-md.sln with Visual Studio 2013 and build gtest
== Linking against CommonAPI
CommonAPI bindings requires successful activation of all static initialization code on library load. Therefore it is
necessary to activate certain linker flags to ensure this is always the case. These should be specified in the
pkg-config files of the respective bindings, but are also listed here. In case of dynamic linking (.so)
--no-as-needed must be specified:
----
-Wl,--no-as-needed -lbindingLib -Wl,--as-needed
----
In case of static linking --whole-archive must be specified:
----
-Wl,--whole-archive bindingLib.a -Wl,--no-whole-archive
----
=== Linking generated proxies & stubs
Generated proxies and stubs also require successful activation of all static initialization code on load.
If they are provided in either a static or dynamic library to the application they must also be linked wrapped in the
flags described above.
== Elements marked as deprecated
All elements that are marked as deprecated on Common API level are considered to be redundant, and normally
the other way of acchieving the same (the way pointed to by the marked elements) is the way we recommend to use.
Elements marked as deprecated will be removed once we have reliable and comprehensive feedback telling us they
are not used anymore by anybody, but they will remain in Common API for compatibility reasons at least until then.
== Fully Dynamic loading of middleware bindings
CommonAPI supports the loading of middleware specific libraries at runtime, without even linking them to the executable beforehand.
For this purpose, each middleware binding library provides a short well known name that can be used to identify the library.
If such a well known name is passed as an argument to _CommonAPI::Runtime::load()_, CommonAPI will try to dynamically resolve the
given name (i.e. find an appropriate library for it), if it is not already provided by a library that was linked at compile time.
In order to resolve a middleware specific library, the default search paths _/usr/lib_ and _/usr/local/lib/_ will be searched for
all libraries that match the name pattern "libCommonAPI-<arbitraryName>.so[.major[.minor.revision]]". This naming constraint
exists in order to prevent too many libraries to be opened and closed again, as each of the libraries found will be searched for the
presence of the identifying well known name.
If there are more libraries for the same binding, the library with the higher version will take precedence.
The resolution procedure can be extended by providing an environment variable with additonal search paths (see below),
or by specifying a specific path for a specific binding using configuration files (see below). +
NOTE: If you call _CommonAPI::Runtime::load()_ without an parameter when no middleware library has been linked at compile time,
CommonAPI will load the first middleware library it encounters on the default and specified search paths, regardless of
its version.
== Configuring CommonAPI
It is possible to provide additional configuration parameters to tailor CommonAPI to your specific system architecture.
This can be done either by providing configuration files or by setting appropriate environment variables.
=== Configuration Files
Each CommonAPI configuration file will define additional parameters for specific categories.
Which categories and which parameters for each of those categories are available will be detailed below.
All parameters for all categories are optional. For each omitted parameter a reasonable default will be set. Because of
this, it is not mandatory to provide a config file unless you want to alter any of the configurable default values.
CommonAPI config files can be defined locally per binary, globally per binary or globally for all binaries.
If more than one config file is defined for a given binary (e.g. one locally and one globally) and a given category
is defined in several of these config files, for each parameter that may be provided for this category the value found
in the most specific config file will take precedence. If a category is defined several times within the same config file,
the first occurrence of each parameter will take precedence.
All categories and all parameters are separated from each other by one or more newline characters.
CommonAPI Config files have to be named this way:
----
# Binary local: "<FqnOfBinary>.conf", e.g. "/usr/bin/myBinary.conf" if the binary is "/usr/bin/myBinary"
# Binary global: "/etc/CommonApi/<NameOfBinary>.conf", e.g. "/etc/CommonAPI/myBinary.conf"
# Global: "/etc/CommonAPI/CommonAPI.conf"
----
==== Available categories
.Well known names of specific middleware bindings
Allows to set parameters that influence the loading procedure of specific middleware bindings.
The syntax is:
----
{binding:<well known binding name>}
libpath=<Fully qualified name of the library of the binding>
alias=<One or more desired aliases for the binding, separated by ":">
genpath=<One or more fully qualified names to libraries containing additional (generated) code for this binding, separated by ":">
default
----
* *libpath*: Provides a fully qualified name that replaces the search path when trying to dynamically load the identified binding.
The library found at libpath will take precedence over all other dynamically discoverable libraries for this binding. +
NOTE: If a library for the specified middleware binding is linked to the binary already, this parameter will have no effect. +
WARNING: _Not_ finding an appropriate library at libpath is considered to be an error! In this case, no further attempts to resolve
the library will be made. If you want to have an explicit error state, call the overloaded _Runtime::load()_
functions and pass in an instance of _Runtime::LoadState_ as argument.
* *alias*: In order to load a specific middleware binding, one normally has to know the well known name of the middleware
(e.g. "DBus" for the D-Bus middleware binding) and pass this name as parameter when calling _CommonAPI::Runtime::load("<name>")_.
_alias_ maps the well known name for this purpose to one or more arbitrary aliases, thereby decoupling the loading of a specific
middleware binding from its specific name. +
NOTE: You MAY specify this parameter more than once for a binding. The effect will be the same as if you had one alias parameter
specifying the exact same names separated by ":". +
NOTE: If the same alias is specified more than once, only the first occurrence of the alias will be considered. +
WARNING: As CommonAPI itself does not know about which well known middleware names there are, it is possible to specify the well known
name of an actual binding as an alias for any other middleware binding. In this case, the actual middleware binding will not
be accessible any longer, unless you specify another unique alias for it.
* *genpath*: Specifies one or more paths at which a generic library containing additional (e.g. generated middleware and interface specific)
code for the middleware binding is to be found. This additional code will be injected when the specific middleware considers
it to be the right time to do so. +
NOTE: You MAY specify this parameter more than once for a binding. The effect will be the same as if you had one genpath parameter
specifying the exact same values separated by ":". +
NOTE: If _No_ such parameter is defined, the standard search paths "/usr/lib" and "/usr/local/lib" plus any additional paths defined in
the environment variable COMMONAPI_BINDING_PATH (see below) will be searched for any libraries that match the name pattern
"lib<wellKnownMiddlewareName>Gen-<arbitraryName>.so[.major[.minor.revision]]". All matching libraries will be loaded. +
WARNING: _Not_ finding an appropriate library at any single one of the defined genpaths may result in undefined behavior. +
NOTE FOR DEVELOPERS: The _genpath_ parameter will be parsed by the CommonAPI framework and stored in _CommonAPI::Configuration_. Actually loading the
libraries and following the rules described here however is task of the specific middleware binding. You might want to use
the convenience methods provided in <CommonAPI/utils.h> for this purpose. By taking control of the actual proceedings,
you may introduce additional mechanisms of discovering and loading such libraries, and you can defer the loading of the
libraries until you deem it to be the right time to do so.
* *default*: Specifies the library for this binding as the default that is to be loaded if no parameter is given to _CommonAPI::Runtime::load()_. +
WARNING: _Not_ finding an appropriate library for a configured default binding at neither specified nor the default paths is considered to be an error!
In this case, no further attempts to find another default library will be made! If you want to have an explicit error state, call the
overloaded _Runtime::load()_ functions and pass in an instance of _Runtime::LoadState_ as argument.
=== Environment Variables
* COMMONAPI_BINDING_PATH: By default, the standard paths "/usr/lib" and "/usr/local/lib" will be searched for binding libraries that are
loaded dynamically (i.e. at runtime without linking them to the binary beforehand). All paths defined in this environment variable
will take precedence over those two default paths. Separator between several paths is ":".
== Remarks on Windows version
Due to a compiler bug in Visual Studio 2013, which is not able to call constructors of variadic template packs, if they contain zero elements, the factory’s buildProxy method does not return a proxy without AttributeExtensions, but implicitly adds a WINDummyAttributeExtension. So to assign such a proxy use the auto keyword or the typedef ***ProxyDefault in the generated ***Proxy.h.
This restriction does only affect the windows port. The typedef is cross platform compatible as it points to a proxy with empty template list on Linux.
The Windows version does not support dynamic loading.
== 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 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
|
