Generate a Compilation Database

Intel® DPC++ Compatibility Tool Developer Guide and Reference

Download PDF

ID 768918

Date 3/22/2024

Version

Public

A newer version of this document is available. Customers should click here to go to the newest version.

Visible to Intel only — GUID: GUID-952AA2F0-6239-4EE9-BFB5-2B9FD363A58E

View Details

Generate a Compilation Database

A compilation database is a JSON file that contains an array of command objects, each of which usually contains three parts:

directory: The working directory of the compilation. All paths specified in the command or file fields must be either absolute or relative to this directory.
command: The compile command.
file: The translation unit’s main source file that is processed in the compilation step.

The compilation database lists detailed build options for each translation unit’s main source file, which can be consumed by Intel® DPC++ Compatibility Tool to guide the code project migration.

For example:

[
  {
    "directory": "/path/to/project",
    "command": "/usr/bin/clang++ ...  -Iinclude_path -D_FOO_=VALUE -c ./foo/foo.cpp",
    "file": "./foo/foo.cpp"
  },
  ...
  {
    "directory": "/path/to/project",
    "command": "/usr/bin/clang++ ... -Iinclude_path -D_BAR_=VALUE -c ./foo/bar.cpp",
    "file": "./foo/bar.cpp"
  }
]

A compilation database can be generated by running the intercept-build script, which is provided as part of Intel® DPC++ Compatibility Tool. intercept-build supports the capture of compilation command lines for files with the following extensions: .c, .C, .cc, .CC, .cp, .cpp, .cxx, .c++, .C++, .txx, and .cu.

Generate a Compilation Database for Makefile-Based Projects

The source code in Makefile-based projects can be compiled and linked into an executable binary or library by running build commands specified in the project Makefile.

For Makefile-based projects, you can generate the compilation database by running intercept-build make.

Use the folder-options-dpct sample to show the generation of compilation database.

Change to the folder-options-dpct sample directory.
Run the intercept-build tool to generate the compilation database:
```
intercept-build make
```
The compilation datebase compile_commands.json is created in the sample directory.

Generate a Compilation Database for CMake-Based Projects

CMake uses CMakeLists.txt files to describe project configuration, source files, and dependencies. When using CMake, make sure that all software that CMakeLists.txt files depend on has been installed, so that a functional Makefile can be generated by CMake.

There are two options to generate compilation database for CMake-based projects:

Use intercept-build
Use CMake option CMAKE_EXPORT_COMPILE_COMMANDS

Option One: Use intercept-build to Generate the Compilation Database

The following steps show how to generate the compilation database using intercept-build:

Install the required software dependencies for the project.
In a command window, go to the project folder.
In the project folder create and navigate to a new build directory:
```
mkdir build && cd build
```
Run CMake to generate a Makefile:
```
cmake ../
```
Run intercept-build to generate the compilation database:
```
intercept-build make
```

Option Two: Use CMake Option to Generate the Compilation Database

With CMake 3.5 version or higher, you can use the CMake option CMAKE_EXPORT_COMPILE_COMMANDS to generate the compilation database. For example, the following command generates the compilation database compile_commands.json in the build directory:

cmake  -DCMAKE_EXPORT_COMPILE_COMMANDS=ON ../

NOTE:

CMake 3.10 or higher is recommended as it provides better support for CUDA source code.

Generate a Compilation Database for Setuptools-Based Projects

Setuptools is a package development library in Python for facilitating packaging, distribution and installation of Python projects. For projects with setuptools as their build system, the steps to generate a compilation database are as follows:

Generate a build log for the setuptools project by using the -v or --verbose flag with the Python build command.
```
python3 setup.py <build-option> -v > build.log 2>&1
```
Use intercept-build –-parse-build-log option to generate the compilation database.
```
intercept-build -–parse-build-log build.log
```

Generate a Compilation Database with Other Build Systems

For projects using other build systems, intercept-build can be used to generate a compilation database from the build log of the project.

When generating a compilation database from the build log of a project, make sure to build your project using the appropriate build options to generate a verbose build log.

For example:

Build System	Option to Generate Verbose Build Log
Make	`VERBOSE=1`
CMake/Ninja	`-DCMAKE_VERBOSE_MAKEFILE=ON`
Bazel	`--subcommands`

You can use the folder-options-dpct sample to show the generation of the compilation database based on the build log.

Change to the folder-options-dpct sample directory.

Run make with options to collect a verbose build log:

make VERBOSE=1 -B > ./build_log.txt

  The content of ``build_log.txt`` should look like the following:

  .. code-block:: none
 :linenos:

 nvcc -c  -I./foo -I./foo/bar foo/main.cu -o foo/main.o
 nvcc -c  -I./foo -I./foo/bar foo/bar/util.cu -o foo/bar/util.o
 nvcc  ./foo/main.o ./foo/bar/util.o -o foo-bar

Use intercept-build to generate the compilation database with the --parse-build-log option to specify the build log to use:
```
intercept-build --parse-build-log=build_log.txt --work-directory=./
```
The compilation database compile_commands.json is generated in the current directory.

For more information about intercept-build, run intercept-build --help.

Select Your Language

Using Intel.com Search

Quick Links

Recent Searches

Advanced Search

Only search in

Intel® DPC++ Compatibility Tool Developer Guide and Reference

Generate a Compilation Database

Generate a Compilation Database for Makefile-Based Projects

Generate a Compilation Database for CMake-Based Projects

Generate a Compilation Database for Setuptools-Based Projects

Generate a Compilation Database with Other Build Systems