How to Build

Mandatory Buildtime Dependencies

• C++-17-compliant-compiler with C++ standard library
• cmake >= 3.10
• make or some other build tool compatible to cmake (the examples suppose make nonetheless)

Optional Buildtime Dependencies

If you intend to run the tests or build the documentation, there are some more dependencies required.

Installed files

The following 18 files will be installed to your system:

• The shared object libarcstk.so.x.y.z (along with a symbolic link libarcstk.so) in the standard library location (e.g. /usr/local/lib).
• The 12 public header files accuraterip.hpp, algorithms.hpp, calculate.hpp, checksum.hpp, dbar.hpp, identifier.hpp, logging.hpp, metadata.hpp, policies.hpp, samples.hpp, verify.hpp, and version.hpp in the the subfolder arcstk in the default include location (e.g. /usr/local/include).
• The 4 cmake packaging files libarcstk-config.cmake, libarcstk-config-version.cmake, libarcstk-targets.cmake and libarcstk-targets-release.cmake in directory libarcstk beneath the default cmake location (e.g. /usr/local/lib/cmake). Those files allow other projects to simply import libarcstk's exported cmake targets.
• The pkg-config configuration file libarcstk.pc in the default pkgconfig location (e.g. /usr/local/lib/pkgconfig).

The default installation prefix can be changed by passing the actual prefix to cmake. This is achieved by using the switch -DCMAKE_INSTALL_PREFIX=/path/to/install/dir in the configure step. See Configure switches for more configuration options.

We describe the build configuration for the following profiles:

• User (read: a developer who uses libarcstk in her project)
• Contributing developer (who intends to debug and test libarcstk and maybe contribute to the documentation)
• Package maintainer (who intends to package libarcstk for some target system).

Users

You intend to install libarcstk on your system, say, as a dependency for your own project. You just need libarcstk to be available along with its headers and not getting in your way:

$ cmake -DCMAKE_BUILD_TYPE=Release ..
$ cmake --build .
$ sudo make install

Contributors

You want to debug into the libarcstk code, hence you need to build libarcstk with debugging symbols and without aggressive optimization:

$ cmake -DCMAKE_BUILD_TYPE=Debug ..

For also building and running the tests, just use the corresponding switch:

$ cmake -DCMAKE_BUILD_TYPE=Debug -DWITH_TESTS=ON ..

Thereafter just start the build and run the tests:

$ cmake --build .
$ ctest

Note: This build will take significantly longer than the build without tests.

Package maintainers

You want to build libarcstk with a release profile but without any architecture specific optimization (e.g. without -march=native and -mtune=generic for g++ or clang++).

Furthermore, you would like to adjust the install prefix path such that libarcstk is configured for being installed in the real system prefix (such as /usr) instead of some default prefix (such as /usr/local).

You may also want to specify a staging directory as an intermediate install target.

When using clang++ or g++, all of these can be achieved as follows:

$ cmake -DCMAKE_BUILD_TYPE=Release -DWITH_NATIVE=OFF -DCMAKE_INSTALL_PREFIX=/usr ..
$ cmake --build .
$ make DESTDIR=/my/staging/dir install

Note that -DWITH_NATIVE=OFF currently only works for clang++ and g++. The build process is untested and broken on other compilers.

If you use another compiler than clang++ or g++, CMake will not apply any project specific modifications to the compiler default settings. Therefore, you have to carefully inspect the build process (e.g. by using $ make VERBOSE=1 instead of cmake --build .) to verify which compiler settings are actually used.

Configure switches

Note that USE_DOC_TOOL can be passed multiple values. For example, building the HTML version as well as the manual in one build run is achieved by:

$ cmake -DUSE_DOC_TOOL=MCSS\;LUALATEX ..

Switch between clang++ and g++

Libarcstk is tested to compile with clang++ as well as with g++.

If you want to switch the compiler, you should just hint CMake what compiler to use. On unixoid systems you can usually do this via the environment variables CC and CXX.

