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