Developer cookbook¶
Table of contents:
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 memberstest
is the target to run unit testsbench
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.
macOS options¶
There are a few macOS-specific build options:
--macos-platform
- specify macOS target platform version, a.k.a. macOS deployment target, for example10.12
.Resulting binaries will be compatible with all OS versions starting from the specified one, even if you’re compiling on a different version. This requires all Roc dependencies to be built with the the same deployment target too. If you’re using
--build-3rdparty
to build dependencies, deployment target will be automatically propagated to them.--macos-arch
- specify macOS target architecture(s), for examplex86_64
orarm64
.You can specify multiple architectures (comma-separated) to produce universal binaries (a.k.a. fat binaries) that contain code for every architecture and can be executed on each of them. Use special architecture
all
to enable all supported architectures.
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
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