Developer cookbook

Build options

Developer build:

$ scons -Q --build-3rdparty=... \
  --enable-werror --enable-debug --enable-tests --enable-benchmarks \
  --enable-examples --enable-doxygen test bench

Explanation:

  • -Q enables compact colored build output
  • --build-3rdparty specifies the list of dependencies to be downloaded and built automatically
  • --enable-werror turns compiler and Doxygen warnings into error
  • --enable-debug enables debug build
  • --enable-tests enables building of unit tests
  • --enable-benchmarks enables building of micro benchmarks
  • --enable-examples enables building of API usage examples
  • --enable-doxygen enables running Doxygen and producing warnings for undocumented members
  • test is the target to run unit tests
  • bench is the target to run micro benchmarks

For --build-3rdparty option, see User cookbook.

For developer build, you may also want to automatically download and build CppUTest (for unut tests) and Google Benchmark (for micro behcmarks):

$ scons -Q --build-3rdparty=...,cpputest,google-benchmark ...

Additionally, you can enable GCC/Clang sanitizers:

$ scons -Q --sanitizers=undefined,address ...
$ scons -Q --sanitizers=all ...

Minimal build (don’t build library and tools):

$ scons -Q --build-3rdparty=... --disable-lib --disable-tools

Disable specific dependencies (and features they provide):

$ scons -Q --build-3rdparty=... --disable-libunwind --disable-openfec \
  --disable-speexdsp --disable-sox --disable-pulseaudio

Compiler options

Select specific compiler:

$ scons -Q --compiler=gcc ...
$ scons -Q --compiler=gcc-4.8 ...
$ scons -Q --compiler=gcc-4.8.5 ...

Select toolchain for cross-compiling:

# arm-linux-gnueabihf-g++ should be in PATH
$ scons -Q --host=arm-linux-gnueabihf ...

Select both compiler and toolchain:

# arm-linux-gnueabihf-clang++ should be in PATH
$ scons -Q --compiler=clang --host=arm-linux-gnueabihf ...

Specify search paths manually:

$ scons -Q --with-openfec-includes=... --with-includes=... --with-libraries=...

Specify tools and flags manually:

$ scons -Q CXX="..." CXXFLAGS="..." ...

or:

$ export CXX="..."
$ export CXXFLAGS="..."
$ scons -Q ...

The full list of the available options and variables is documented in SCons options.

Building dependencies

Download and build selected dependencies, then build everything:

$ scons -Q --build-3rdparty=libuv:1.4.2,libunwind,openfec,cpputest ...

Download and build all dependencies, then build everything:

$ scons -Q --build-3rdparty=all

Per-module targets

Build one module:

$ scons -Q ... roc_core

Run tests for one module:

$ scons -Q ... test/roc_core

Run benchmarks for one module:

$ scons -Q ... bench/roc_core

Running tests manually

Run tests for the module manually:

$ ./bin/x86_64-pc-linux-gnu/roc-test-pipeline -v

Run a single test group:

$ ./bin/x86_64-pc-linux-gnu/roc-test-pipeline -v -g receiver_source

Run a single test:

$ ./bin/x86_64-pc-linux-gnu/roc-test-pipeline -v -g receiver_source -n one_session_long_run

Enable trace logging:

$ ./bin/x86_64-pc-linux-gnu/roc-test-core -t

Run benchmarks for the module manually:

$ ./bin/x86_64-pc-linux-gnu/roc-bench-pipeline

Formatting code

Format code. Requires clang-format:

$ scons -Q fmt

Building documentation

Build all documentation. Requires doxygen, sphinx-build, and breathe-apidoc.

$ scons -Q --enable-werror --enable-doxygen --enable-sphinx docs

Or build specific parts of documentation:

$ scons -Q --enable-werror --enable-doxygen --enable-sphinx doxygen
$ scons -Q --enable-werror --enable-doxygen --enable-sphinx sphinx

Remove generated documentation:

$ scons -Q cleandocs

Run doxygen manually:

# internal modules (HTML)
$ cd src/modules
$ doxygen

# public api (XML for sphinx)
$ cd src/lib
$ doxygen

Cleaning build results

Clean everything:

$ scons -Q -c

or:

$ scons -Q clean

Clean build results except third-parties and documentation:

$ scons -Q cleanbuild

Clean only built documentation:

$ scons -Q cleandocs