CLion 2018.2 Help

Compilation Database

Compilation database as a project format

With non-CMake and non-Gradle projects, you can still benefit from the advanced IDE features that CLion provides. One way is to import 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 or Gradle.

A compilation database is a JSON-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:

{ "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 details on the format, see the official documentation.

How to generate 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). Some examples are given below:

CMake:

  • Use the CMAKE_EXPORT_COMPILE_COMMANDS flag. You can run
    cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=ON…
    or add the following line to your CMakeLists.txt script:
    set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
    The compile_commands.json file will be put into the build directory.

Clang (version 5.0 and later):

  • The -Mj 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 (see the procedure example).

Ninja (version 1.2 and later):

  • To get a compilation database, use the -t compdb 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), for example:
    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:
    -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 (see one of the possible solutions).

Make-based projects:

Bear and intercept-build tools:

  • Bear and intercept-build from scan-build are the tools to help you get a compilation database by intercepting compiler calls during the build.

SourceTrail Visual Studio extension:

Working with compilation database in CLion

Load a compilation database

Once you have created a compilation database for your project, you can load it in CLion. Navigate to File | Open on the main menu, choose the compile_commands.json file or a directory that contains it, and click Open as Project.

As a result, the project files are detected and the status of all commands in compile_commands.json is shown in the icons toolwindows toolWindowBuild svg Build tool window:

Compilation database project

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

Change the 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 of the directory with compile_commands.json (i.e., out of 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.

To change the project root, select Tools | Compilation Database | Change Project Root from the main menu, and provide a different location for the project root.

Auto-import and reload a compilation database project

To have your project automatically reloaded for every change in compile_command.json, set the Use auto-import checkbox in Settings / Preferences | Build, Execution, Deployment | Compilation Database. If the checkbox is cleared, a pop-up message prompting to import changes will be shown upon any modification of the compilation database file:

cl compdb importpopup

You can also use the Reload Compilation Database Project action from the Tools | Compilation Database menu to refresh the project manually when needed.

Note that CLion natively supports JSON file format, so you can edit the compile_database.json file right in the IDE, with highlighting and code completion for help.

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 action. It is available for individual source and header files (for the latter, 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, choose Run | Recompile from the main menu (or press Ctrl+Shift+F9). For a file in the project tree, use the Recompile option from the right-click menu (or press the same Ctrl+Shift+F9 keys).

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 Tool Window, 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 Mark directory as....

Current limitations and future plans

Compilation database lacks the data required for building, running and debugging an application. However, the IDE itself could wrap this functionality over a compilation database project, and that is in the plans for implementation in CLion.

Last modified: 18 September 2018

See Also