Build Process

SPEXone processor is dependent on the CMake build system generator. CMake is a set of tools for configuring, building, and testing software, and is released under the New BSD License. Building the processor is a two-step process: we must first run CMake to generate the build files, e.g. GNU Makefiles, and then issue the build command, e.g. make.

First step is to obtain CMake. On Ubuntu and similar distributions it can likely be installed by issuing

sudo apt-get install cmake

When running CMake (the configuration step) it creates a set of persistent variables which are contained in a file called CMakeCache.txt in the build directory. These are referred to as cache variables and they are the user-configurable settings of the project. All the important decisions such as which compiler to use, which libraries to link against, etc., are stored as cache variables. There are several ways of setting the cache variables, one of which is to define them in a file that can be read by CMake. This is called the initial cache file, templates of which are provided with the source code so you don’t have to compose it from scratch. Start by navigating into the SPEXone source directory <spexone_cal>:

cd <spexone_cal>
cp initial_cache.cmake.example initial_cache.cmake

If you are using one of SRON’s computers then copy the one from the SRON directory instead:

cd <spexone_cal>
cp SRON/initial_cache.cmake.example initial_cache.cmake
# Have a look at SRON/bashrc for hints of how to set up the correct
# environment, in particular for using the correct compilers.

Next, edit the initial cache file to reflect your environment, although the default values might already be fine. When done editing, create a build directory and run CMake from within that directory using the initial cache file:

mkdir build && cd build
cmake -C <spexone_cal>/initial_cache.cmake <spexone_cal>

One can also build directly in the source directory but it is generally a good habit to do out-of-source builds to keep the source directory clean.

Note that editing the initial cache file has no effect after the first configuring! Instead, it is necessary to empty the build directory before running CMake again:

rm -rf * # From within the build directory
cmake -C <spexone_cal>/initial_cache.cmake <spexone_cal>

Tip

Alternatively, if you want to keep the build directory intact while editing a CMake cache variable such as a compiler flag or a library to be linked against, you can use a graphical CMake front end or specify that variable from the command line (the latter will not be demonstrated here). The two commonly used graphical front ends are the command line based ccmake and the Qt-based cmake-gui, obtained by issuing

sudo apt-get install cmake-curses-gui
# or
sudo apt-get install cmake-gui

When using ccmake issue

ccmake .

from the build directory. Some CMake variables and options appear, most of which should be self-explanatory. A short help text to each variable is displayed at the bottom in a status bar. Pressing t reveals all options. When done editing, press c to reconfigure and g to generate the native build files. Pay attention when ccmake warns you that the cache variables have been reset. This will happen, e.g., when changing the compiler, and will necessitate the reconfiguring of some variables.

If CMake ran successfully the next step is to compile the executable. The default build system generated by CMake is GNU makefiles on Linux. Unless you are using a different build system, you can compile with

make -j # or make -j VERBOSE=1 for more verbose output

If you are not sure which build system you are using, run

cmake --build . # make is probably fine though

from within the build directory. If successful, an executable called spexone_cal is produced in the build directory.

Tip

A different build system can be chosen by passing an argument to the CMake generator function. For instance, for using Ninja, use -G Ninja during the initial configuring,

cmake -G Ninja -C <spexone_cal>/initial_cache.cmake <spexone_cal>

The build command is then

ninja
# or
cmake --build .

CMake configuration variables

See initial_cache.cmake.example in the root directory for a list of configuration variables. You can copy and work with that file directly. There is thus no need to list them separately here.