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 * [Graphviz](http://graphviz.org/) 2+ (For doxygen graph generation)
  20 * [Sphinx](http://sphinx-doc.org/) 1.1.3+ (For Python docs)
  21
  22
  23 ## Basic build steps
  24
  25 ~~~~~~~~~~~~~{.sh}
  26 mkdir build
  27 cd build
  28 cmake ..
  29 make
  30 ~~~~~~~~~~~~~
  31
  32 If this goes wrong and you have all the dependencies installed, then please
  33 file an issue with the full output of `cmake ..` and `make` or however far you
  34 got.
  35
  36 ## Configuration flags
  37
  38 Our cmake configure has a number of options, cmake-gui or ccmake (cmake -i is
  39 no longer with us :() can show you all the options. A few of the more common
  40 ones are listed below. Note that when the option starts with CMAKE_ it's an
  41 option that is made available by cmake and will be similar in all cmake
  42 projects. You need to add them after `cmake` but before `..`.
  43
  44 A few recommended options:
  45 Changing install path from /usr/local to /usr:
  46  -DCMAKE_INSTALL_PREFIX:PATH=/usr
  47
  48 Building debug build - adds -g and disables optimisations - this will force a
  49 full rebuild:
  50  -DCMAKE_BUILD_TYPE=DEBUG
  51
  52 Using clang instead of gcc:
  53  -DCMAKE_C_COMPILER=/usr/bin/clang -DCMAKE_CXX_COMPILER=/usr/bin/clang++
  54
  55 Building with an older version of SWIG (< 3.0.2) requires the disabling of javascript:
  56  -DBUILDSWIGNODE=OFF
  57
  58 Disabling python module building:
  59  -DBUILDSWIGPYTHON=OFF
  60
  61 Building doc, this will require [SPHINX](http://sphinx-doc.org) &
  62 [Doxygen](http://doxygen.org):
  63  -DBUILDDOC=ON
  64
  65 Building with python3 (careful you need to clear cmake cache between python
  66 version switches!)
  67  -DBUILDPYTHON3=ON
  68
  69 Override build architecture (this is useful because on x86 arm code is not
  70 compiled so use this flag to force the target arch)
  71  -DBUILDARCH=arm
  72
  73 ## Dependencies continued
  74
  75 You'll need at least SWIG version 3.0.2 and we recommend 3.0.5 to build the
  76 javascript & python modules. If your version of SWIG is older than this then
  77 please see above for disabling SWIGNODE. Otherwise you will get a weird build
  78 failure when building the javascript module. The python module builds with SWIG
  79 2.x.
  80
  81 During the build, we'll assume you're building from git, note that if you
  82 compile with git installed your version of mraa will be tagged -dirty. This
  83 simply means git wasn't installed or that you where building form a tarball.
  84 You can modify build/src/version.c before running make if this is incorrect.
  85 The instructions listed here all assume that build/ is an empty dir that lives
  86 inside the cloned repository of mraa.
  87
  88 If you have multiple versions of python then mraa can get confused, we
  89 recommend using virtualenv to select which version of python you want. We test
  90 2.7 the most but SWIG will generate valid 3.x python code but we do not
  91 generally support building both at once.
  92
  93 ## Using a yocto/oe toolchain
  94
  95 In order to compile with a yocto/oe toolchain use the following toolchain file.
  96 This works well on the edison 1.6 SDK. First source the environment file, then
  97 use our cmake toolchain file.
  98
  99 ~~~~~~~~~~~~~{.sh}
 100 source /opt/poky-edison/1.6/environment-setup-core2-32-poky-linux
 101 mkdir build
 102 cmake -DCMAKE_TOOLCHAIN_FILE=../cmake/Toolchains/oe-sdk_cross.cmake ..
 103 make
 104 ~~~~~~~~~~~~~
 105
 106 ## Using coverity
 107
 108 Static analysis is routinely performed using coverity on libmraa's codebase.
 109 This is the procedure to submit a build to coverity. You'll need to install
 110 coverity-submit for your OS.
 111
 112 ~~~~~~~~~~~~~{.sh}
 113 mkdir covbuild/ && cd covbuild
 114 cmake -DBUILDDOC=OFF -DBUILDSWIG=OFF ..
 115 cov-build --dir cov-int make
 116 tar caf mraa.tar.bz2 cov-int
 117 ~~~~~~~~~~~~~
 118
 119 ## Building Java bindings
 120 Have JAVA_HOME set to JDK install directory. Most distributions set this from /etc/profile.d/ and have a way of switching between alternatives. We support both OpenJDK and Oracle's JDK. On Arch Linux with openjdk8 you'll have to set this yourself like this:
 121 ~~~~~~~~~~~~~{.sh}
 122 export JAVA_HOME=/usr/lib/jvm/default/
 123 ~~~~~~~~~~~~~
 124 Then use the cmake configuration flag:
 125  -DBUILDSWIGJAVA=ON
 126 To compile Example.java
 127 ~~~~~~~~~~~~~{.sh}
 128 javac -cp $DIR_WHERE_YOU_INSTALLED_MRAA/mraa.jar:. Example.java
 129 ~~~~~~~~~~~~~
 130 To run, make sure libmraajava.so is in LD_LIBRARY_PATH
 131  ~~~~~~~~~~~~~{.sh}
 132 jave -cp $DIR_WHERE_YOU_INSTALLED_MRAA/mraa.jar:. Example
 133 ~~~~~~~~~~~~~