summaryrefslogtreecommitdiffstats
path: root/docs/BUILDING.md
diff options
context:
space:
mode:
authorTavian Barnes <tavianator@tavianator.com>2024-04-08 11:27:11 -0400
committerTavian Barnes <tavianator@tavianator.com>2024-04-09 17:15:23 -0400
commitc31577d102d87455f3f12086be4c0e2159fa5d35 (patch)
tree864c7c199e5b846dcf497de8b667d6c6f8c550b9 /docs/BUILDING.md
parent5e0b721d0d929223e4308406480a1f1ca9e3f4dc (diff)
downloadbfs-c31577d102d87455f3f12086be4c0e2159fa5d35.tar.xz
build: Add a separate configuration step
Diffstat (limited to 'docs/BUILDING.md')
-rw-r--r--docs/BUILDING.md83
1 files changed, 44 insertions, 39 deletions
diff --git a/docs/BUILDING.md b/docs/BUILDING.md
index 7eb3a37..abf6185 100644
--- a/docs/BUILDING.md
+++ b/docs/BUILDING.md
@@ -7,9 +7,10 @@ Compiling
`bfs` uses [GNU Make](https://www.gnu.org/software/make/) as its build system.
A simple invocation of
+ $ make config
$ make
-should build `bfs` successfully, with no additional steps necessary.
+should build `bfs` successfully.
As usual with `make`, you can run a [parallel build](https://www.gnu.org/software/make/manual/html_node/Parallel.html) with `-j`.
For example, to use all your cores, run `make -j$(nproc)`.
@@ -17,25 +18,28 @@ For example, to use all your cores, run `make -j$(nproc)`.
| Command | Description |
|------------------|---------------------------------------------------------------|
+| `make config` | Configures the build system |
| `make` | Builds just the `bfs` binary |
| `make all` | Builds everything, including the tests (but doesn't run them) |
| `make check` | Builds everything, and runs the tests |
| `make install` | Installs `bfs` (with man page, shell completions, etc.) |
| `make uninstall` | Uninstalls `bfs` |
+| `make clean` | Delete the build products |
+| `make mrclean` | Delete all generated files, including the build configuration |
-### Flag-like targets
+### Build profiles
-The build system provides a few shorthand targets for handy configurations:
+The configuration system provides a few shorthand flags for handy configurations:
-| Command | Description |
-|----------------|-------------------------------------------------------------|
-| `make release` | Build `bfs` with optimizations, LTO, and without assertions |
-| `make asan` | Enable [AddressSanitizer] |
-| `make lsan` | Enable [LeakSanitizer] |
-| `make msan` | Enable [MemorySanitizer] |
-| `make tsan` | Enable [ThreadSanitizer] |
-| `make ubsan` | Enable [UndefinedBehaviorSanitizer] |
-| `make gcov` | Enable [code coverage] |
+| Command | Description |
+|-------------------------|-------------------------------------------------------------|
+| `make config RELEASE=y` | Build `bfs` with optimizations, LTO, and without assertions |
+| `make config ASAN=y` | Enable [AddressSanitizer] |
+| `make config LSAN=y` | Enable [LeakSanitizer] |
+| `make config MSAN=y` | Enable [MemorySanitizer] |
+| `make config TSAN=y` | Enable [ThreadSanitizer] |
+| `make config UBSAN=y` | Enable [UndefinedBehaviorSanitizer] |
+| `make config GCOV=y` | Enable [code coverage] |
[AddressSanitizer]: https://github.com/google/sanitizers/wiki/AddressSanitizer
[LeakSanitizer]: https://github.com/google/sanitizers/wiki/AddressSanitizerLeakSanitizer#stand-alone-mode
@@ -44,38 +48,38 @@ The build system provides a few shorthand targets for handy configurations:
[UndefinedBehaviorSanitizer]: https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html
[code coverage]: https://gcc.gnu.org/onlinedocs/gcc/Gcov.html
-You can combine multiple flags and other targets (e.g. `make asan ubsan check`), but not all of them will work together.
+You can combine multiple profiles (e.g. `make config ASAN=y UBSAN=y`), but not all of them will work together.
### Flags
-Other flags are controlled with `make` variables and/or environment variables.
-Here are some of the common ones; check the [`GNUmakefile`](/GNUmakefile) for more.
-
-| Flag | Description |
-|----------------------------------|---------------------------------------------|
-| `CC` | The C compiler to use, e.g. `make CC=clang` |
-| `CFLAGS`<br>`EXTRA_CFLAGS` | Override/add to the default compiler flags |
-| `LDFLAGS`<br>`EXTRA_LDFLAGS` | Override/add to the linker flags |
-| `USE_ACL`<br>`USE_LIBCAP`<br>... | Enable/disable [optional dependencies] |
-| `TEST_FLAGS` | `tests.sh` flags for `make check` |
-| `BUILDDIR` | The build output directory (default: `.`) |
-| `DESTDIR` | The root directory for `make install` |
-| `PREFIX` | The installation prefix (default: `/usr`) |
-| `MANDIR` | The man page installation directory |
+Other flags can be specified on the `make config` command line or in the environment.
+Here are some of the common ones; check the [`Makefile`](/Makefile) for more.
+
+| Flag | Description |
+|----------------------------------|----------------------------------------------------|
+| `CC` | The C compiler to use, e.g. `make config CC=clang` |
+| `CFLAGS`<br>`EXTRA_CFLAGS` | Override/add to the default compiler flags |
+| `LDFLAGS`<br>`EXTRA_LDFLAGS` | Override/add to the linker flags |
+| `USE_ACL`<br>`USE_LIBCAP`<br>... | Enable/disable [optional dependencies] |
+| `TEST_FLAGS` | `tests.sh` flags for `make check` |
+| `BUILDDIR` | The build output directory (default: `.`) |
+| `DESTDIR` | The root directory for `make install` |
+| `PREFIX` | The installation prefix (default: `/usr`) |
+| `MANDIR` | The man page installation directory |
[optional dependencies]: #dependencies
### Dependencies
`bfs` depends on some system libraries for some of its features.
-These dependencies are optional, and can be turned off at build time if necessary by setting the appropriate variable to the empty string (e.g. `make USE_ONIGURUMA=`).
+These dependencies are optional, and can be turned off in `make config` if necessary by setting the appropriate variable to `n` (e.g. `make config USE_ONIGURUMA=n`).
-| Dependency | Platforms | `make` flag |
-|-------------|------------|-----------------|
-| [acl] | Linux only | `USE_ACL` |
-| [libcap] | Linux only | `USE_LIBCAP` |
-| [liburing] | Linux only | `USE_LIBURING` |
-| [Oniguruma] | All | `USE_ONIGURUMA` |
+| Dependency | Platforms | `make config` flag |
+|-------------|------------|--------------------|
+| [acl] | Linux only | `USE_ACL` |
+| [libcap] | Linux only | `USE_LIBCAP` |
+| [liburing] | Linux only | `USE_LIBURING` |
+| [Oniguruma] | All | `USE_ONIGURUMA` |
[acl]: https://savannah.nongnu.org/projects/acl
[libcap]: https://sites.google.com/site/fullycapable/
@@ -84,21 +88,22 @@ These dependencies are optional, and can be turned off at build time if necessar
### Dependency tracking
-The build system automatically tracks header dependencies with the `-M` family of compiler options (see `DEPFLAGS` in the [`GNUmakefile`](/GNUmakefile)).
+The build system automatically tracks header dependencies with the `-M` family of compiler options (see `DEPFLAGS` in the [`Makefile`](/Makefile)).
So if you edit a header file, `make` will rebuild the necessary object files ensuring they don't go out of sync.
+We also add a dependency on the current configuration, so you can change configurations and rebuild without having to `make clean`.
+
We go one step further than most build systems by tracking the flags that were used for the previous compilation.
That means you can change configurations without having to `make clean`.
For example,
+ $ make config
+ $ make
+ $ make config RELEASE=y
$ make
- $ make release
will build the project in debug mode and then rebuild it in release mode.
-A side effect of this may be surprising: `make check` by itself will rebuild the project in the default configuration.
-To test a different configuration, you'll have to repeat it (e.g. `make release check`).
-
Testing
-------