From 99260d347b91f9f7ede335b7f582cee34ead2b0c Mon Sep 17 00:00:00 2001 From: Tavian Barnes Date: Wed, 1 May 2024 14:23:20 -0400 Subject: build: Add some nice aliases to ./configure --- docs/BUILDING.md | 200 +++++++++++++++++++++++++++++++++---------------------- 1 file changed, 122 insertions(+), 78 deletions(-) (limited to 'docs') diff --git a/docs/BUILDING.md b/docs/BUILDING.md index db5d721..cb33c51 100644 --- a/docs/BUILDING.md +++ b/docs/BUILDING.md @@ -1,104 +1,101 @@ Building `bfs` ============== -Compiling ---------- - A simple invocation of $ ./configure $ make 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)`. -### Targets -| Command | Description | -|------------------|---------------------------------------------------------------| -| `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 distclean` | Delete all generated files, including the build configuration | +Configuration +------------- + +```console +$ ./configure --help +Usage: + + $ ./configure [--enable-*|--disable-*] [CC=...] [CFLAGS=...] [...] + $ make + +... +``` + +### Variables + +Variables set in the environment or on the command line will be picked up: +These variables specify binaries to run during the configuration and build process: + +
+MAKE=make
+    make implementation
+CC=cc
+    C compiler
+INSTALL=install
+    Copy files during make install
+MKDIR="mkdir -p"
+    Create directories
+PKG_CONFIG=pkg-config
+    Detect external libraries and required build flags
+RM="rm -f"
+    Delete files
+
+ +These flags will be used by the build process: + +
+CPPFLAGS="-I... -D..."
+CFLAGS="-W... -f..."
+LDFLAGS="-L... -Wl,..."
+    Preprocessor/compiler/linker flags
+
+LDLIBS="-l... -l..."
+    Dynamic libraries to link
+
+EXTRA_{CPPFLAGS,CFLAGS,LDFLAGS,LDLIBS}="..."
+    Adds to the default flags, instead of replacing them
+
### Build profiles -The configuration system provides a few shorthand flags for handy configurations: - -| Command | Description | -|-------------------------|-------------------------------------------------------------| -| `./configure RELEASE=y` | Build `bfs` with optimizations, LTO, and without assertions | -| `./configure ASAN=y` | Enable [AddressSanitizer] | -| `./configure LSAN=y` | Enable [LeakSanitizer] | -| `./configure MSAN=y` | Enable [MemorySanitizer] | -| `./configure TSAN=y` | Enable [ThreadSanitizer] | -| `./configure UBSAN=y` | Enable [UndefinedBehaviorSanitizer] | -| `./configure GCOV=y` | Enable [code coverage] | - -[AddressSanitizer]: https://github.com/google/sanitizers/wiki/AddressSanitizer -[LeakSanitizer]: https://github.com/google/sanitizers/wiki/AddressSanitizerLeakSanitizer#stand-alone-mode -[MemorySanitizer]: https://github.com/google/sanitizers/wiki/MemorySanitizer -[ThreadSanitizer]: https://github.com/google/sanitizers/wiki/ThreadSanitizerCppManual -[UndefinedBehaviorSanitizer]: https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html -[code coverage]: https://gcc.gnu.org/onlinedocs/gcc/Gcov.html - -You can combine multiple profiles (e.g. `./configure ASAN=y UBSAN=y`), but not all of them will work together. - -### Flags - -Other flags can be specified on the `./configure` 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. `./configure CC=clang` | -| `CFLAGS`
`EXTRA_CFLAGS` | Override/add to the default compiler flags | -| `LDFLAGS`
`EXTRA_LDFLAGS` | Override/add to the linker flags | -| `USE_LIBACL`
`USE_LIBCAP`
... | Enable/disable [optional dependencies] | -| `TEST_FLAGS` | `tests.sh` flags for `make check` | -| `DESTDIR` | The root directory for `make install` | -| `PREFIX` | The installation prefix (default: `/usr`) | -| `MANDIR` | The man page installation directory | - -[optional dependencies]: #dependencies +The default flags result in a plain debug build. +Other build profiles can be enabled: -### Dependencies +
+--enable-release
+    Enable optimizations, disable assertions
 
-`bfs` depends on some system libraries for some of its features.
-These dependencies are optional, and can be turned off in `./configure` if necessary by setting the appropriate variable to `n` (e.g. `./configure USE_ONIGURUMA=n`).
+--enable-asan
+--enable-lsan
+--enable-msan
+--enable-tsan
+--enable-ubsan
+    Enable sanitizers
 
-| Dependency   | Platforms  | `./configure` flag |
-|--------------|------------|--------------------|
-| [libacl]     | Linux only | `USE_LIBACL`       |
-| [libcap]     | Linux only | `USE_LIBCAP`       |
-| [liburing]   | Linux only | `USE_LIBURING`     |
-| [libselinux] | Linux only | `USE_LIBSELINUX`   |
-| [Oniguruma]  | All        | `USE_ONIGURUMA`    |
+--enable-gcov
+    Enable code coverage instrumentation
+
-[libacl]: https://savannah.nongnu.org/projects/acl -[libcap]: https://sites.google.com/site/fullycapable/ -[libselinux]: https://github.com/SELinuxProject/selinux -[liburing]: https://github.com/axboe/liburing -[Oniguruma]: https://github.com/kkos/oniguruma +You can combine multiple profiles (e.g. `./configure --enable-asan --enable-ubsan`), but not all of them will work together. -### Dependency tracking +### Dependencies -The build system automatically tracks header dependencies with the `-M` family of compiler options (see `DEPFLAGS` in [`build/deps.mk`](/build/deps.mk)). -So if you edit a header file, `make` will rebuild the necessary object files ensuring they don't go out of sync. +`bfs` depends on some system libraries for some of its features. +External dependencies are auto-detected by default, but you can `--enable` or `--disable` them manually: -We also add a dependency on the current configuration, so you can change configurations and rebuild without having to `make clean`. -For example, +
+--enable-libacl      --disable-libacl
+--enable-libcap      --disable-libcap
+--enable-libselinux  --disable-libselinux
+--enable-liburing    --disable-liburing
+--enable-oniguruma   --disable-oniguruma
+
- $ ./configure - $ make - $ ./configure RELEASE=y - $ make +[`pkg-config`] is used, if available, to detect these libraries and any additional build flags they may require. +If this is undesireable, disable it by setting `PKG_CONFIG` to the empty string (`./configure PKG_CONFIG=""`). -will build the project in debug mode and then rebuild it in release mode. +[`pkg-config`]: https://www.freedesktop.org/wiki/Software/pkg-config/ ### Out-of-tree builds @@ -110,6 +107,53 @@ You can set up an out-of-tree build by running the `configure` script from anoth $ make +Building +-------- + +### Targets + +The [`Makefile`](/Makefile) supports several different build targets: + +
+make
+    The default target; builds just the bfs binary
+make all
+    Builds everything, including the tests (but doesn't run them)
+
+make check
+    Builds everything, and runs all tests
+make unit-tests
+    Builds and runs the unit tests
+make integration-tests
+    Builds and runs the integration tests
+make distcheck
+    Builds and runs the tests in multiple different configurations
+
+make install
+    Installs bfs globally
+make uninstall
+    Uninstalls bfs
+
+make clean
+    Deletes all built files
+make distclean
+    Also deletes files generated by ./configure
+
+ + +Troubleshooting +--------------- + +If the build fails or behaves unexpectedly, start by enabling verbose mode: + + $ ./configure V=1 + $ make V=1 + +This will print the generated configuration and the exact commands that are executed. + +You can also check the file `gen/config.log`, which contains any errors from commands run during the configuration phase. + + Testing ------- -- cgit v1.2.3