From: Alex Tereschenko Date: Tue, 17 Nov 2015 20:33:04 +0000 (+0100) Subject: README.md: formatting updates to make it nicer + typo fixes. X-Git-Tag: v0.9.0~91 X-Git-Url: http://review.tizen.org/git/?p=contrib%2Fmraa.git;a=commitdiff_plain;h=bde9715c942e0e1f675951e4d1572b7fafec27b0 README.md: formatting updates to make it nicer + typo fixes. Signed-off-by: Alex Tereschenko Signed-off-by: Brendan Le Foll --- diff --git a/docs/building.md b/docs/building.md index 7912d13..919c49f 100644 --- a/docs/building.md +++ b/docs/building.md @@ -1,8 +1,8 @@ Building libmraa {#building} =============== -libmraa uses cmake in order to make compilation relatively painless. Cmake runs -build out of tree so the recommended way is to clone from git and make a build/ +libmraa uses cmake in order to make compilation relatively painless. CMake runs +build out of tree so the recommended way is to clone from git and make a `build/` directory inside the clone directory. ## Build dependencies @@ -22,7 +22,7 @@ sudo apt-get install git build-essential swig3.0 python-dev nodejs-dev cmake To build the documentation you'll also need: * [Doxygen](http://www.stack.nl/~dimitri/doxygen/) 1.8.9.1+ -* [Graphviz](http://graphviz.org/) 2+ (For doxygen graph generation) +* [Graphviz](http://graphviz.org/) 2+ (For Doxygen graph generation) * [Sphinx](http://sphinx-doc.org/) 1.1.3+ (For Python docs) @@ -64,66 +64,67 @@ in the path accordingly. ## Configuration flags -Our cmake configure has a number of options, cmake-gui or ccmake (cmake -i is +Our CMake configuration has a number of options, `cmake-gui` or `ccmake` (`cmake -i` is no longer with us :() can show you all the options. A few of the more common -ones are listed below. Note that when the option starts with CMAKE_ it's an -option that is made available by cmake and will be similar in all cmake -projects. You need to add them after `cmake` but before `..`. +ones are listed below. Note that when the option starts with `CMAKE_` it's an +option that is made available by CMake and will be similar in all CMake +projects. You need to add them after `cmake` but before `..` A few recommended options: -Changing install path from /usr/local to /usr: - -DCMAKE_INSTALL_PREFIX:PATH=/usr -Building debug build - adds -g and disables optimisations - this will force a +Changing install path from `/usr/local` to `/usr`: + `-DCMAKE_INSTALL_PREFIX:PATH=/usr` + +Building debug build - adds `-g` and disables optimisations - this will force a full rebuild: - -DCMAKE_BUILD_TYPE=DEBUG + `-DCMAKE_BUILD_TYPE=DEBUG` -Using clang instead of gcc: - -DCMAKE_C_COMPILER=/usr/bin/clang -DCMAKE_CXX_COMPILER=/usr/bin/clang++ +Using `clang` instead of `gcc`: + `-DCMAKE_C_COMPILER=/usr/bin/clang -DCMAKE_CXX_COMPILER=/usr/bin/clang++` -Building with an older version of SWIG (< 3.0.2) requires the disabling of javascript: - -DBUILDSWIGNODE=OFF +Building with an older version of SWIG (< 3.0.2) requires the disabling of JavaScript: + `-DBUILDSWIGNODE=OFF` -Disabling python module building: - -DBUILDSWIGPYTHON=OFF +Disabling Python module building: + `-DBUILDSWIGPYTHON=OFF` Building doc, this will require [SPHINX](http://sphinx-doc.org) & [Doxygen](http://doxygen.org): - -DBUILDDOC=ON + `-DBUILDDOC=ON` -Building with python3 (careful you need to clear cmake cache between python +Building with Python 3 (careful you need to clear CMake cache between Python version switches!) - -DBUILDPYTHON3=ON + `-DBUILDPYTHON3=ON` -Override build architecture (this is useful because on x86 arm code is not +Override build architecture (this is useful because on x86 ARM code is not compiled so use this flag to force the target arch) - -DBUILDARCH=arm + `-DBUILDARCH=arm` ## Dependencies continued You'll need at least SWIG version 3.0.2 and we recommend 3.0.5 to build the -javascript & python modules. If your version of SWIG is older than this then -please see above for disabling SWIGNODE. Otherwise you will get a weird build -failure when building the javascript module. The python module builds with SWIG +JavaScript & Python modules. If your version of SWIG is older than this then +please see above for disabling `SWIGNODE`. Otherwise you will get a weird build +failure when building the JavaScript module. The Python module builds with SWIG 2.x. During the build, we'll assume you're building from git, note that if you -compile with git installed your version of mraa will be tagged -dirty. This -simply means git wasn't installed or that you where building form a tarball. -You can modify build/src/version.c before running make if this is incorrect. -The instructions listed here all assume that build/ is an empty dir that lives +compile with `git` installed your version of mraa will be tagged `-dirty`. This +simply means `git` wasn't installed or that you where building from a tarball. +You can modify `build/src/version.c` before running `make` if this is incorrect. +The instructions listed here all assume that `build/` is an empty dir that lives inside the cloned repository of mraa. -If you have multiple versions of python then mraa can get confused, we -recommend using virtualenv to select which version of python you want. We test -2.7 the most but SWIG will generate valid 3.x python code but we do not +If you have multiple versions of Python then mraa can get confused, we +recommend using virtualenv to select which version of Python you want. We test +2.7 the most but SWIG will generate valid 3.x Python code but we do not generally support building both at once. -## Using a yocto/oe toolchain +## Using a Yocto/OE toolchain -In order to compile with a yocto/oe toolchain use the following toolchain file. -This works well on the edison 1.6 SDK. First source the environment file, then -use our cmake toolchain file. +In order to compile with a Yocto/OE toolchain use the following toolchain file. +This works well on the Edison 1.6 SDK. First source the environment file, then +use our CMake toolchain file. ~~~~~~~~~~~~~{.sh} source /opt/poky-edison/1.6/environment-setup-core2-32-poky-linux @@ -132,11 +133,11 @@ cmake -DCMAKE_TOOLCHAIN_FILE=../cmake/Toolchains/oe-sdk_cross.cmake .. make ~~~~~~~~~~~~~ -## Using coverity +## Using Coverity -Static analysis is routinely performed using coverity on libmraa's codebase. -This is the procedure to submit a build to coverity. You'll need to install -coverity-submit for your OS. +Static analysis is routinely performed using Coverity on libmraa's codebase. +This is the procedure to submit a build to Coverity. You'll need to install +`coverity-submit` for your OS. ~~~~~~~~~~~~~{.sh} mkdir covbuild/ && cd covbuild @@ -146,24 +147,26 @@ tar caf mraa.tar.bz2 cov-int ~~~~~~~~~~~~~ ## Building Java bindings -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: +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 OpenJDK 8 you'll have to set this yourself like this: ~~~~~~~~~~~~~{.sh} export JAVA_HOME=/usr/lib/jvm/default/ ~~~~~~~~~~~~~ -Then use the cmake configuration flag: - -DBUILDSWIGJAVA=ON -To compile Example.java +Then use the CMake configuration flag: + `-DBUILDSWIGJAVA=ON` +To compile `Example.java` ~~~~~~~~~~~~~{.sh} javac -cp $DIR_WHERE_YOU_INSTALLED_MRAA/mraa.jar:. Example.java ~~~~~~~~~~~~~ -To run, make sure libmraajava.so is in LD_LIBRARY_PATH +To run, make sure `libmraajava.so` is in `LD_LIBRARY_PATH` ~~~~~~~~~~~~~{.sh} jave -cp $DIR_WHERE_YOU_INSTALLED_MRAA/mraa.jar:. Example ~~~~~~~~~~~~~ -## Building an IPK/RPM package using cpack +## Building an IPK/RPM package using `cpack` -You can get cpack to generate an IPK or RPM package fairly easily if you have +You can get `cpack` to generate an IPK or RPM package fairly easily if you have the correct packaging tools ~~~~~~~~~~~~~{.sh} @@ -171,7 +174,7 @@ cmake -DIPK=ON -DCMAKE_INSTAL_PREFIX=/usr .. make package ~~~~~~~~~~~~~ -To use RPM simply enable the RPM option. You'll need rpmbuild installed on your +To use RPM simply enable the RPM option. You'll need `rpmbuild` installed on your build machine. ~~~~~~~~~~~~~{.sh}