bootstrap/specs/clang/template/README.md

72 lines
2.5 KiB
Markdown
Raw Normal View History

2023-11-26 21:51:41 +00:00
# Clang Flake Template
This is a template for constructing a working environment for C/C++ development
with the [clang](https://clang.llvm.org/) (version 16.0.6) toolchain. [direnv](https://direnv.net/)
2023-11-26 21:54:42 +00:00
can be used to launch a dev shell upon entering this directory (refer to
`.envrc`). Otherwise run via:
2023-11-26 21:51:41 +00:00
```bash
$ nix develop
2023-11-26 21:51:41 +00:00
```
## Building
We use [CMake](https://cmake.org/) (version 3.27.7) to build the project. When
first starting the project, we recommend running the following commands:
```bash
$ mkdir -p build/{Debug,Release}
$ (cd build/Debug && cmake -DCMAKE_BUILD_TYPE=Debug ../..)
$ (cd build/Release && cmake -DCMAKE_BUILD_TYPE=Release ../..)
```
This will create a CMake cache file in each subdirectory with the build types
set. Now you can build a `Debug` or `Release` variant by navigating to the
corresponding subdirectory and running:
```bash
$ cmake --build .
```
2023-11-26 21:51:41 +00:00
## Language Server
The [clangd](https://clangd.llvm.org/) LSP (version 14.0.6) is included in this
flake. The [codelldb](https://github.com/vadimcn/codelldb) VSCode plugin is also
included to interface with the LSP. Note this plugin, despite its name, is
compatible with other editors (e.g. neovim). To configure, refer to your
editor's documentation.
To use the LSP across files, a
[compilation database](https://clang.llvm.org/docs/JSONCompilationDatabase.html)
must be generated. The `CMakeLists.txt` file already enables this in the Debug
configuration type. A top-level `compile_commands.json` symbolic link already
exists and points to this generated database.
2023-11-26 21:51:41 +00:00
## Documentation
Documentation is generated using [Doxygen](https://www.doxygen.nl/index.html)
2024-01-06 17:59:26 +00:00
(version 1.9.7) through CMake. (Re)generate documentation by navigating to
the desired build configuration directory and running:
2023-11-26 21:51:41 +00:00
```bash
2024-01-06 17:59:26 +00:00
$ cmake --build .
$ make docs
2023-11-26 21:51:41 +00:00
```
## Testing
We use [CTest](https://cmake.org/cmake/help/latest/module/CTest.html) (version
3.27.7) for unit testing. To run the tests, navigate to `build/Debug` and type
the following:
```bash
$ cmake --build .
$ make test
```
2023-11-26 21:51:41 +00:00
## Formatting
Formatting depends on the [clang-format](https://clang.llvm.org/docs/ClangFormat.html)
(version 14.0.6) tool. Refer to `.clang-format` for default formatting options.
A `pre-commit` hook is included in `.githooks` that can be used to format all
`*.c(pp)?` and `*.h(pp)?` files prior to commit. Install via:
2023-11-26 21:51:41 +00:00
```bash
$ git config --local core.hooksPath .githooks/
2023-11-26 21:51:41 +00:00
```
2023-11-26 21:54:42 +00:00
If running [direnv](https://direnv.net/), this hook is installed automatically
when entering the directory.