diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/BUILDING.md | 83 | ||||
| -rw-r--r-- | docs/USAGE.md | 2 |
2 files changed, 45 insertions, 40 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 ------- diff --git a/docs/USAGE.md b/docs/USAGE.md index 071c95b..70f8475 100644 --- a/docs/USAGE.md +++ b/docs/USAGE.md @@ -7,8 +7,8 @@ When invoked with no arguments, `bfs` will list everything under the current dir ```console $ bfs . -./GNUmakefile ./LICENSE +./Makefile ./README.md ./completions ./docs |