diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/BUILDING.md | 200 | ||||
| -rw-r--r-- | docs/CHANGELOG.md | 62 | ||||
| -rw-r--r-- | docs/RELATED.md | 5 | ||||
| -rw-r--r-- | docs/bfs.1 | 6 |
4 files changed, 192 insertions, 81 deletions
diff --git a/docs/BUILDING.md b/docs/BUILDING.md index db5d721..025dadf 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-*] [--with-*|--without-*] [CC=...] [...] + $ 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: + +<pre> +<b>MAKE</b>=<i>make</i> + <a href="https://en.wikipedia.org/wiki/Make_(software)">make</a> implementation +<b>CC</b>=<i>cc</i> + C compiler +<b>INSTALL</b>=<i>install</i> + Copy files during <i>make install</i> +<b>MKDIR</b>="<i>mkdir -p</i>" + Create directories +<b>PKG_CONFIG</b>=<i>pkg-config</i> + Detect external libraries and required build flags +<b>RM</b>="<i>rm -f</i>" + Delete files +</pre> + +These flags will be used by the build process: + +<pre> +<b>CPPFLAGS</b>="<i>-I... -D...</i>" +<b>CFLAGS</b>="<i>-W... -f...</i>" +<b>LDFLAGS</b>="<i>-L... -Wl,...</i>" + Preprocessor/compiler/linker flags + +<b>LDLIBS</b>="<i>-l... -l...</i>" + Dynamic libraries to link + +<b>EXTRA_</b>{<b>CPPFLAGS</b>,<b>CFLAGS</b>,<b>LDFLAGS</b>,<b>LDLIBS</b>}="<i>...</i>" + Adds to the default flags, instead of replacing them +</pre> ### 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`<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` | -| `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 +<pre> +--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-<a href="https://github.com/google/sanitizers/wiki/AddressSanitizer">asan</a> +--enable-<a href="https://github.com/google/sanitizers/wiki/AddressSanitizerLeakSanitizer#stand-alone-mode">lsan</a> +--enable-<a href="https://github.com/google/sanitizers/wiki/MemorySanitizer">msan</a> +--enable-<a href="https://github.com/google/sanitizers/wiki/ThreadSanitizerCppManual">tsan</a> +--enable-<a href="https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html">ubsan</a> + 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-<a href="https://gcc.gnu.org/onlinedocs/gcc/gcov/introduction-to-gcov.html">gcov</a> + Enable code coverage instrumentation +</pre> -[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 build `--with` or `--without` them explicitly: -We also add a dependency on the current configuration, so you can change configurations and rebuild without having to `make clean`. -For example, +<pre> +--with-<a href="https://savannah.nongnu.org/projects/acl">libacl</a> --without-libacl +--with-<a href="https://sites.google.com/site/fullycapable/">libcap</a> --without-libcap +--with-<a href="https://github.com/SELinuxProject/selinux">libselinux</a> --without-libselinux +--with-<a href="https://github.com/axboe/liburing">liburing</a> --without-liburing +--with-<a href="https://github.com/kkos/oniguruma">oniguruma</a> --without-oniguruma +</pre> - $ ./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: + +<pre> +make + The default target; builds just the <i>bfs</i> binary +make <b>all</b> + Builds everything, including the tests (but doesn't run them) + +make <b>check</b> + Builds everything, and runs all tests +make <b>unit-tests</b> + Builds and runs the unit tests +make <b>integration-tests</b> + Builds and runs the integration tests +make <b>distcheck</b> + Builds and runs the tests in multiple different configurations + +make <b>install</b> + Installs bfs globally +make <b>uninstall</b> + Uninstalls bfs + +make <b>clean</b> + Deletes all built files +make <b>distclean</b> + Also deletes files generated by ./configure +</pre> + + +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 ------- diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index 672c2b4..1d4bdcf 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -1,6 +1,68 @@ 3.* === +3.3 +--- + +**May 28, 2024** + +### New features + +- The `-status` bar can now be toggled by `SIGINFO` (<kbd>Ctrl</kbd>+<kbd>T</kbd>) on systems that support it, and `SIGUSR1` on other systems + +- `-regextype` now supports all regex types from GNU find ([#21](https://github.com/tavianator/bfs/issues/21)) + +- File birth times are now supported on OpenBSD + +### Changes + +- Symbolic link loops are now treated like other broken links, rather than an error + +- `./configure` now expects `--with-libacl`, `--without-libcap`, etc. rather than `--enable-`/`--disable-` + +- The ` ` (space) flag is now restricted to numeric `-printf` specifiers + +### Bug fixes + +- `-regextype emacs` now supports [shy](https://www.gnu.org/software/emacs/manual/html_node/elisp/Regexp-Backslash.html#index-shy-groups) (non-capturing) groups + +- Fixed `-status` bar visual corruption when the terminal is resized + +- `bfs` now prints a reset escape sequence when terminated by a signal in the middle of colored output ([#138](https://github.com/tavianator/bfs/issues/138)) + +- `./configure CFLAGS=...` no longer overrides flags from `pkg-config` during configuration + + +3.2 +--- + +**May 2, 2024** + +### New features + +- New `-limit N` action that quits immediately after `N` results + +- Implemented `-context` (from GNU find) for matching SELinux contexts ([#27](https://github.com/tavianator/bfs/issues/27)) + +- Implemented `-printf %Z` for printing SELinux contexts + +### Changes + +- The build system has been rewritten, and there is now a configure step: + + $ ./configure + $ make + + See `./configure --help` or [docs/BUILDING.md](/docs/BUILDING.md) for more details. + +- Improved platform support + - Implemented `-acl` on Solaris/Illumos + - Implemented `-xattr` on DragonFly BSD + +### Bug fixes + +- Fixed some rarely-used code paths that clean up after allocation failures + 3.1.3 ----- diff --git a/docs/RELATED.md b/docs/RELATED.md index cf52b70..6e7bd38 100644 --- a/docs/RELATED.md +++ b/docs/RELATED.md @@ -25,8 +25,9 @@ These are not usually installed as the system `find`, but are designed to be `fi - [`bfs`](https://tavianator.com/projects/bfs.html) ([manual](https://man.archlinux.org/man/bfs.1), [source](https://github.com/tavianator/bfs)) - [schilytools](https://codeberg.org/schilytools/schilytools) `sfind` ([source](https://codeberg.org/schilytools/schilytools/src/branch/master/sfind)) - [BusyBox](https://busybox.net/) `find` ([manual](https://busybox.net/downloads/BusyBox.html#find), [source](https://git.busybox.net/busybox/tree/findutils/find.c)) -- [ToyBox](http://landley.net/toybox/) `find` ([manual](http://landley.net/toybox/help.html#find), [source](https://github.com/landley/toybox/blob/master/toys/posix/find.c)) -- uutils `find` ([source](https://github.com/uutils/findutils)) +- [ToyBox](https://landley.net/toybox/) `find` ([manual](http://landley.net/toybox/help.html#find), [source](https://github.com/landley/toybox/blob/master/toys/posix/find.c)) +- [Heirloom Project](https://heirloom.sourceforge.net/) `find` ([manual](https://heirloom.sourceforge.net/man/find.1.html), [source](https://github.com/eunuchs/heirloom-project/blob/master/heirloom/heirloom/find/find.c)) +- [uutils](https://uutils.github.io/) `find` ([source](https://github.com/uutils/findutils)) ## `find` alternatives @@ -479,6 +479,10 @@ Find files the current user can execute/read/write. Always false/true. .RE .TP +\fB\-flags\fR [\fI\-+\fR]\fIFLAGS\fR +Find files with matching inode +.BR FLAGS . +.TP \fB\-fstype \fITYPE\fR Find files on file systems with the given .IR TYPE . @@ -582,7 +586,7 @@ Find files whose entire path matches the .IR GLOB . .RE .TP -\fB\-perm\fR [\fI\-\fR]\fIMODE\fR +\fB\-perm\fR [\fI\-+/\fR]\fIMODE\fR Find files with a matching mode. .TP \fB\-regex \fIREGEX\fR |