FOSS-VG/doc/build_system.md

FOSS-VG Build System

Yeah, I was annoyed at make. Sorry. -BodgeMaster

Aliases

The shell environment provided in the project's base directory contains aliases that can be invoked from anywhere. This is useful if you, for example, cd src/lib and want to do a quick rebuild, you can just run build and it will take care of switching directories back and forth.

Where necessary, the "aliases" are shell functions instead of literal aliases to accommodate for inline environment variables.

Provided aliases:

• setup_project runs scripts/setup_project.sh
• build runs scripts/build.sh
• run_tests runs scripts/test.sh (we can't alias test because that's an actual POSIX command and it would break a lot of things)
• clean runs scripts/clean.sh
• clean_dependencies runs scripts/clean_dependencies.sh

setup_project

Cleans the project and its dependencies first (see below), ensuring the project is in a known state, then sets up dependencies.

This includes downloading (and caching) of files that are not yet locally cached and compiling dependencies that need to be compiled.

This script’s intended purpose is setting up a development environment but it can also be used to update the locally set-up dependencies to the ones that the project is using.

build

Builds the project. This will compile all the things in src/ except for what is in src/test/.

Checks for endianness if endianness header is missing. Builds the endianness check if that is missing as well.

Accepted environment variables:

• CXX: override the default compiler
• CXXFLAGS: override the default compiler flags, must at least specify the C++ version
• SINGLE: if set to yes, causes the build script to run in single-threaded mode

test / run_tests

Builds and runs the unit tests.

Accepted environment variables:

• CXX: override the default compiler
• CXXFLAGS: override the default compiler flags, must at least specify the C++ version
• SINGLE: if set to yes, causes the test script to compile the tests in single-threaded mode¹

¹Unit tests are always run one after the other.

clean

Removes and re-creates bin/ and include/, then re-creates symlinks to shared object and header files as needed for the build process. Also removes the endianness header and the endianness check binary.

clean_dependencies

Removes and re-creates dependencies/ and prunes the download cache of files that either have been corrupted or are no longer used.

lib

This is not a script you are supposed to run. It's a library that contains some functions for the other scripts to work properly on all platforms.

Features it provides:

• $WAIT_ANYWAY: a variable containing the wait command if SINGLE=yes is set.
• $CXX_WITH_FLAGS: deals with CXX and CXXFLAGS environment variables so it can be used as a generic compiler command
• function check_sha256: deals with sha256sum and NetBSD's sha256
• function remove: better verbosity
• function create_directory: alternative to mkdir -v because that's not available on some systems
• function create_file: the same but for files