summaryrefslogtreecommitdiff
path: root/README
blob: 409944217be3131e558ab4ef0a9d8ea26b5d9e35 (plain)
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
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
GENIVI_AudioManager
===================
:Author: Christian Linke <christian.linke@bmw.de>
:doctitle: GENIVI_AudioManager
 
Copyright
---------
Copyright (C) 2012, GENIVI Alliance, Inc.
Copyright (C) 2012, BMW AG

This file is part of GENIVI Project AudioManager.
 
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/.
 
author Christian Mueller, christian.linke@bmw.de BMW 2011,2012

For further information see http://projects.genivi.org/audio-manager/.

== License
The licenses of this project are split into two parts:
1) the AudioManagerDaemon, licensed under MPL 2.0
2) all other parts that serve as example code that can be taken to build up an own project with it -
    these parts are licensed with the MIT license
    
Contribution is done under GENIVI CLA or MPL2.0. 

== Version
The current version can be taken out of the git. The version 1.0.0 is the first GENIVI compliant code,in the compliance statement of discovery (2.0). 
For every GENIVI release, there is a release of the AudioManager, each of the releases have an own bugfix branch that will get the most important fixes.
Development is done on the master branch.

=== Versioning Scheme
The versioning scheme was decided in the February face2face 2012.
The firs number describes the release branch. This is 1 for discovery, 2 for excalibur and 3 for photon. For major features or release, the second number will be increased.
Each new GENIVI version (releases are every half year, around april and october) will get the current HEAD (for example 2.0.34 for excalibur) and release with the increase of the second number (2.1).
The next commit on the master branch gets then the new first numner (3) and starts from zero.

For the daemon the third number (for example 1.0.X) describes the patch version. The versions are automatically created by git during the build process.
The versioning scheme is used for the AudioManager daemon itself and for each of it's interfaces. The versioning of the Interfaces in EA is defined via the tag "version" and the name of the interfaceversion versionName, for example "CommandReceiveVersion". This information is generated into the interface header files and is used then by cmake to set the interface versions.
Whenever changes are done, the minor version of the interface needs to be incremented.

== Documentation
A very detailed documentation is provided by doxygen. In order to use this, please compile the AudioManager with
----
cmake -DWITH_DOCUMENTATION=ON
make
----

== COMPILE PROGRAMS

=== Compile Options
These are the compile options with default values:

 BUILD_SHARED_LIBS                OFF                                                                                                                                                                             
 CMAKE_BUILD_TYPE                                                                                                                                                                                                 
 CMAKE_INSTALL_PREFIX             /usr/local                                                                                                                                                                      
 COMMON_API_DBUS_LIBRARY          /usr/local/lib/libCommonAPI-DBus.so                                                                                                                                             
 COMMON_API_LIBRARY               /usr/local/lib/libCommonAPI.so                                                                                                                                                  
 GLIB_DBUS_TYPES_TOLERANT         ON                                                                                                                                                                              
 USE_BUILD_LIBS                   ON                                                                                                                                                                              
 WITH_COMMAND_INTERFACE_COMMON_   ON                                                                                                                                                                              
 WITH_DATABASE_STORAGE            OFF                                                                                                                                                                             
 WITH_DLT                         ON                                                                                                                                                                              
 WITH_DOCUMENTATION               ON                                                                                                                                                                              
 WITH_ENABLED_IPC                 CAPI                                                                                                                                                                            
 WITH_LOGSTATE                    ON                                                                                                                                                                              
 WITH_NSM                         ON                                                                                                                                                                              
 WITH_OXF_ANIMATION               OFF                                                                                                                                                                             
 WITH_OXF_TRACE                   OFF                                                                                                                                                                             
 WITH_PLUGIN_COMMAND              ON                                                                                                                                                                              
 WITH_PLUGIN_CONTROL              ON                                                                                                                                                                              
 WITH_PLUGIN_ROUTING              ON                                                                                                                                                                              
 WITH_ROUTING_INTERFACE_ASYNC     OFF                                                                                                                                                                             
 WITH_ROUTING_INTERFACE_CAPI      ON                                                                                                                                                                              
 WITH_SYSTEMD_WATCHDOG            OFF                                                                                                                                                                             
 WITH_TELNET                      ON                                                                                                                                                                              
 WITH_TESTS                       ON                                                                                                                                                                              
 WITH_TEST_CONTROLLER             OFF                                                                                                                                                                             
 gmock_build_tests                OFF                                                                                                                                                                             
 gtest_build_samples              OFF                                                                                                                                                                             
 gtest_build_tests                OFF                                                                                                                                                                             
 gtest_disable_pthreads           OFF                                                                                                                                                                             
 gtest_force_shared_crt           OFF 
    
