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