compiledb for GNU Make compilation databases

compiledb targets make-based C and C++ analysis

compiledb addresses a specific gap between GNU Make projects and Clang tooling. Editors and language servers can use Clang's JSON Compilation Database to discover each translation unit, its working directory, compiler flags, and source files. Projects built with CMake normally receive `compile_commands.json` from CMake itself, but many large GNU Make codebases do not. The README identifies non-CMake large codebases as the main audience.

The project originated from a need to index AOSP modules for navigation and source study. Its intended consumers include `cquery`, `ccls`, and related editor integrations such as Neovim, Vim, ALE, and LanguageClient-neovim. compiledb does not replace the compiler or language server. It produces the database that lets those tools request accurate command information.

Its central design choice is to use GNU Make's prediction behavior rather than depend on an ordinary build. The README says that compiledb generally does not need a clean build, unlike Bear and YCM-Generator. That makes the project relevant to incremental build trees where a clean build would be expensive or would invalidate useful outputs.

compiledb converts GNU Make recipes into JSON entries

The normal path uses compiledb as a Make wrapper. The `compiledb make` command invokes GNU Make, observes the recipe commands produced during a dry run, extracts compiler invocations, writes a compilation database, and then performs the requested build unless no-build mode is selected. The README describes GNU Make options `-n` or `--dry-run` and `-k` or `--keep-going` as the basis for discovering commands without completing every build action.

This mechanism works only when the build log exposes enough information for the parser to identify compilation commands. compiledb is therefore sensitive to how a Makefile invokes its compiler. Recipes with shell conditionals, generated shell scripts, deferred variables, or heavily abbreviated commands may not map cleanly to the parser's expectations. The README describes the input as an ideal `make -Bnwk` build log, which makes dry-run logging central to the project's operation rather than merely a convenience.

The generated file uses Clang's `arguments` list format by default. For tools or workflows that require a single `command` string, compiledb offers `--command-style make`. That choice is an output-format decision rather than a different Make invocation strategy.

Installing compiledb and generating the first database

The README gives pip installation as the starting point. It states support for Python 3.3 and later. The package entry point is `compiledb`, and the project declares `click` and `bashlex` as runtime dependencies. After installation, the first basic use is to run compiledb through its Make wrapper:

$ compiledb make

This asks compiledb to generate a `compile_commands.json` file and run the requested Make build. The reader should see Make execute the requested build while compiledb updates the database corresponding to that build. The README does not define the output filename as a configurable option, so `compile_commands.json` is the expected default artifact.

For a build with a selected Makefile and directory, pass GNU Make arguments after the `make` subcommand. compiledb forwards them to Make:

$ compiledb make -f core/main.mk -C build

If the goal is database generation without running the actual build, put `-n` or `--no-build` before `make`:

$ compiledb -n make

The README also mentions bash completion, but completion is optional. Its completion file is `sh-completion/compiledb.bash`, which can be added to `.bashrc` if shell completion is wanted.

Parsing an existing make log with compiledb

compiledb is not limited to its wrapper mode. Its base command can parse compile commands from a text file or standard input. This is useful when a build log already exists, when a build is performed in another environment, or when the output from GNU Make should be handled separately from the build invocation.

The documented file-based form is:

$ compiledb --parse build-log.txt

The equivalent input redirection form is:

$ compiledb < build-log.txt

For a direct pipeline, GNU Make can print a dry-run build log and compiledb can write the resulting database to standard output:

$ make -Bnwk | compiledb -o-

The `-o-` form writes the database to standard output rather than requiring the reader to rely on the default file. This makes compiledb composable with shell pipelines and lets the caller decide where the generated JSON should go. The README's wording is specific: the log should ideally have been generated with `make -Bnwk`. It does not claim that every possible build-log format is accepted.

compiledb versus CMake, Bear, and YCM-Generator

The clearest alternative for a CMake-based project is CMake itself. The README says that CMake already generates a compilation database, so replacing that output with compiledb would add a parsing layer without solving a missing-generation problem. compiledb is designed for make-based systems and has no documented CMake mode.

Bear and YCM-Generator are the more relevant comparisons because they address similar editor tooling needs. According to the README, compiledb is intended to be faster for large projects because it generally avoids a clean build. Its use of Make dry-run options means it can inspect what the build would do while leaving compiled objects and other build artifacts alone. The README also characterizes compiledb as more cross-compilation friendly than YCM-Generator's fake-toolchain approach.

That comparison does not make compiledb suitable for every Make project. A build that conceals compiler commands, relies on interactive behavior, or does not produce analyzable Make output can still require a different strategy. The exact differences in supported command shapes are not documented, so compatibility with a particular Makefile must be checked rather than inferred from the project category.

Platform boundaries and maintenance cost in compiledb

The README lists Windows 10 with cmd, WSL on Ubuntu, and mingw32 under Windows, Arch Linux and Ubuntu 18 under Linux, and macOS 10.13 and 10.14 under Mac. These are the platforms named by the project documentation, not a claim about every current operating system or distribution. GNU Make behavior, shell differences, and path handling can still vary outside those combinations.

The repository is not archived. Its last push was on 2026-08-14, so the repository metadata does not indicate an abandoned project. The recent release list includes versions 0.10.5, 0.10.6, and 0.10.7, all dated 2025-03-23. The presence of a recent push and older listed releases does not establish a new release schedule, so upgrade planning should check the repository and package index rather than assume frequent releases.

The project uses `setuptools-scm` to derive its version dynamically from Git references. Development dependencies include `pytest`, `coverage`, `pytest-cov`, `pycodestyle`, `flake8`, and `tox`. The documented installation is short, but adopting compiledb in a large build environment still requires checking the Python version, GNU Make output, and editor integration. Its GPL-3.0-or-later license is relevant to distribution and integration decisions, although this article does not provide legal advice.

Editorial conclusion

Developers working with GNU Make, Clang-oriented editors, or language servers should consider compiledb when their build prints complete compiler commands and they want database generation without requiring a clean build. Projects using CMake should normally keep CMake's generator because the README states that CMake already produces a compilation database. Before adoption, verify that your Makefiles expose the required compiler invocations under the selected flags, especially when recipes use shell logic, generated commands, or toolchain configuration that GNU Make does not print as expected.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-3.0
3. nickdiego/compiledb on GitHub
4. README
5. Releases