Building `bfs`
==============

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.
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 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 distclean` | Delete all generated files, including the build configuration |

### Build profiles

The configuration system provides a few shorthand flags for handy configurations:

| 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
[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. `make config ASAN=y UBSAN=y`), but not all of them will work together.

### Flags

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_LIBACL`<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 in `make config` if necessary by setting the appropriate variable to `n` (e.g. `make config USE_ONIGURUMA=n`).

| Dependency   | Platforms  | `make config` 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`    |

[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

### Dependency tracking

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

will build the project in debug mode and then rebuild it in release mode.


Testing
-------

`bfs` comes with an extensive test suite which can be run with

    $ make check

The test harness is implemented in the file [`tests/tests.sh`](/tests/tests.sh).
Individual test cases are found in `tests/*/*.sh`.
Most of them are *snapshot tests* which compare `bfs`'s output to a known-good copy saved under the matching `tests/*/*.out`.

You can pass the name of a particular test case (or a few) to run just those tests.
For example:

    $ ./tests/tests.sh posix/basic

If you need to update the reference snapshot, pass `--update`.
It can be handy to generate the snapshot with a different `find` implementation to ensure the output is correct, for example:

    $ ./tests/tests.sh posix/basic --bfs=find --update

But keep in mind, other `find` implementations may not be correct.
To my knowledge, no other implementation passes even the POSIX-compatible subset of the tests:

    $ ./tests/tests.sh --bfs=find --posix
    ...
    tests passed: 90
    tests skipped: 3
    tests failed: 6

Run

    $ ./tests/tests.sh --help

for more details.

### Validation

A more thorough testsuite is run by the [CI](https://github.com/tavianator/bfs/actions) and to validate releases.
It builds `bfs` in multiple configurations to test for latent bugs, memory leaks, 32-bit compatibility, etc.
You can run it yourself with

    $ make distcheck

Some of these tests require `sudo`, and will prompt for your password if necessary.