=== Passing options to cmake:

.-DVERSION="XXX"
When building the AudioManager without taking it from the git (and thus having a .git folder), you can set the version via passing _-DVERSION="XXX"_ to cmake.

.-DDBUS_SERVICE_PREFIX="XXX"
sets the service prefix for Dbus, default "org.genivi.audiomanager\0"

.-DDBUS_SERVICE_OBJECT_PATH="XXX"
sets the object path for Dbus, default "/org/genivi/audiomanager\0"

.-DDEFAULT_TELNETPORT="XXX"
sets the default telnetport, default 6060. Can be overwriten by command line parameter

.-DMAX_TELNETCONNECTIONS="XXX"
sets the default maximum number of telnetconnections, default is 3

.-DNSM_PATH="XXX"
sets the path of the NSM DBUS interface

.-DNSM_INTERFACE="XXX"
sets the interface to the NSM DBUS interface

In order to change these options, you can modify this values with ccmake, do the appropriate changes in 
CmakeList.txt or via the commandline for cmake or (when installed via ccmake)

=== Build dependencies
Basically, all build dependencies are optional- but you might need to use some if you want to have support for Dbus,
for example...

You will need optionally fullfill some dependencies in order to comile the GENIVI AudioManager Daemon, these are:

* dbus (only when DBUS_WRAPPER==ON) [tested on version 1.2.16]
* sqlite3 [tested on version 3.6.22] (only when WITH_DATABASE_STORAGE==ON)
* automotive-dlt [greater 2.5.0] (only when WITH_DLT==ON)        
* doxygen [tested on version 1.6.3] (only when WITH_DOCUMENTATION==ON) 
* commonAPI [version > 2.1] (only with WITH_ENABLED_IPC CAPI), more information here http://projects.genivi.org/commonapi/

To install them in a build environment like Ubuntu you can use:
----
sudo apt-get install libdbus-1-dev libsqlite3-dev doxygen git cmake build-essential
----

=== The NodeStateManager

The nodestatemanager headers are needed to compile the audiomanager. If the nodestatemanagerincludes are not found, 
the headers shipped with the audiomanager are used.
The nodestatemanager can be retrieved from projects.genivi.org . You can install the headers on you system by

----
sudo make install-includeHEADERS
----

For building the tests, you will need the following packages:

* python [tested on version 2.6, should work on higher versions as well]

GoogleMock and GoogleTest are as source code integrated in the sourcetree
To install them in a build environment like Ubuntu you can use:
----
sudo apt-get install python2.6-dev
----

For compiling, you will need a compiler, linker etc. On most linux systems you will get this via
----
sudo apt-get install build-essential
----

More details in the CMake Files CmakeList.txt in the projects.

=== Compiling
To compile open a shell, browse to the AudioManager folder and 
----
mkdir /build
cd build
cmake ..
make
----

After the script finished, you should have:

* a bin/ folder which contains all executables and the libraries: 
* a build/ folder which has all build objects (erase that if you need a clean build)
* a doc/ folder in case you turned the documentation on

In order to install the AudioManager, you can do
----
sudo make install
----

Package generation is supported via CPack. To build packages, you have to 
----
make genivi_package
----

This will create one package if your CMake version is < 2.8.5 (all binaries stripped):
----
AudioManager-<git verison>-Linux.deb 
----

If your version is above 2.8.5, you will get 4 packages (all binaries stripped) :
	
* AudioManager-<git verison>-Linux-bin.deb   		[AudioManager binary]
* AudioManager-<git verison>-Linux-dev.deb   		[header files needed to compile plugins]
* AudioManager-<git verison>-Linux-sampleplugins.deb 	[sample plugins]
* AudioManager-<git verison>-Linux-tests.deb		[tests including tests for sample plugins, installed in the ~/AudioMAnagerTests]

In order to create a tar.gz file of all sources (not including .git, build and bin folder,config files), you can do:
----
make package_source			
----

