docs/building.md

   1 Building libmraa                         {#building}
   2 ===============
   3
   4 libmraa uses cmake in order to make compilation relatively painless. Cmake runs
   5 build out of tree so the recommended way is to clone from git and make a build/
   6 directory inside the clone directory.
   7
   8 ## Build dependencies
   9 Not all these are required but if you're unsure of what you're doing this is
  10 what you'll need:
  11 * [SWIG](http://swig.org) 3.0.5+
  12 * [git](http://git-scm.com)
  13 * [python](http://python.org) 2.7 or 3.4+ (you'll need not just the interpreter but python-dev)
  14 * [node.js](http://nodejs.org) 0.10.x or 0.12.x (you'll need not just the interpreter but nodejs-dev)
  15 * [CMake](http://cmake.org) 2.8.8+
  16
  17 To build the documentation you'll also need:
  18 * [Doxygen](http://www.stack.nl/~dimitri/doxygen/) 1.8.9.1+
  19 * [Sphinx](http://sphinx-doc.org/) 1.1.3+ (For Python docs)
  20
  21 ## Basic build steps
  22
  23 ~~~~~~~~~~~~~{.sh}
  24 mkdir build
  25 cd build
  26 cmake ..
  27 make
  28 ~~~~~~~~~~~~~
  29
  30 If this goes wrong and you have all the dependencies installed, then please
  31 file an issue with the full output of `cmake ..` and `make` or however far you
  32 got.
  33
  34 ## Configuration flags
  35
  36 Our cmake configure has a number of options, cmake-gui or ccmake (cmake -i is
  37 no longer with us :() can show you all the options. A few of the more common
  38 ones are listed below. Note that when the option starts with CMAKE_ it's an
  39 option that is made available by cmake and will be similar in all cmake
  40 projects. You need to add them after `cmake` but before `..`.
  41
  42 A few recommended options:
  43 Changing install path from /usr/local to /usr:
  44  -DCMAKE_INSTALL_PREFIX:PATH=/usr
  45
  46 Building debug build - adds -g and disables optimisations - this will force a
  47 full rebuild:
  48  -DCMAKE_BUILD_TYPE=DEBUG
  49
  50 Using clang instead of gcc:
  51  -DCMAKE_C_COMPILER=/usr/bin/clang -DCMAKE_CXX_COMPILER=/usr/bin/clang++
  52
  53 Building with an older version of SWIG (< 3.0.2) requires the disabling of javascript:
  54  -DBUILDSWIGNODE=OFF
  55
  56 Disabling python module building:
  57  -DBUILDSWIGPYTHON=OFF
  58
  59 Building doc, this will require [SPHINX](http://sphinx-doc.org) &
  60 [Doxygen](http://doxygen.org):
  61  -DBUILDDOC=ON
  62
  63 ## Dependencies continued
  64
  65 You'll need at least SWIG version 3.0.2 and we recommend 3.0.5 to build the
  66 javascript & python modules. If your version of SWIG is older than this then
  67 please see above for disabling SWIGNODE. Otherwise you will get a weird build
  68 failure when building the javascript module. The python module builds with SWIG
  69 2.x.
  70
  71 During the build, we'll assume you're building from git, note that if you
  72 compile with git installed your version of mraa will be tagged -dirty. This
  73 simply means git wasn't installed or that you where building form a tarball.
  74 You can modify build/src/version.c before running make if this is incorrect.
  75 The instructions listed here all assume that build/ is an empty dir that lives
  76 inside the cloned repository of mraa.
  77
  78 If you have multiple versions of python then mraa can get confused, we
  79 recommend using virtualenv to select which version of python you want. We test
  80 2.7 the most but SWIG will generate valid 3.x python code but we do not
  81 generally support building both at once.
  82
  83 ## Using a yocto/oe toolchain
  84
  85 In order to compile with a yocto/oe toolchain use the following toolchain file.
  86 This works well on the edison 1.6 SDK. First source the environment file, then
  87 use our cmake toolchain file.
  88
  89 ~~~~~~~~~~~~~{.sh}
  90 source /opt/poky-edison/1.6/environment-setup-core2-32-poky-linux
  91 mkdir build
  92 cmake -DCMAKE_TOOLCHAIN_FILE=../cmake/Toolchains/oe-sdk_cross.cmake ..
  93 make
  94 ~~~~~~~~~~~~~
  95
  96 ## Using coverity
  97
  98 Static analysis is routinely performed using coverity on libmraa's codebase.
  99 This is the procedure to submit a build to coverity. You'll need to install
 100 coverity-submit for your OS.
 101
 102 ~~~~~~~~~~~~~{.sh}
 103 mkdir covbuild/ && cd covbuild
 104 cmake -DBUILDDOC=OFF -DBUILDSWIG=OFF ..
 105 cov-build --dir cov-int make
 106 tar caf mraa.tar.bz2 cov-int
 107 ~~~~~~~~~~~~~