HACKING

   1 Hacking on oFono
   2 ****************
   3
   4
   5 Build tools requirements
   6 ========================
   7
   8 When building and testing directly from the repository it is important to
   9 have at least automake version 1.10 or later installed. All modern
  10 distributions should default to the latest version, but it seems that
  11 Debian's default is still an earlier version:
  12
  13   Check version
  14     # dpkg -l '*automake*'
  15
  16   Install new version
  17     # apt-get install automake1.10
  18     # update-alternatives --config automake
  19
  20
  21 Working with the source code repository
  22 =======================================
  23
  24 The repository contains two extra scripts that accomplish the bootstrap
  25 process. One is called "bootstrap" which is the basic scripts that uses the
  26 autotools scripts to create the needed files for building and installing.
  27 It makes sure to call the right programs depending on the usage of shared or
  28 static libraries or translations etc.
  29
  30 The second program is called "bootstrap-configure". This program will make
  31 sure to properly clean the repository, call the "bootstrap" script and then
  32 call configure with proper settings for development. It will use the best
  33 options and pass them over to configure. These options normally include
  34 the enabling the maintainer mode and the debugging features.
  35
  36 So while in a normal source project the call "./configure ..." is used to
  37 configure the project with its settings like prefix and extra options. In
  38 case of bare repositories call "./bootstrap-configure" and it will bootstrap
  39 the repository and calls configure with all the correct options to make
  40 development easier.
  41
  42 In case of preparing for a release with "make distcheck", don't use
  43 bootstrap-configure since it could export development specific settings.
  44
  45 So the normal steps to checkout, build and install such a repository is
  46 like this:
  47
  48   Checkout repository
  49     # git clone git://git.kernel.org/pub/scm/network/ofono/ofono.git
  50     # cd ofono
  51
  52   Configure and build
  53     # ./bootstrap-configure
  54     # make
  55
  56   Check installation
  57     # make install DESTDIR=$PWD/x
  58     # find x
  59     # rm -rf x
  60
  61   Check distribution
  62     # make distcheck
  63
  64   Final installation
  65     # sudo make install
  66
  67   Remove autogenerated files
  68     # make maintainer-clean
  69
  70
  71 Running from within the source code repository
  72 ==============================================
  73
  74 When using "./configure --enable-maintainer-mode" the automake scripts will
  75 use the plugins directly from within the repository. This removes the need
  76 to use "make install" when testing "ofonod". The "bootstrap-configure"
  77 automatically includes this option.
  78
  79   Copy configuration file which specifies the required security policies
  80     # sudo cp ./src/ofono.conf /etc/dbus-1/system.d/
  81
  82   Run daemon in foreground with debugging
  83     # sudo ./src/ofonod -n -d 'plugins/*'
  84
  85 For production installations or distribution packaging it is important that
  86 the "--enable-maintainer-mode" option is NOT used.
  87
  88 Note multiple arguments to -d can be specified, colon, comma or space
  89 separated. The arguments are relative source code filenames for which
  90 debugging output should be enabled; output shell-style globs are
  91 accepted (e.g.: 'plugins/*:src/main.c').
  92
  93 Other debugging settings that can be toggled:
  94
  95  - Environment variable OFONO_AT_DEBUG (set to 1): enable AT commands
  96    debugging
  97
  98
  99 Submitting patches
 100 ==================
 101
 102 If you fixed a bug or you want to add support for something, patches are
 103 welcome! In order to ease the inclusion of your patch, it's important to follow
 104 some rules, otherwise it will likely be rejected by maintainers:
 105
 106 1) Do *not* add "Signed-off-by" lines in your commit messages. oFono does not
 107 use them, so including them is actually an error.
 108
 109 2) Be sure to follow the coding style rules of oFono. They are listed in
 110 doc/coding-style.txt.
 111
 112 3) Split your patch according to the top-level directories. E.g.: if you added
 113 a feature that touches files under 'include/', 'src/' and 'drivers/'
 114 directories, split in three separated patches, taking care not to
 115 break compilation.