Intel® DPC++ Compatibility Tool Developer Guide and Reference
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
Visible to Intel only — GUID: GUID-952AA2F0-6239-4EE9-BFB5-2B9FD363A58E
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 makeThe 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 buildRun 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 ../
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>&1Use 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-barUse 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.