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 For Debian-like distros the below command installs the basic set:
  18
  19 ```bash
  20 sudo apt-get install git build-essential swig3.0 python-dev nodejs-dev cmake
  21 ```
  22
  23 To build the documentation you'll also need:
  24 * [Doxygen](http://www.stack.nl/~dimitri/doxygen/) 1.8.9.1+
  25 * [Graphviz](http://graphviz.org/) 2+ (For Doxygen graph generation)
  26 * [Sphinx](http://sphinx-doc.org/) 1.1.3+ (For Python docs)
  27
  28
  29 ## Basic build steps
  30
  31 ~~~~~~~~~~~~~{.sh}
  32 mkdir build
  33 cd build
  34 cmake ..
  35 make
  36 ~~~~~~~~~~~~~
  37
  38 If this goes wrong and you have all the dependencies installed, then please
  39 file an issue with the full output of `cmake ..` and `make` or however far you
  40 got.
  41
  42 After that you can install built files (into default path) by running:
  43
  44
  45 ```bash
  46 sudo make install
  47 ```
  48
  49 See flags for adjusting install paths in the section below.
  50
  51 Currently our install logic puts Python bindings into standard paths, which
  52 do not work on Debian due to their
  53  [policy](http://www.debian.org/doc/packaging-manuals/python-policy/ch-python.html#s-paths).
  54
  55 We are working on a permanent solution, in the meanwhile please use this command
  56 after `make install` to link installed modules where Debian's Python expects them:
  57
  58 ```bash
  59 sudo ln -s <your install prefix, e.g. /usr>/lib/python2.7/site-packages/* /usr/lib/python2.7/dist-packages
  60 ```
  61
  62 Same approach works for Python 3, you'll just need to adjust the version number
  63 in the path accordingly.
  64
  65 ## Configuration flags
  66
  67 Our CMake configuration has a number of options, `cmake-gui` or `ccmake` (`cmake -i` is
  68 no longer with us :() can show you all the options. A few of the more common
  69 ones are listed below. Note that when the option starts with `CMAKE_` it's an
  70 option that is made available by CMake and will be similar in all CMake
  71 projects. You need to add them after `cmake` but before `..`
  72
  73 A few recommended options:
  74
  75 Changing install path from `/usr/local` to `/usr`:
  76  `-DCMAKE_INSTALL_PREFIX:PATH=/usr`
  77
  78 Building debug build - adds `-g` and disables optimisations - this will force a
  79 full rebuild:
  80  `-DCMAKE_BUILD_TYPE=DEBUG`
  81
  82 Using `clang` instead of `gcc`:
  83  `-DCMAKE_C_COMPILER=/usr/bin/clang -DCMAKE_CXX_COMPILER=/usr/bin/clang++`
  84
  85 Building with an older version of SWIG (< 3.0.2) requires the disabling of JavaScript:
  86  `-DBUILDSWIGNODE=OFF`
  87
  88 Disabling Python module building:
  89  `-DBUILDSWIGPYTHON=OFF`
  90
  91 Building doc, this will require [SPHINX](http://sphinx-doc.org) &
  92 [Doxygen](http://doxygen.org):
  93  `-DBUILDDOC=ON`
  94
  95 Building with Python 3 (careful you need to clear CMake cache between Python
  96 version switches!)
  97  `-DBUILDPYTHON3=ON`
  98
  99 Override build architecture (this is useful because on x86 ARM code is not
 100 compiled so use this flag to force the target arch)
 101  `-DBUILDARCH=arm`
 102
 103 ## Dependencies continued
 104
 105 You'll need at least SWIG version 3.0.2 and we recommend 3.0.5 to build the
 106 JavaScript & Python modules. If your version of SWIG is older than this then
 107 please see above for disabling `SWIGNODE`. Otherwise you will get a weird build
 108 failure when building the JavaScript module. The Python module builds with SWIG
 109 2.x.
 110
 111 During the build, we'll assume you're building from git, note that if you
 112 compile with `git` installed your version of mraa will be tagged `-dirty`. This
 113 simply means `git` wasn't installed or that you where building from a tarball.
 114 You can modify `build/src/version.c` before running `make` if this is incorrect.
 115 The instructions listed here all assume that `build/` is an empty dir that lives
 116 inside the cloned repository of mraa.
 117
 118 If you have multiple versions of Python then mraa can get confused, we
 119 recommend using virtualenv to select which version of Python you want. We test
 120 2.7 the most but SWIG will generate valid 3.x Python code but we do not
 121 generally support building both at once.
 122
 123 ## Using a Yocto/OE toolchain
 124
 125 In order to compile with a Yocto/OE toolchain use the following toolchain file.
 126 This works well on the Edison 1.6 SDK. First source the environment file, then
 127 use our CMake toolchain file.
 128
 129 ~~~~~~~~~~~~~{.sh}
 130 source /opt/poky-edison/1.6/environment-setup-core2-32-poky-linux
 131 mkdir build
 132 cmake -DCMAKE_TOOLCHAIN_FILE=../cmake/Toolchains/oe-sdk_cross.cmake ..
 133 make
 134 ~~~~~~~~~~~~~
 135
 136 ## Using Coverity
 137
 138 Static analysis is routinely performed using Coverity on libmraa's codebase.
 139 This is the procedure to submit a build to Coverity. You'll need to install
 140 `coverity-submit` for your OS.
 141
 142 ~~~~~~~~~~~~~{.sh}
 143 mkdir covbuild/ && cd covbuild
 144 cmake -DBUILDDOC=OFF -DBUILDSWIG=OFF ..
 145 cov-build --dir cov-int make
 146 tar caf mraa.tar.bz2 cov-int
 147 ~~~~~~~~~~~~~
 148
 149 ## Building Java bindings
 150 Have JAVA_HOME set to JDK install directory. Most distributions set this from `/etc/profile.d/`
 151  and have a way of switching between alternatives. We support both OpenJDK and Oracle's JDK.
 152  On Arch Linux with OpenJDK 8 you'll have to set this yourself like this:
 153 ~~~~~~~~~~~~~{.sh}
 154 export JAVA_HOME=/usr/lib/jvm/default/
 155 ~~~~~~~~~~~~~
 156 Then use the CMake configuration flag:
 157  `-DBUILDSWIGJAVA=ON`
 158 To compile `Example.java`
 159 ~~~~~~~~~~~~~{.sh}
 160 javac -cp $DIR_WHERE_YOU_INSTALLED_MRAA/mraa.jar:. Example.java
 161 ~~~~~~~~~~~~~
 162 To run, make sure `libmraajava.so` is in `LD_LIBRARY_PATH`
 163  ~~~~~~~~~~~~~{.sh}
 164 jave -cp $DIR_WHERE_YOU_INSTALLED_MRAA/mraa.jar:. Example
 165 ~~~~~~~~~~~~~
 166
 167 ## Building an IPK/RPM package using `cpack`
 168
 169 You can get `cpack` to generate an IPK or RPM package fairly easily if you have
 170 the correct packaging tools
 171
 172 ~~~~~~~~~~~~~{.sh}
 173 cmake -DIPK=ON -DCMAKE_INSTAL_PREFIX=/usr ..
 174 make package
 175 ~~~~~~~~~~~~~
 176
 177 To use RPM simply enable the RPM option. You'll need `rpmbuild` installed on your
 178 build machine.
 179
 180 ~~~~~~~~~~~~~{.sh}
 181 cmake -DRPM=ON -DCMAKE_INSTAL_PREFIX=/usr ..
 182 ~~~~~~~~~~~~~