This will create the following package:
'AudioManager-<git verison>-Source.tar.gz'

All packages will be placed in a folder called packages

=== Adding own plugins
Since the AudioManager needs to be completed with on plugins before it can be used, it provides a mechanism to keep the own sources away from the GENIVI code but compile them together.

TIP: Using this feature is simple: +
Just add a folder with the name _ProjectSpecific_ (be sure to name it excactly like this!) on the main level of the AudioManager folder. CMake will look for CMakeLists.txt in this folder and add all files that it finds in /include to the include path. You can use this to add subfolders with your own plugins and includes, and overwrite productspecific.h for example.

.Here is a sample CMakeLists.txt that can be placed in ProjectSpecific folder:
----
cmake_minimum_required(VERSION 2.6)

### set your own buildflags:
set (CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -g -Wall -Wextra -std=c++98 -D_GNU_SOURCE -pedantic -Wno-variadic-macros")

##overwrite priojecttypes.h:
CONFIGURE_FILE( ${CMAKE_SOURCE_DIR}/ProjectSpecific/overwrite/projecttypes.h ${CMAKE_SOURCE_DIR}/include/projecttypes.h COPYONLY)

if(WITH_PLUGIN_ROUTING)
	add_subdirectory (../PluginRoutingInterfaceMyRoutingPlugin ${CMAKE_CURRENT_BINARY_DIR}/PluginRoutingInterfaceMyRoutingPlugin )
endif(WITH_PLUGIN_ROUTING)

if(WITH_PLUGIN_CONTROL)
	add_subdirectory ( ../PluginControlInterfaceMyControlPlugin ${CMAKE_CURRENT_BINARY_DIR}/PluginControlInterfaceMyControlPlugin)
endif(WITH_PLUGIN_CONTROL)

----

=== CommandLine options
The commandline options of the AudioManager:

----
AudioManagerDaemon Version: 3.0.11
Usage:	AudioManagerDaemon [options]
options:	
	-h: print this message	
	-i: info about current settings 	
	-v: print version	
	-d: daemonize AudioManager 	
	-T: DbusType to be used by CAmDbusWrapper (0=DBUS_SESSION[default], 1=DBUS_SYSTEM)	
	-p<path> path for sqlite database (default is in memory)	
	-t<port> port for telnetconnection	
	-m<max> number of max telnetconnections	
	-c<Name> use controllerPlugin <Name> (full path with .so ending)	
	-l<Name> replace command plugin directory with <Name> (full path)	
	-r<Name> replace routing plugin directory with <Name> (full path)	
	-L<Name> add command plugin directory with <Name> (full path)	
	-R<Name> add routing plugin directory with <Name> (full path)	
----  	


== Telnet Server
The audiomanager has a build- in telnetserver that serves for debuggin purposes.
If you compile your AudioManager with TelnetServer support (cmake -DWITH_TELNET=ON), you will be able to 
set with commandline argument -t the port number and with -m the maximum supported connections. 
The default telnet port is 6060. 
   
.For example, launch a telnet session on port 6060:
      telnet localhost 6060
   
      #>Welcome to GENIVI AudioManager ver-0.0.1-37-ga004215
      #>
   
.press 'help' to get a list of all supported commands on this level:
   
      #>help
      ####################################################
      ####### The following commands are supported: ######
      ####################################################
      #
      #exit  - quit telnet session
      #get   - Go into 'get'-submenu
      #help  - show all possible commands
      #info  - Go into 'info'-submenu
      #list  - Go into 'list'-submenu
      #set   - Go into 'set'-submenu
      #
      #\>
   
.Now type one of these commands, for example 'get', followed with another 'help' to get a list of supported commands:
   
      #\>get
      #
      #\Get>help
      ####################################################
      ####### The following commands are supported: ######
      ####################################################
      # 
      #.. - one step back in menu tree (back to root folder)
      #exit  - close telnet session
      #help  - show all possible commands
      #recv  - show receiverversion 
      #routing  - show current routing
      #sendv - show senderversion
      #
      #\Get>
   
.You can also execute several commands in a line:
   
      #\Get>recv sendv .. help exit
      #   Receiver versions:
      #   Ctrl: 1 | Cmd: 1 | Routing: 1
      #   Sender versions:
      #   Ctrl: 1 | Cmd: 1 | Routing: 1
      ####################################################
      ######## The following commands are supported: ######
      ####################################################
      #
      #exit  - quit telnet session
      #get   - Go into 'get'-submenu
      #help  - show all possible commands
      #info  - Go into 'info'-submenu
      #list  - Go into 'list'-submenu
      #set   - Go into 'set'-submenu
      #
      #Your wish is my command ... bye!
      #Connection closed by foreign host.



== Code Formatting
The source code if formatted with eclipse, the style sheet used can be found in the cmake folder:
----
cmake/AudioManager_Codestyle.xml
----

== 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 (see versioning schmeme, the 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 peaced during the work that makes it easier to 
handle later on.

.If you want to commit you changes, send them to the audiomanager-dev list, 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



----
					    _             _ _       __  __                                   
					   / \  _   _  __| (_) ___ |  \/  | __ _ _ __   __ _  __ _  ___ _ __ 
					  / _ \| | | |/ _` | |/ _ \| |\/| |/ _` | '_ \ / _` |/ _` |/ _ \ '__|
					 / ___ \ |_| | (_| | | (_) | |  | | (_| | | | | (_| | (_| |  __/ |   
					/_/   \_\__,_|\__,_|_|\___/|_|  |_|\__,_|_| |_|\__,_|\__, |\___|_|   
										             |___/    




                                					QQ
                                                                        QQ[
                                                                  qaap
                                                                  )4W? ayQap
                                                                       4QQQ[
                                                              .awQap   ==
                                                               $WWQF   aaaa,
                                                                 `    QWQWQQ
                                                            _aaap=    J?QQP'|
                                                           qQQWQQ6    -      qyQQQgp
                                                           )4QQQQ^ .yQQQQ,   QQQQQQQ
                                                         aa         4QQQW'   )?QQQP'  gmQQma
                                                       ]QQQQp         .               WQQQQW
                                                        ????    aQQQ6p    _aQQQQa      "??"+
                                                       qaaa,   ]QQQQQQ    jQQQQQQf   -aaaap
                                                      jQQWWQ    )????'    )4QQQQP'   mQWQWQf
                                                      ]WQQQQ    jaaa                 QQQQQQf
                                                      )WQQQQ   yQQWWQp    ayQQQap    QQQQQQf
                                                      )QQQQQ   QQQQQQf   ]QQQQQQQ,   QQQQQQf
                                                      ]QQQQD   QQQQQQf   ]QQQQQQQ[   QQQQQQf
                                                        ??':   QQQQQQf   ]QQQQQQQ[   4QQQQQf
                                                               QQQQQQf   ]QQQQQQQ[   =????'I
                                                               QQQQQQf   ]QQQQQQQ[
                                                              .4QQQQQ'   ]QQQQQQQ[
                                                                ]??"-    ]QQQQQQQ(
                                                                         ]4QQQQQ?
                                                                           :

                            qaayQQQQQQQQQwaa   ]mmmmmmmmmmmmmm  ]mmmmmmg,     ]mmm[  ]mmmm  4mmmg         ymmm' ]mmmm pwLq
                           jQQQQD???????QWWQf  ]QQQP??????????  ]QQQWQQQQp    ]QQQf  ]QQQQ   4QQQ6.     _yQQQ'  ]QQQQ \!'a'
                           ]QQQf        )???'  ]QQQ6aaaaaaaaap  ]QQQf)4QQQ6,  ]QQQf  ]QQQQ   |4QQQ6    jmQQQ'v  ]QQQQ
                           ]QQQ[   ]QQQQWWQQf  ]QQQQQQQWQWQWQf  ]QQQf  ?QQQQa ]QQQf  ]QQQQ    i4QQQ6  qQQQQ'    ]QQQQ
                           ]QQQ6,   .   qQQQf  ]QQQf            ]QQQf   ]4QQQ6jQQQf  ]QQQQ      4QQQ6gQWQQ'     ]QQQQ
                            4QQQQQQQQQQQQQQW'  ]QQQQQQWQWQWQWQ  ]QQQf    i?QQQQQQQf  ]QQQQ       ]QQQQQQQ'      ]QQQQ
                            ++"??????????`     ]""!"""""""""""S ]""!'      ]"""!""'  -""!"        """!""'       ]""!"


----