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