FOSS-VG/doc/build_system.md

96 lines
3.1 KiB
Markdown
Raw Permalink Normal View History

# 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 scripts 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