1\page mipi_syst_building_page Building SyS-T
2
3[TOC]
4
5Building the SyS-T Library                  {#mipi_syst_building}
6=========================================================================
7
8The SyS-T library includes CMake build support scripts. CMake is an
9open-source, cross-platform build environment that is available for all major
10platforms. The CMake tooling is available from https://cmake.org.
11
12Requirements for building SyS-T {#mipi_syst_build_req}
13=========================================================================
14The SyS-T Library requires the following tooling for building
15
16Component              |Description
17-----------------------|--------------------------
18CMake (https://cmake.org)|Build and packaging system
19C-Compiler             | Needed to build library from its C-Source code
20C++-Compiler           | Needed for building the unit test suite
21Google Test (https://github.com/google/googletest)|Needed for building the unit test suite
22Doxygen(www.doxygen.org)| Needed for building the HTML documentaion
23
24Configuring the build {#mipi_syst_build_conf}
25=========================================================================
26CMake based projects require configuration for generating the platform native
27build support files from the CMake scripts. Configuring the SyS-T CMake scripts
28follows CMake standard methodologies. Use the CMake documentation to familiarize
29yourself with the CMake build environment.
30
31The SyS-T project uses the following configuration options:
32
33Configuration             |Description
34--------------------------|--------------------------------
35SYST_CFG_CONFORMANCE_LEVEL| The library conformance level setting (10=minimal, 20=cpu low overhead, 30=complete).
36SYST_BUILD_PLATFORM_NAME  | The name of the platform adaptation code directory (see also: @ref mipi_syst_adapting_platform).
37SYST_BUILD_GTEST_DIR      | File system location of the Google Test framework source code. This code is needed for the library unit tests only.
38SYST_BUILD_TEST           | Option to enable/disable generation of unit tests.
39SYST_BUILD_DOC            | Option to enable/disable generation of the HTML documentation (requires Doxygen)
40CMAKE_INSTALL_PREFIX      | File System location for installing the SyS-T build.
41
42Configuring using the CMake Gui
43------------------------------------------------------------------------------
44The CMake distribution includs a GUI front end for setting up a configuration.
45The GUI front end is started using the cmake-gui command.
46
47Perform the following steps inside the CMake Gui:
48
49- Point the "Where is the source code:" field to the library directory inside
50  the SyS-T distribution.
51- Point the "Where to build the binaries:" field to a temporary location. This
52  directory will hold build artifacts like object files. Note: This is not the
53  installation location for the build result.
54- Press "Configure".
55  A new dialog appears for selecting the desired native platform build tooling.
56  Select the desired tooling and press "Finish". CMake now parses the build
57  scripts and populates the variable table with build configuration options.
58- Update the path for the variable ``CMAKE_INSTALL_PREFIX`` to point to your
59  desired install location.
60- To build the unit tests, update the ``SYST_BUILD_GTEST_DIR`` variable to point
61  to the Google Test sources and check the ``SYST_BUILD_TEST`` field.
62- To build the HTML documentation, verify that doxygen was found by CMake and
63  check the ``SYST_BUILD_DOC`` option.
64- Press "Configure" again to activate the changed settings.
65- Press "Generate" to generate the native build configuration files.
66
67Configuring using the CMake command line
68------------------------------------------------------------------------------
69The SyS-T project can be configured with command line option, following
70CMake standard methodologies. Follow these steps to setup a project using the
71command line.
72
73- Create a new directory for holding the build artifact files and enter this
74  directory
75
76        $ mkdir syst_build
77        $ cd syst_build
78
79- Run the configuration using the cmake tool. The following call shows an
80 example with all options set:
81
82 ```
83 $ cmake \
84     -DSYST_BUILD_GTEST_DIR=/home/username/googletest \
85     -DSYST_BUILD_TEST=ON \
86     -DSYST_BUILD_DOC=ON \
87     -DSYST_BUILD_PLATFORM=example \
88     -DCMAKE_INSTALL_PREFIX=/opt/mipi_syst \
89     /home/jdoe/src/sys_t
90```
91
92Building and Installing {#mipi_syst_building_deploy}
93=========================================================================
94The build system provides various targets for building and installing the
95SyS-T library, header files and documentation. The following table shows which
96targets exist:
97
98Target Name     |Description
99----------------|--------------------------------
100all             | Build binaries and, if enabled, the unit tests
101doc             | Build HTML documentation
102syst_unittest   | Build unit tests
103install         | Install to CMAKE_INSTALL_PREFIX location, implies 'all'
104clean           | Remove build artifacts
105RUN_TEST        | Run the tests (not showing test output)
106RUN_TEST_VERBOSE| Run the tests (showing test output)
107
108Integration Build and Test Script
109=========================================================================
110A bash script in ``examples/scripts/bldall.sh`` can be used to run an
111integration test using the different projects. The script builds all projects
112sequentially using the example library platform. It then runs their components
113tests and finally calls the printer tool to format the output of
114the ``hello`` example application. The following transcript shows how to
115run execute the script. The BLD_ROOT variable sets the location of the build
116folder. If unset, the script creates a local build folder inside the scripts
117folder.
118
119```
120$ cd sys-t/examples/scripts
121$ BLD_ROOT=/tmp/sys_t_test_bld ./bldall.sh
122```
123