libvieter/README.md

# libvieter

This library powers part of Vieter, most notably the sections that can easily
be implemented in C (or just parts I want to implement in C because it's fun).

The goal of this library is to be as self-contained as possible; data
structures should be implemented manually if possible.

See the [source code](src) for the list of modules.

## Development

### Compilation

Everything is handled by the provided Makefile. To compile the static library,
simply run `make`.

### Required libraries

Libvieter requires libarchive.

### Project structure

Each module has its own subdirectory inside `src`, e.g. `src/cron`. This
directory contains the actual implementation of a module, along with any
internally used header files. Each internal function should be defined in a
header file, as to make testing these possible.

Each module should also have its own header file inside the `include`
directory. This header file defines the public API that the library exposes for
this specific module.

Any code in a module may only import internal headers from that module, along
with any of the public API header files. Modules should not depend on each
other's internal implementationns.

Each module should contain a README describing its contents.

All file names, function names... (even internals) should follow snake case
convention and have a prefix unique to that module, starting with `vieter_`.
For example, the `cron` modules uses the `vieter_cron_` prefix for everything.

Header files should only import what they explicitely need. If some function is
only used in a .c file, the import should be placed in the .c file instead.

### Testing

This library uses [Acutest](https://github.com/mity/acutest) for its tests.
Tests should be placed in the `test` subdirectory, further divided into
directories that correspond to those in `src`. Test files should begin with
`test_`, and their format should follow the expected format for Acutest.

Each `test_` is compiled separately into a binary, linked with libvieter. A
test file can import any of the public API header files, along with any header
files defined in its respective module. This allows testing internal functions.

To run the tests, simply run `make test`. If you wish to only run a specific
test binary, you can find them in `build/test`.

The name of tests in the `TEST_LIST` variable should be prefixed with the
module they're testing. This makes it much easier to distinguish the output of
tests in the CLI. For example:

```c
TEST_LIST = {
    {"cron illegal parts", test_illegal_parts},
    {NULL, NULL}
};
```

### `compile_commands.json`

Clangd requires a `compile_commands.json` to function properly. You can
generate it using [bear](https://github.com/rizsotto/Bear):

```sh
make clean
bear -- make
bear --append -- make build-test
```

This will create a `compile_commands.json` file in the current directory.