# Blues compilation database format
> Note: as this project is still early in development, everything mentioned here is still subject to change.
To correctly identify source files belonging to a project, Blues currently requires a `blues_compdb.json` file to be present in a project. The format is heavily inspired by [Clang's JSON compilation database format](https://clang.llvm.org/docs/JSONCompilationDatabase.html).
An example `blues_compdb.json`:
```json
[
{
"directory": "./build_scripts",
"command": "bsc -u -sim -bdir build_dir -D VPP_DEF=VALUE -p ../src:+ ../src/Top.bsv",
"file": "./src/Top.bsv"
}
]
```
Following format used by Clang, the file contains JSON array, where each element represents a single `bsc` invocation.
JSON fields for each element:
- `directory` - The working directory (PWD) under which the compiler is called. Can be absolute or relative to project root. Paths specified in other fields are relative to this directory.
- `command` - A single string representing the full `bsc` command line.
- `arguments` - Alternative to `command`, full `bsc` command line represented as a pre-tokenized array of strings.
- `file` - Optional. Currently only used as an alternative to the positional source file argument in `command` or `arguments`.
For most projects, consisting of a single `bsc -u` invocation, this minimal example can be used as a template:
```json
[
{
"directory": ".",
"command": "bsc -u <BSC ARGS>"
}
]
```
The default location for `blues_compdb.json` is `<PROJECT_ROOT>/blues_compdb.json`. This can be overridden with a separate `<PROJECT_ROOT>/blues.toml` configuration file:
```toml
compdb_path = "build_dir/blues_compdb.json"
```
As a final example, [The Tooba Blues demo](https://gitlab.com/runtimetantrum/blues-demo-tooba) is a fork [Tooba](https://github.com/bluespec/Toooba), preconfigured to work with Blues.