# Building The Mesh Stack

The mesh library and example applications can be built either using [CMake](https://cmake.org/) or
[SEGGER Embedded Studio](https://www.segger.com/products/development-tools/embedded-studio/?L=0).
Using CMake provides the possiblity to build both for host (unit tests) and target, while SEGGER
Embedded Studio provides a way of getting the example code quickly up and running with full debug
capability.

## Building with SEGGER Embedded Studio

To build with SEGGER Embedded Studio, open the project file located in `examples/examples.emProject`.
To compile the examples, first choose the target you want to compile for: go to
`Build -> Set Active Build Configuration` and select the desired target configuration.

To compile all the projects, go to `Build -> Rebuild Solution`. To flash a specific example to a device,
first right-click on the project you wish to flash and choose `Set as Active Project` (if not already
active). Then connect to the target device using `Target -> Connect J-Link`. The target can then be
flashed using `Target -> Download <example_name>.hex` to flash both the application and the SoftDevice
in one go.

## Building with CMake

To build the example applications using CMake, the following tools are required:

* **CMake**: [CMake](https://cmake.org/) is a build management system used for managing a compiler
  and build system independent environment. Version 3.0 or above is required by the mesh stack.
* **A toolchain**: supported toolchains are the
  [`arm-none-eabi-gcc` toolchain](https://developer.arm.com/open-source/gnu-toolchain/gnu-rm) or the
  [`armcc v5` toolchain](https://developer.arm.com/products/software-development-tools/compilers/arm-compiler/downloads/version-5)
  which is also provided by [Keil](http://www2.keil.com/mdk5/compiler/5/), and comes bundled with the
  [Keil uVision IDE](http://www2.keil.com/mdk5/uvision/).
* **A Build System**: CMake supports a range of build systems, the preferred build system for the
  Microsoft Windows operating system is [Ninja](https://ninja-build.org/). Ninja comes in the form
  of a single executable, which should be placed in a folder that is referenced by the system path
  (i.e. the PATH environment variable). The preferred build system for unix based operating systems
  is [Make](http://pubs.opengroup.org/onlinepubs/9699919799/utilities/make.html).

**Note**: All the examples built by the CMake generated build system does not include the SoftDevice
as part of the generated hex files, and the SoftDevice must be already present on the device before
flashing the hex file for the example mesh application.

To build and run the unit tests on a host computer, the following tools are needed:

* **GCC**: used to build the unit tests
* **Unity**: [Unity](github.com/ThrowTheSwitch/Unity) is the unit testing framework used for running the tests.
* **CMock**: [CMock](github.com/ThrowTheSwitch/CMock) is used by the unit tests in order to generate mocks.
* **Ruby**: used by CMock.

**Note**: Currently, the CMock version used in this project is an internal fork of the public repository.
This means that downloading the official version of CMock might not work.

### Building on Windows
In order to build with Ninja, the correct build files need to be generated first by using CMake
`cmake -G Ninja <root directory for the mesh stack repository>`. Once the Ninja build files are generated
running `ninja` will build all the targets (examples and libraries) except for documentation and pc-lint.
In order to see a list of available build targets, running `ninja -t targets` will show the options
available; a specific target can be built by specifying it from this list such as: `ninja 51_MBTLE_CORE`.

CMake will generage ninja build files in the folder the CMake is run (but not in any of its subfolders),
so all targets need to be built from that directory. In otherwords, in-directory building is not supported,
i.e. running `ninja` in one of the examples will result in an error message generated by the Ninja build system.

It is recommended that a build folder is created where all the artifacts generated by the Ninja build
system are stored, such as:
```
    mesh-btle $ mkdir build      # Create a build directory
    mesh-btle $ cd build         # Move into that directory
    build $ cmake -G Ninja ..    # Generate build files
    build $ ninja
```

However, the mesh stack can be built from its root directory, which will place the generated
artifacts in the folder where the source files are kept.
```
    mesh-btle $ cmake -G Ninja    # Generate build files
    mesh-btle $ ninja
```
By default CMake is configured to build for target using the armcc v5 compiler. In order to build
with arm-none-eabi-gcc, the `BUILD_TOOLCHAIN` needs to be set to `GCC`, for example:
```
    mesh-btle $ mkdir build && cd build             # Create a build directory
    build $ cmake -G Ninja -DBUILD_TOOLCHAIN=GCC .. # Generate build files
    build $ ninja
```
In order to build for host (i.e. PC), so that the unit tests can be run, the option `BUILD_HOST` should
be set to `ON`, and the path to unity and cmock provided:
```
    mesh-btle  $ mkdir host_build && cd host_build
    host_build $ cmake -G Ninja -DBUILD_HOST=ON -DUNITY_ROOT=<dir/unity> -DCMOCK_ROOT=<dir/cmock> ..
    host_build $ ninja
    host_build $ ctest # Run all unit tests
```
### Building on Linux
CMake can generate `make` files as well, which is natively supported by Linux and is the preferred
method of building C based programs. On Linux, the build system will default to GCC and Make.
So in order to build on Linux with GCC:
```
    mesh-btle $ mkdir build && cd build       # Create a build directory
    build $ cmake ..                          # Generate build files
    build $ make
```
Building on Linux with armcc v5:
```
    mesh-btle $ mkdir build && cd build       # Create a build directory
    build $ cmake -DBUILD_TOOLCHAIN=ARM ..    # Generate build files
    build $ make
```

### Building the Documentation

To build all documentation (API documentation and internal documentation), the build system should
be called with the target `doc`. i.e. `ninja doc` in Microsoft Windows, and `make doc` in Linux.

The Doxygen documentation is generated in `<build folder>/mesh/doc/html`.

