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)
• libarcstk – dependency of libarcsdec

Optional Buildtime Dependencies

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

Libarcsdec can use of the following libraries to parse or read input formats:

Each dependency to a library in this list can be activated or de-activated for building by using its corresponding configure switch.

Some of these dependencies are activated for building by default (see Configure switches). They can be deactivated safely if not required.

Of course, it is possible to deactivate all dependencies. Deactivating all dependencies renders libarcsdec incapable of reading most input formats. Libarcsdec without any dependencies is only capable of reading the following input formats:

• WAV audio files encoding PCM-16bit stereo, 44100 Hz (== CDDA)
• Cuesheets
• CDRDAO's toc files

NOTE on ffmpeg:

Libarcsdec uses the decoding API introduced with libavcodec 57.37.100 on 21, April 2016, hence the requirements are:

which determines ffmpeg 3.1 as the earliest possible version. Libarcsdec can not be compiled against earlier versions of ffmpeg.

Installed files

The following 13 files will be installed to your system:

• The shared object libarcsdec.so.x.y.z (along with a symbolic link libarcsdec.so) in the standard library location (e.g. /usr/local/lib)
• The 7 public header files audioreader.hpp, calculators.hpp, descriptor.hpp, metaparser.hpp, sampleproc.hpp, selection.hpp and version.hpp in the default include location (e.g. /usr/local/include).
• The 4 cmake packaging files libarcsdec-config.cmake, libarcsdec-config-version.cmake, libarcsdec-targets.cmake and libarcsdec-targets-release.cmake in directory libarcsdec beneath the default cmake location (e.g. /usr/local/lib/cmake). Those files allow other projects to simply import libarcsdec's exported cmake targets.
• The pkg-config configuration file libarcsdec.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 libarcsdec in her project)
• Contributing developer (who intends to debug and test libarcsdec and maybe contribute to the documentation)
• Package maintainer (who intends to package libarcsdec for some target system).

Users

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

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

Note that this presupposes the three optional buildtime dependencies that are activated in the default configuration:

• ffmpeg
• FLAC++
• libwavpack

Any of the configure switches can be used to deactivate optional dependencies which are activated by default.

For example to compile without libwavpack, do:

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

Contributors

You want to debug into the libarcsdec code, hence you need to build libarcsdec 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 libarcsdec 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 libarcsdec 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++

Libarcsdec 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.

Build with libarcstk as a submodule

Having installed the dependencies system-wide is considered the standard setup. For some development tasks, this may nonetheless not be convenient. If installing libarcstk is for any reason not applicable, libarcstk can alternatively be build as a submodule of libarcsdec. For setting up a fresh local libarcsdec repo with libarcstk as a submodule of libarcsdec, do the following:

$ git clone --recurse-submodules https://github.com/crf8472/libarcsdec
$ cd libarcsdec      # your libarcsdec root folder where README.md resides
$ mkdir build && cd build  # create build folder for out-of-source-build
$ cmake -DWITH_SUBMODULES=ON .. # add any switches required
$ cmake --build .    # perform the actual build (including libarcstk)

Alternatively, if you already have cloned libarcsdec without using the --recurse-submodules switch, you can alternatively setup the submodule thereafter by applying:

$ cd libarcsdec      # your libarcsdec root folder where README.md resides
$ git submodule init
$ git submodule update # clones libarcstk as a submodule
$ mkdir build && cd build  # create build folder for out-of-source-build
$ cmake -DWITH_SUBMODULES=ON ..

Note that if libarcsdec was configured with -DWITH_SUBMODULES=ON any switches will be applied to libarcstk as well! If you use -DWITH_TESTS or WITH_DOCS when configuring libarcsdec those options will be applied recursively to libarcstk. Equivalently, using make install will install libarcsdec as well as libarcstk!

Note that this setup is only intended to make handling synchronous development tasks (such as debugging) on both libraries libarcsdec and libarcstk easier. It is not intended to support packaging or installation in productional environments.

Cleaning the project

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

$ cmake -P CMakeFiles/libarcsdec.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 libarcsdec 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)

Libarcsdec 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.