diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/BUILDING.md (renamed from docs/CONTRIBUTING.md) | 55 | ||||
| -rw-r--r-- | docs/HACKING.md | 47 |
2 files changed, 55 insertions, 47 deletions
diff --git a/docs/CONTRIBUTING.md b/docs/BUILDING.md index 77e8e2c..f61c11e 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/BUILDING.md @@ -1,15 +1,8 @@ -Contributing -============ +Building `bfs` +============== -License -------- - -`bfs` is licensed under the [Zero-Clause BSD License](https://opensource.org/licenses/0BSD), a maximally permissive license. -Contributions must use the same license. - - -Building --------- +Compiling +--------- `bfs` uses [GNU Make](https://www.gnu.org/software/make/) as its build system. A simple invocation of @@ -69,9 +62,11 @@ Here are some of the common ones; check the [`Makefile`](/Makefile) for more. | `PREFIX` | The installation prefix (default: `/usr`) | | `MANDIR` | The man page installation directory | +### + ### Dependency tracking -The build system automatically tracks header dependencies with the `-M` family of compiler options (see `DEPFLAGS` in the `Makefile`). +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 go one step further than most build systems by tracking the flags that were used for the previous compilation. @@ -90,7 +85,7 @@ To test a different configuration, you'll have to repeat it (e.g. `make release Testing ------- -`bfs` comes with an extensive testsuite which can be run with +`bfs` comes with an extensive test suite which can be run with $ make check @@ -131,37 +126,3 @@ You can run it yourself with $ make distcheck Some of these tests require `sudo`, and will prompt for your password if necessary. - - -Hacking -------- - -`bfs` is written in [C](https://en.wikipedia.org/wiki/C_(programming_language)), specifically [C11](https://en.wikipedia.org/wiki/C11_(C_standard_revision)). -You can get a feel for the coding style by skimming the source code. -[`main.c`](/src/main.c) contains an overview of the rest of source files. -A quick summary: - -- Tabs for indentation, spaces for alignment. -- Most types and functions should be namespaced with `bfs_`. - Exceptions are made for things that could be generally useful outside of `bfs`. -- Error handling follows the C standard library conventions: return a nonzero `int` or a `NULL` pointer, with the error code in `errno`. - All failure cases should be handled, including `malloc()` failures. -- `goto` is not harmful for cleaning up in error paths. - -### Adding tests - -Both new features and bug fixes should have associated tests. -To add a test, create a new function in `tests.sh` called `test_<something>`. -Snapshot tests use the `bfs_diff` function to automatically compare the generated and expected outputs. -For example, - -```bash -function test_something() { - bfs_diff basic -name something -} -``` - -`basic` is one of the directory trees generated for test cases; others include `links`, `loops`, `deep`, and `rainbow`. - -Run `./tests.sh test_something --update` to generate the reference snapshot (and don't forget to `git add` it). -Finally, add the test case to one of the arrays `posix_tests`, `bsd_tests`, `gnu_tests`, or `bfs_tests` depending on which `find` implementations it should be compatible with. diff --git a/docs/HACKING.md b/docs/HACKING.md new file mode 100644 index 0000000..7dfc497 --- /dev/null +++ b/docs/HACKING.md @@ -0,0 +1,47 @@ +Hacking on `bfs` +================ + +License +------- + +`bfs` is licensed under the [Zero-Clause BSD License](https://opensource.org/licenses/0BSD), a maximally permissive license. +Contributions must use the same license. + + +Implementation +-------------- + +`bfs` is written in [C](https://en.wikipedia.org/wiki/C_(programming_language)), specifically [C11](https://en.wikipedia.org/wiki/C11_(C_standard_revision)). +You can get a feel for the coding style by skimming the source code. +[`main.c`](/src/main.c) contains an overview of the rest of source files. +A quick summary: + +- Tabs for indentation, spaces for alignment. +- Most types and functions should be namespaced with `bfs_`. + Exceptions are made for things that could be generally useful outside of `bfs`. +- Error handling follows the C standard library conventions: return a nonzero `int` or a `NULL` pointer, with the error code in `errno`. + All failure cases should be handled, including `malloc()` failures. +- `goto` is not considered harmful for cleaning up in error paths. + + +Tests +----- + +`bfs` includes an extensive test suite. +See the [build documentation](BUILDING.md#testing) for details on running the tests. + +Both new features and bug fixes should have associated tests. +To add a test, create a new function in `tests.sh` called `test_<something>`. +Snapshot tests use the `bfs_diff` function to automatically compare the generated and expected outputs. +For example, + +```bash +function test_something() { + bfs_diff basic -name something +} +``` + +`basic` is one of the directory trees generated for test cases; others include `links`, `loops`, `deep`, and `rainbow`. + +Run `./tests.sh test_something --update` to generate the reference snapshot (and don't forget to `git add` it). +Finally, add the test case to one of the arrays `posix_tests`, `bsd_tests`, `gnu_tests`, or `bfs_tests`, depending on which `find` implementations it should be compatible with. |