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 SYCLomatic to guide the code project migration.

For example:

 1[
 2  {
 3    "directory": "/path/to/project",
 4    "command": "/usr/bin/clang++ ...  -Iinclude_path -D_FOO_=VALUE -c ./foo/foo.cpp",
 5    "file": "./foo/foo.cpp"
 6  },
 7  ...
 8  {
 9    "directory": "/path/to/project",
10    "command": "/usr/bin/clang++ ... -Iinclude_path -D_BAR_=VALUE -c ./foo/bar.cpp",
11    "file": "./foo/bar.cpp"
12  }
13]

A compilation database can be generated by running the intercept-build script, which is provided as part of SYCLomatic. 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.

  1. Change to the folder-options-dpct sample directory.

  2. 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:

  1. Use intercept-build

  2. 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:

  1. Install the required software dependencies for the project.

  2. In a command window, go to the project folder.

  3. In the project folder create and navigate to a new build directory:

    mkdir build && cd build

  4. Run CMake to generate a Makefile:

    cmake ../

  5. 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:

  1. 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

  2. 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.

  1. Change to the folder-options-dpct sample directory.

  2. 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

  3. 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.