README

   1 GENIVI_AudioManager
   2 ===================
   3 :Author: Christian Linke <christian.linke@bmw.de>
   4 :doctitle: GENIVI_AudioManager
   5
   6 Copyright
   7 ---------
   8 Copyright (C) 2012, GENIVI Alliance, Inc.
   9 Copyright (C) 2012, BMW AG
  10
  11 This file is part of GENIVI Project AudioManager.
  12
  13 Contributions are licensed to the GENIVI Alliance under one or more
  14 Contribution License Agreements or MPL 2.0 .
  15
  16 (C) Copyright
  17 This Source Code Form is subject to the terms of the
  18 Mozilla Public License, v. 2.0. If a  copy of the MPL was not distributed with
  19 this file, You can obtain one at http://mozilla.org/MPL/2.0/.
  20
  21 author Christian Mueller, christian.linke@bmw.de BMW 2011,2012
  22
  23 For further information see http://projects.genivi.org/audio-manager/.
  24
  25 == License
  26 The licenses of this project are split into two parts:
  27 1) the AudioManagerDaemon, licensed under MPL 2.0
  28 2) all other parts that serve as example code that can be taken to build up an own project with it -
  29     these parts are licensed with the MIT license
  30
  31 Contribution is done under GENIVI CLA or MPL2.0.
  32
  33 == Version
  34 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).
  35 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.
  36 Development is done on the master branch.
  37
  38 === Versioning Scheme
  39 The versioning scheme was decided in the February face2face 2012.
  40 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.
  41 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).
  42 The next commit on the master branch gets then the new first numner (3) and starts from zero.
  43
  44 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.
  45 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.
  46 Whenever changes are done, the minor version of the interface needs to be incremented.
  47
  48 == Documentation
  49 A very detailed documentation is provided by doxygen. In order to use this, please compile the AudioManager with
  50 ----
  51 cmake -DWITH_DOCUMENTATION=ON
  52 make
  53 ----
  54
  55 == COMPILE PROGRAMS
  56
  57 === Compile Options
  58 These are the compile options with default values:
  59
  60  BUILD_SHARED_LIBS                OFF
  61  CMAKE_BUILD_TYPE
  62  CMAKE_INSTALL_PREFIX             /usr/local
  63  GLIB_DBUS_TYPES_TOLERANT         ON
  64  USE_BUILD_LIBS                   ON
  65  WITH_COMMAND_INTERFACE_DBUS      ON
  66  WITH_DATABASE_STORAGE            ON
  67  WITH_DBUS_WRAPPER                ON
  68  WITH_DLT                         OFF
  69  WITH_DOCUMENTATION               ON
  70  WITH_NSM                         OFF
  71  WITH_PLUGIN_COMMAND              ON
  72  WITH_PLUGIN_CONTROL              ON
  73  WITH_PLUGIN_ROUTING              ON
  74  WITH_ROUTING_INTERFACE_ASYNC     OFF
  75  WITH_ROUTING_INTERFACE_DBUS      ON
  76  WITH_SYSTEMD_WATCHDOG            OFF
  77  WITH_TELNET                      OFF
  78  WITH_TESTS                       OFF
  79  WITH_TEST_CONTROLLER             OFF
  80  gmock_build_tests                OFF
  81  gtest_build_samples              OFF
  82  gtest_build_tests                OFF
  83  gtest_disable_pthreads           OFF
  84  gtest_force_shared_crt           OFF
  85
  86 === Passing options to cmake:
  87
  88 .-DVERSION="XXX"
  89 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.
  90
  91 .-DDBUS_SERVICE_PREFIX="XXX"
  92 sets the service prefix for Dbus, default "org.genivi.audiomanager\0"
  93
  94 .-DDBUS_SERVICE_OBJECT_PATH="XXX"
  95 sets the object path for Dbus, default "/org/genivi/audiomanager\0"
  96
  97 .-DDEFAULT_TELNETPORT="XXX"
  98 sets the default telnetport, default 6060. Can be overwriten by command line parameter
  99
 100 .-DMAX_TELNETCONNECTIONS="XXX"
 101 sets the default maximum number of telnetconnections, default is 3
 102
 103 .-DNSM_PATH="XXX"
 104 sets the path of the NSM DBUS interface
 105
 106 .-DNSM_INTERFACE="XXX"
 107 sets the interface to the NSM DBUS interface
 108
 109 In order to change these options, you can modify this values with ccmake, do the appropriate changes in
 110 CmakeList.txt or via the commandline for cmake or (when installed via ccmake)
 111
 112 === Build dependencies
 113 Basically, all build dependencies are optional- but you might need to use some if you want to have support for Dbus,
 114 for example...
 115
 116 You will need optionally fullfill some dependencies in order to comile the GENIVI AudioManager Daemon, these are:
 117
 118 * dbus (only when DBUS_WRAPPER==ON) [tested on version 1.2.16]
 119 * sqlite3 [tested on version 3.6.22] (only when WITH_DATABASE_STORAGE==ON)
 120 * automotive-dlt [greater 2.5.0] (only when WITH_DLT==ON)
 121 * doxygen (only when WITH_DOCUMENTATION==ON) [tested on version 1.6.3]
 122
 123 To install them in a build environment like Ubuntu you can use:
 124 ----
 125 sudo apt-get install libdbus-1-dev libsqlite3-dev doxygen git cmake build-essential
 126 ----
 127
 128 === The NodeStateManager
 129
 130 The nodestatemanager headers are needed to compile the audiomanager. If the nodestatemanagerincludes are not found,
 131 the headers shipped with the audiomanager are used.
 132 The nodestatemanager can be retrieved from projects.genivi.org . You can install the headers on you system by
 133
 134 ----
 135 sudo make install-includeHEADERS
 136 ----
 137
 138 For building the tests, you will need the following packages:
 139
 140 * python [tested on version 2.6, should work on higher versions as well]
 141
 142 GoogleMock and GoogleTest are as source code integrated in the sourcetree
 143 To install them in a build environment like Ubuntu you can use:
 144 ----
 145 sudo apt-get install python2.6-dev
 146 ----
 147
 148 For compiling, you will need a compiler, linker etc. On most linux systems you will get this via
 149 ----
 150 sudo apt-get install build-essential
 151 ----
 152
 153 More details in the CMake Files CmakeList.txt in the projects.
 154
 155 === Compiling
 156 To compile open a shell, browse to the AudioManager folder and
 157 ----
 158 mkdir /build
 159 cd build
 160 cmake ..
 161 make
 162 ----
 163
 164 After the script finished, you should have:
 165
 166 * a bin/ folder which contains all executables and the libraries:
 167 * a build/ folder which has all build objects (erase that if you need a clean build)
 168 * a doc/ folder in case you turned the documentation on
 169
 170 In order to install the AudioManager, you can do
 171 ----
 172 sudo make install
 173 ----
 174
 175 Package generation is supported via CPack. To build packages, you have to
 176 ----
 177 make genivi_package
 178 ----
 179
 180 This will create one package if your CMake version is < 2.8.5 (all binaries stripped):
 181 ----
 182 AudioManager-<git verison>-Linux.deb
 183 ----
 184
 185 If your version is above 2.8.5, you will get 4 packages (all binaries stripped) :
 186
 187 * AudioManager-<git verison>-Linux-bin.deb              [AudioManager binary]
 188 * AudioManager-<git verison>-Linux-dev.deb              [header files needed to compile plugins]
 189 * AudioManager-<git verison>-Linux-sampleplugins.deb    [sample plugins]
 190 * AudioManager-<git verison>-Linux-tests.deb            [tests including tests for sample plugins, installed in the ~/AudioMAnagerTests]
 191
 192 In order to create a tar.gz file of all sources (not including .git, build and bin folder,config files), you can do:
 193 ----
 194 make package_source
 195 ----
 196
 197 This will create the following package:
 198 'AudioManager-<git verison>-Source.tar.gz'
 199
 200 All packages will be placed in a folder called packages
 201
 202 === Adding own plugins
 203 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.
 204
 205 TIP: Using this feature is simple: +
 206 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.
 207
 208 .Here is a sample CMakeLists.txt that can be placed in ProjectSpecific folder:
 209 ----
 210 cmake_minimum_required(VERSION 2.6)
 211
 212 ### set your own buildflags:
 213 set (CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -g -Wall -Wextra -std=c++98 -D_GNU_SOURCE -pedantic -Wno-variadic-macros")
 214
 215 ##overwrite priojecttypes.h:
 216 CONFIGURE_FILE( ${CMAKE_SOURCE_DIR}/ProjectSpecific/overwrite/projecttypes.h ${CMAKE_SOURCE_DIR}/include/projecttypes.h COPYONLY)
 217
 218 if(WITH_PLUGIN_ROUTING)
 219         add_subdirectory (../PluginRoutingInterfaceMyRoutingPlugin ${CMAKE_CURRENT_BINARY_DIR}/PluginRoutingInterfaceMyRoutingPlugin )
 220 endif(WITH_PLUGIN_ROUTING)
 221
 222 if(WITH_PLUGIN_CONTROL)
 223         add_subdirectory ( ../PluginControlInterfaceMyControlPlugin ${CMAKE_CURRENT_BINARY_DIR}/PluginControlInterfaceMyControlPlugin)
 224 endif(WITH_PLUGIN_CONTROL)
 225
 226 ----
 227
 228 === CommandLine options
 229 The commandline options of the AudioManager:
 230
 231 ----
 232 AudioManagerDaemon Version: 3.0.11
 233 Usage:  AudioManagerDaemon [options]
 234 options:
 235         -h: print this message
 236         -i: info about current settings
 237         -v: print version
 238         -d: daemonize AudioManager
 239         -T: DbusType to be used by CAmDbusWrapper (0=DBUS_SESSION[default], 1=DBUS_SYSTEM)
 240         -p<path> path for sqlite database (default is in memory)
 241         -t<port> port for telnetconnection
 242         -m<max> number of max telnetconnections
 243         -c<Name> use controllerPlugin <Name> (full path with .so ending)
 244         -l<Name> replace command plugin directory with <Name> (full path)
 245         -r<Name> replace routing plugin directory with <Name> (full path)
 246         -L<Name> add command plugin directory with <Name> (full path)
 247         -R<Name> add routing plugin directory with <Name> (full path)
 248 ----
 249
 250
 251 == Telnet Server
 252 The audiomanager has a build- in telnetserver that serves for debuggin purposes.
 253 If you compile your AudioManager with TelnetServer support (cmake -DWITH_TELNET=ON), you will be able to
 254 set with commandline argument -t the port number and with -m the maximum supported connections.
 255 The default telnet port is 6060.
 256
 257 .For example, launch a telnet session on port 6060:
 258       telnet localhost 6060
 259
 260       #>Welcome to GENIVI AudioManager ver-0.0.1-37-ga004215
 261       #>
 262
 263 .press 'help' to get a list of all supported commands on this level:
 264
 265       #>help
 266       ####################################################
 267       ####### The following commands are supported: ######
 268       ####################################################
 269       #
 270       #exit  - quit telnet session
 271       #get   - Go into 'get'-submenu
 272       #help  - show all possible commands
 273       #info  - Go into 'info'-submenu
 274       #list  - Go into 'list'-submenu
 275       #set   - Go into 'set'-submenu
 276       #
 277       #\>
 278
 279 .Now type one of these commands, for example 'get', followed with another 'help' to get a list of supported commands:
 280
 281       #\>get
 282       #
 283       #\Get>help
 284       ####################################################
 285       ####### The following commands are supported: ######
 286       ####################################################
 287       #
 288       #.. - one step back in menu tree (back to root folder)
 289       #exit  - close telnet session
 290       #help  - show all possible commands
 291       #recv  - show receiverversion
 292       #routing  - show current routing
 293       #sendv - show senderversion
 294       #
 295       #\Get>
 296
 297 .You can also execute several commands in a line:
 298
 299       #\Get>recv sendv .. help exit
 300       #   Receiver versions:
 301       #   Ctrl: 1 | Cmd: 1 | Routing: 1
 302       #   Sender versions:
 303       #   Ctrl: 1 | Cmd: 1 | Routing: 1
 304       ####################################################
 305       ######## The following commands are supported: ######
 306       ####################################################
 307       #
 308       #exit  - quit telnet session
 309       #get   - Go into 'get'-submenu
 310       #help  - show all possible commands
 311       #info  - Go into 'info'-submenu
 312       #list  - Go into 'list'-submenu
 313       #set   - Go into 'set'-submenu
 314       #
 315       #Your wish is my command ... bye!
 316       #Connection closed by foreign host.
 317
 318
 319
 320 == Code Formatting
 321 The source code if formatted with eclipse, the style sheet used can be found in the cmake folder:
 322 ----
 323 cmake/AudioManager_Codestyle.xml
 324 ----
 325
 326 == Working on the code & contribution
 327
 328 .First get the code from the git:
 329         git clone
 330
 331 .Get an overview of all branches:
 332         git branch
 333
 334 .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)
 335         git checkout <your branch>
 336         git branch
 337
 338 .Best practice is to create a local branch based on the current branch:
 339         git branch working_branch
 340
 341 Start working, best practice is to commit smaller, compilable peaced during the work that makes it easier to
 342 handle later on.
 343
 344 .If you want to commit you changes, send them to the audiomanager-dev list, you can create a patch like this:
 345         git format-patch working_branch <your branch>
 346
 347 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.
 348
 349 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
 350
 351
 352
 353 ----
 354                                             _             _ _       __  __
 355                                            / \  _   _  __| (_) ___ |  \/  | __ _ _ __   __ _  __ _  ___ _ __
 356                                           / _ \| | | |/ _` | |/ _ \| |\/| |/ _` | '_ \ / _` |/ _` |/ _ \ '__|
 357                                          / ___ \ |_| | (_| | | (_) | |  | | (_| | | | | (_| | (_| |  __/ |
 358                                         /_/   \_\__,_|\__,_|_|\___/|_|  |_|\__,_|_| |_|\__,_|\__, |\___|_|
 359                                                                                              |___/
 360
 361
 362
 363
 364                                                                         QQ
 365                                                                         QQ[
 366                                                                   qaap
 367                                                                   )4W? ayQap
 368                                                                        4QQQ[
 369                                                               .awQap   ==
 370                                                                $WWQF   aaaa,
 371                                                                  `    QWQWQQ
 372                                                             _aaap=    J?QQP'|
 373                                                            qQQWQQ6    -      qyQQQgp
 374                                                            )4QQQQ^ .yQQQQ,   QQQQQQQ
 375                                                          aa         4QQQW'   )?QQQP'  gmQQma
 376                                                        ]QQQQp         .               WQQQQW
 377                                                         ????    aQQQ6p    _aQQQQa      "??"+
 378                                                        qaaa,   ]QQQQQQ    jQQQQQQf   -aaaap
 379                                                       jQQWWQ    )????'    )4QQQQP'   mQWQWQf
 380                                                       ]WQQQQ    jaaa                 QQQQQQf
 381                                                       )WQQQQ   yQQWWQp    ayQQQap    QQQQQQf
 382                                                       )QQQQQ   QQQQQQf   ]QQQQQQQ,   QQQQQQf
 383                                                       ]QQQQD   QQQQQQf   ]QQQQQQQ[   QQQQQQf
 384                                                         ??':   QQQQQQf   ]QQQQQQQ[   4QQQQQf
 385                                                                QQQQQQf   ]QQQQQQQ[   =????'I
 386                                                                QQQQQQf   ]QQQQQQQ[
 387                                                               .4QQQQQ'   ]QQQQQQQ[
 388                                                                 ]??"-    ]QQQQQQQ(
 389                                                                          ]4QQQQQ?
 390                                                                            :
 391
 392                             qaayQQQQQQQQQwaa   ]mmmmmmmmmmmmmm  ]mmmmmmg,     ]mmm[  ]mmmm  4mmmg         ymmm' ]mmmm pwLq
 393                            jQQQQD???????QWWQf  ]QQQP??????????  ]QQQWQQQQp    ]QQQf  ]QQQQ   4QQQ6.     _yQQQ'  ]QQQQ \!'a'
 394                            ]QQQf        )???'  ]QQQ6aaaaaaaaap  ]QQQf)4QQQ6,  ]QQQf  ]QQQQ   |4QQQ6    jmQQQ'v  ]QQQQ
 395                            ]QQQ[   ]QQQQWWQQf  ]QQQQQQQWQWQWQf  ]QQQf  ?QQQQa ]QQQf  ]QQQQ    i4QQQ6  qQQQQ'    ]QQQQ
 396                            ]QQQ6,   .   qQQQf  ]QQQf            ]QQQf   ]4QQQ6jQQQf  ]QQQQ      4QQQ6gQWQQ'     ]QQQQ
 397                             4QQQQQQQQQQQQQQW'  ]QQQQQQWQWQWQWQ  ]QQQf    i?QQQQQQQf  ]QQQQ       ]QQQQQQQ'      ]QQQQ
 398                             ++"??????????`     ]""!"""""""""""S ]""!'      ]"""!""'  -""!"        """!""'       ]""!"
 399
 400
 401 ----