If your current compiler is not clang++ and you want to use your installed clang++:

$ export CC=$(type -p clang)
$ export CXX=$(type -p clang++)

If your current compiler is not g++ and you want to use your installed g++:

$ export CC=$(type -p gcc)
$ export CXX=$(type -p g++)

Delete your directory build since it contains metadata from the previous compiler. Start off cleanly.

$ cd ..
$ rm -rf build

CMake-reconfigure the project to have the change take effect:

$ mkdir build && cd build
$ cmake ..

To check whether your setting took effect, observe the CMake output. During the configure step, CMake informs about the actual C++-compiler like:

-- The CXX compiler identification is Clang 19.1.7
...
-- Check for working CXX compiler: /usr/bin/clang++ - works

Turn optimizing on/off

You may or may not want the -march=native and -mtune=generic switches on compilation. For Debug-builds, they are OFF by default, but can be added by using -DWITH_NATIVE=ON. For now, this switch has only influence when using g++ or clang++. For other compilers, default settings apply.

Run unit tests

Note that -DWITH_TESTS=ON will try to git-clone the testing framework Catch2 within your build directory and fail if this does not work.

Running the unit tests is not part of the build process. To run the tests, invoke ctest manually in the build directory after cmake --build . is completed.

Note that ctest will write report files in the build folder, their name pattern is report.<testcase>.xml where <testcase> corresponds to a .cpp-file in test/src.

Cleaning the project

Clean only the shared library binaries (when in directory build):

$ cmake -P CMakeFiles/libarcstk.dir/cmake_clean.cmake

Clean the project entirely:

$ cmake --build . --target clean

Note that this forces to recompile everything including Catch2 if -DWITH_TESTS is configured.

Completely wipe everything configured and built locally (when in top-level directory):

$ rm -rf build

Website: Doxygen Stock HTML

The generation of the documentation sources must be requested at configuration stage. The documentation sources will not be generated automatically during build. It is required to call target doc manually.

$ cd build
$ cmake -DWITH_DOCS=ON ..
$ cmake --build . --target doc

This will build the documentation sources for HTML in subdirectories of build/generated-docs/doxygen. Open the file build/generated-docs/doxygen/html/index.html in your browser to see the entry page.

Website: m.css with HTML5 and CSS3 via doxygen's XML

Accompanying m.css comes a doxygen style. It takes the doxygen XML output and generates a static site in plain HTML5 and CSS3 from it (nearly without JavaScript).

The public APIdoc of libarcstk is build with m.css.

This APIdoc can be built locally by the following steps:

$ cd build
$ cmake -DWITH_DOCS=ON -DUSE_DOC_TOOL=MCSS ..
$ cmake --build . --target doc

CMake then creates a local python sandbox in directory build using virtualenv, installs jinja2 and Pygments in it, then clones m.css, and then runs m.css which internally runs doxygen. Maybe this process needs finetuning for some environments. (It is completely untested on Windows and will not work.)

Documentation is generated in build/generated-docs/mcss and you can load build/generated-docs/mcss/html/index.html in your browser.

Manual: PDF by LaTeX (smoke-tested, more or less)

Libarcstk is supposed to provide support for a PDF manual using LaTeX at some point in the future. Currently, it is possible to create a manual for just working on the process. Do not expect satisfying results.

An actual LaTeX installation (containing lualatex and epstopdf) is required for creating the manual.

Building the PDF manual can be requested by using -DUSE_DOC_TOOL=LUALATEX. It will thereby be typeset by building the doc target.

The entire process:

$ cd build
$ cmake -DWITH_DOCS=ON -DUSE_DOC_TOOL=LUALATEX ..
$ cmake --build . --target doc

This will create the manual refman.pdf in folder build/generated-docs/doxygen/lualatex (while issuing loads of warnings, which is perfectly normal).

Note that I did never give any love to the manual. It will build. Not more. However, it will not be convenient to read or look good at its current stage.