# Compilation database

If you are working with a project which is not based on [CMake](quick-cmake-tutorial.html), [Gradle](gradle-support.html), or [Makefiles](makefiles-support.html), you can still benefit from the advanced IDE features that CLion provides. One way is to [import](creating-new-project-from-scratch.html#import-prj) a non-CMake project and let CLion convert it into a simple CMake structure. Another option is to open a project by loading its compilation database.

A compilation database lets CLion detect project files and extract all the necessary compiler information, such as include paths and compilation flags. This approach enables you to operate in the IDE and get the full experience of its capabilities while keeping your project independent from CMake, Makefile, or Gradle.

A [compilation database](https://clang.llvm.org/docs/JSONCompilationDatabase.html) is a [JSON](https://www.json.org/)-formatted file named `compile_commands.json` that contains structured data about every compilation unit in your project.

The following snippet shows an example of a JSON compilation database:

```JSON
{
"directory": "/Users/me/prj/Calendar/",
"command": "/usr/local/bin/g++-7 -I/Users/me/prj/Calendar/calendars -g -std=c++11 -o calendar_run.dir/main.cpp.o -c /Users/me/prj/Calendar/main.cpp",
"file": "/Users/me/prj/Calendar/main.cpp"
},
{
"directory": "/Users/me/prj/Calendar/calendars",
"command": "/usr/local/bin/g++-7 -I/Users/me/prj/Calendar/calendars -g -std=c++11 -o calendars.dir/calendar_defs.cpp.o -c /Users/me/prj/Calendar/calendars/calendar_defs.cpp",
"file": "/Users/me/prj/Calendar/calendars/calendar_defs.cpp"
}
```

You can see an array of entries called command objects. Each command object represents the translation unit’s main file, the working directory, the actual compile command (or the list of arguments), and optionally the name of the output created by the compilation step. For more information about the format, refer to the [official documentation](http://clang.llvm.org/docs/JSONCompilationDatabase.html#format).

## Generating a compilation database

To get a compilation database for your project, you have a wide variety of options: it can be generated by compilers, build systems, and specialized tools (see the [expanded list of variants](https://sarcasm.github.io/notes/dev/compilation-database.html)). Some examples are given below:

Procedure: CMake:

* Use the [CMAKE_EXPORT_COMPILE_COMMANDS](https://cmake.org/cmake/help/v3.11/variable/CMAKE_EXPORT_COMPILE_COMMANDS.html) flag. You can run

```CONSOLE
cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=ON .
```

or add the following line to your [CMakeLists.txt](cmakelists-txt-file.html) script:

```CONSOLE
set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
```

The `compile_commands.json` file will be put into the build directory.

> **Note:**
> `CMAKE_EXPORT_COMPILE_COMMANDS` is implemented only by Makefile and Ninja [generators](https://cmake.org/cmake/help/latest/manual/cmake-generators.7.html#makefile-generators). For other generators, this option is ignored.

Procedure: Clang (version 5.0 and later):

* The [-Mj](http://bcain-llvm.readthedocs.io/projects/clang/en/latest/ClangCommandLineReference/#cmdoption-clang-mj-arg) option writes a compilation entry per input file. You can use it for each file in the project, and then merge the outputs into a JSON-formatted compilation database (refer to the [procedure example](https://github.com/Sarcasm/notes/blob/master/dev/compilation-database.rst#clang)).

Procedure: Ninja (version 1.2 and later):

* To get a compilation database, use the [-t compdb](https://ninja-build.org/manual.html#_extra_tools) option. Note that it requires rule names as arguments: `-t compdb rule1 rule2...` The list of rules is provided in the Ninja build file (default name [build.ninja](https://ninja-build.org/manual.html)), for example:

```CONSOLE
rule cc
    command = gcc -c -o $out $in
    description = CC $out

rule link
    command = gcc -o $out $in
    description = LINK $out
```

To generate a compilation database in case of only one rule named `cc`, specify:

```CONSOLE
-t compdb cc > compile_commands.json
```

But for multiple rules, you need to get their exact names from the build file and pass them to `compdb` (refer to [one of the possible solutions](https://sarcasm.github.io/notes/dev/compilation-database.html#ninja)).

Procedure: Make-based projects:

* The [compiledb-generator](https://github.com/nickdiego/compiledb-generator) tool creates compilation databases for make-based build systems.

Procedure: Bear and intercept-build tools:

* [Bear](https://github.com/rizsotto/Bear) and intercept-build from [scan-build](https://github.com/rizsotto/scan-build) are the tools to help you get a compilation database by intercepting compiler calls during the build.

Procedure: SourceTrail Visual Studio extension:

* [SourceTrail Extension](https://marketplace.visualstudio.com/items?itemName=vs-publisher-1208751.SourcetrailExtension) generates a compilation database for [Visual Studio solutions](https://learn.microsoft.com/en-us/visualstudio/ide/solutions-and-projects-in-visual-studio).

## Working with compilation database in CLion

Once you have created a compilation database for your project, you can start working with it in CLion.

Procedure: Load a project

1. Select `File | Open` from the main menu.

2. Locate the `compile_commands.json` file or the directory that contains it, then click Open.

3. Click Open as Project:

![Opening a compilation database project](https://resources.jetbrains.com/help/img/idea/2026.2/cl_compdb_openasproject.png)

4. CLion will detect the project files and show the status of all commands in `compile_commands.json` in the Build tool window:

![Compilation database project](https://resources.jetbrains.com/help/img/idea/2026.2/cl_compdb_overview.png)

At this point, CLion's code insight, refactoring, analysis, and navigation are fully available for your project.

> **Tip:**
> Your project files can be located outside the directory that contains `compile_commands.json`. CLion extracts actual paths from the compilation database and gathers the project files regardless of their location.

> **Note:**
> When working with a compilation database project under VCS, consider not to share the `.iml` file, since it will be regenerated on import. For more information, refer to [this instruction](https://intellij-support.jetbrains.com/hc/en-us/articles/206544839-How-to-manage-projects-under-Version-Control-Systems).

Procedure: Check the toolchain

1. Go to `Settings | Build, Execution, Deployment | Compilation Database`

2. Select the toolchain to be used for resolving the project files:

![Toolchain for compilation database](https://resources.jetbrains.com/help/img/idea/2026.2/cl_compdb_wsl_toolchain.png)

CLion suggests all the available toolchains from `Settings | Build, Execution, Deployment | Toolchain`. Note that Remote Host toolchains are not currently supported for compilation database projects.

> **Note:**
> Keep in mind that changing the toolchain requires that you regenerate the `compile_commands.json` file using the new toolchain.

Procedure: Change project root

By default, the project root is set to the directory containing the compilation database file. However, this is not always convenient: for example, if some project files are located outside the directory that contains `compile_commands.json` (which means outside the project root), such files are listed in the tree regardless the actual folder structure. In this case, you need to set the project root to the parent directory containing both `compile_commands.json` and the project files.

1. To change the project root, select `Tools | Compilation Database | Change Project Root` from the main menu, and set the new location for the project root.

Procedure: Configure auto-reload

By default, CLion doesn't reload your project automatically on changes in `compile_commands.json` except for the cases of external events like VCS update. You can change this behavior in the Build Tools settings.

1. Go to `Settings | Build, Execution, Deployment | Build Tools`.

2. Select one of the auto-reload options:

![Auto-reload settings](https://resources.jetbrains.com/help/img/idea/2026.2/cl_autoreload_settings.png)

* Any changes - project reload will be triggered on any change in `compile_commands.json`.

* External changes (default) - your project will be reloaded only upon external events like VCS update. In case of other changes in `compile_commands.json`, you need to reload your project manually. Use one of the following options: * Press `Ctrl+Shift+O` (Windows), `⌘ ⇧ I` (macOS), `⌘ ⇧ O` (IntelliJ IDEA Classic (macOS)), `⌘ ⇧ I` (macOS System Shortcuts), `Ctrl+Shift+O` (XWin), `Ctrl+Shift+O` (GNOME), `Ctrl+Shift+O` (KDE), `Ctrl+Shift+O` (Emacs), `Ctrl+Shift+O` (Sublime Text), `⌘ ⇧ I` (Sublime Text (macOS)), `⌘ ⇧ I` (Xcode), `Ctrl+Shift+O` (Visual Studio), `⌘ ⇧ I` (Visual Studio (macOS)), `Ctrl+Shift+O` (ReSharper), `⌘ ⇧ I` (ReSharper (macOS)), `Ctrl+Shift+O` (QtCreator), `Ctrl+Shift+O` (QtCreator (macOS)), `Ctrl+Shift+O` (NetBeans), `Ctrl+Shift+O` (Eclipse), `Ctrl+Shift+O` (Eclipse (macOS)) * Click the popup that appears in the editor: ![Editor popup for reloading the project](https://resources.jetbrains.com/help/img/idea/2026.2/cl_compdb_reload_popup.png) * Click ![Reimport Compilation Database Project](https://resources.jetbrains.com/help/img/idea/2026.2/app.actions.refresh.svg) in the Build tool window: ![The Reimport project icon](https://resources.jetbrains.com/help/img/idea/2026.2/cl_compdb_reimport_syncwindow.png) * Select `Tools | Compilation Database | Reload Compilation Database Project` from the main menu.

> **Tip:**
> This setting works per-project. Auto-reload options should be configured for each of your compilation database, [Makefile](makefiles-support.html), or [Gradle](gradle-support.html) projects separately.

### Coding assistance in compile_database.json

CLion natively supports the [JSON](clion-features-in-different-languages.html) file format, so you can edit the `compile_database.json` file right in the IDE, with highlighting and code completion for help:

![Code completion in compile_database.json](https://resources.jetbrains.com/help/img/idea/2026.2/cl_compdb_jsoncompletion.png)

CLion checks the compliance of your `compile_database.json` file with the compilation database JSON schema. You can adjust the corresponding inspections in `Settings | Editor | Inspections | JSON and JSON5`:

![JSON inspections for compile_database.json](https://resources.jetbrains.com/help/img/idea/2026.2/cl_compdb_jsoninspections.png)

### Compile a single file

Although the build functionality for compilation database projects is not yet implemented in CLion, you may find it useful to check the changes in a single file without building the whole project. For this purpose, CLion provides the [Recompile](compiling-single-file.html) action. It is available for individual source and header files, and also for groups of files selected in the project tree. For headers,  CLion uses resolve context to compile one of the source files that include the specified header. Note that Recompile is disabled for directories and non-C/C++ files.

* To call Recompile for the currently opened file, select `Build | Recompile` from the main menu or press `Ctrl+Shift+F9` (Windows), `⌘ ⇧ F9` (macOS), `⌘ ⇧ F9` (IntelliJ IDEA Classic (macOS)), `⌘ ⇧ F9` (macOS System Shortcuts), `Ctrl+Shift+F9` (XWin), `Ctrl+Shift+F9` (GNOME), `Ctrl+Shift+F9` (KDE), `Ctrl+Shift+F9` (Emacs), `Ctrl+B` (Sublime Text), `⌘ B` (Sublime Text (macOS)), `⌘ ⇧ F9` (Xcode), `Ctrl+F7` (Visual Studio), `⌘ F7` (Visual Studio (macOS)), `Ctrl+F7` (ReSharper), `⌘ F7` (ReSharper (macOS)), `Ctrl+Alt+B` (QtCreator), `⌘ ⌥ B` (QtCreator (macOS)), `F9` (NetBeans), `Ctrl+Shift+F9` (Eclipse), `⌘ ⇧ F9` (Eclipse (macOS)).

* For a file in the project tree, use the Recompile option in the context menu (or press the same `Ctrl+Shift+F9` (Windows), `⌘ ⇧ F9` (macOS), `⌘ ⇧ F9` (IntelliJ IDEA Classic (macOS)), `⌘ ⇧ F9` (macOS System Shortcuts), `Ctrl+Shift+F9` (XWin), `Ctrl+Shift+F9` (GNOME), `Ctrl+Shift+F9` (KDE), `Ctrl+Shift+F9` (Emacs), `Ctrl+B` (Sublime Text), `⌘ B` (Sublime Text (macOS)), `⌘ ⇧ F9` (Xcode), `Ctrl+F7` (Visual Studio), `⌘ F7` (Visual Studio (macOS)), `Ctrl+F7` (ReSharper), `⌘ F7` (ReSharper (macOS)), `Ctrl+Alt+B` (QtCreator), `⌘ ⌥ B` (QtCreator (macOS)), `F9` (NetBeans), `Ctrl+Shift+F9` (Eclipse), `⌘ ⇧ F9` (Eclipse (macOS)) keys).

* To recompile several files, select them in the project tree, and use the Recompile selected files option from the context menu `Ctrl+Shift+F9` (Windows), `⌘ ⇧ F9` (macOS), `⌘ ⇧ F9` (IntelliJ IDEA Classic (macOS)), `⌘ ⇧ F9` (macOS System Shortcuts), `Ctrl+Shift+F9` (XWin), `Ctrl+Shift+F9` (GNOME), `Ctrl+Shift+F9` (KDE), `Ctrl+Shift+F9` (Emacs), `Ctrl+B` (Sublime Text), `⌘ B` (Sublime Text (macOS)), `⌘ ⇧ F9` (Xcode), `Ctrl+F7` (Visual Studio), `⌘ F7` (Visual Studio (macOS)), `Ctrl+F7` (ReSharper), `⌘ F7` (ReSharper (macOS)), `Ctrl+Alt+B` (QtCreator), `⌘ ⌥ B` (QtCreator (macOS)), `F9` (NetBeans), `Ctrl+Shift+F9` (Eclipse), `⌘ ⇧ F9` (Eclipse (macOS)). Note that when used for multiple files, the recompilation stops upon the first compilation failure.

When you Recompile a file, CLion extracts necessary information from the corresponding command object in `compile_commands.json`: the compilation command line (yet CLion suppresses the output and removes the flags that specify output files), and the compiler to be used.

### Mark a directory as..

The Mark Directory As action is also available for your compilation database projects. Select a directory in the Project tree, right-click it, and choose the Mark Directory As action.

For use case descriptions and more details on how CLion treats marked directories, refer to the section [External source files](controlling-source-library-and-exclude-directories.html).

### Build and run

Compilation database itself lacks the data required for building, running and debugging an application. However, you can set up the workflow by adding [custom build targets](custom-build-targets.html) for your compilation database project and creating [custom Run/Debug configurations](custom-build-targets.html#custom-rundebug) for these targets.

## See also

### External Links

[Working with Makefiles in CLion using Compilation DB and File Watchers](https://blog.jetbrains.com/clion/2018/08/working-with-makefiles-in-clion-using-compilation-db/)