Developer Guide and Reference

  • 2021.1
  • 12/04/2020
  • Public Content

Command Line Options Reference

This topic shows the command line options and their descriptions.

Command Line Options Reference

Option
Description
--always-use-async-handler
Always create
cl::sycl::queue
with the async exception handler. Default:
off
.
--comments
Insert comments explaining the generated code. Default:
off
.
--cuda-include-path=<dir>
The directory path of the CUDA* header files.
--enable-ctad
Use a C++17 class template argument deduction (CTAD) in your generated code.
--extra-arg=<string>
Additional argument to append to the migration command line, example:
--extra-arg="-I /path/to/header"
. The options that can be passed this way can be found with the
dpct -- -help
command.
--format-range=<value>
Sets the range of formatting.
The values are:
  • =migrated
    : Only formats the migrated code (default).
  • =all
    : Formats all code.
  • =none
    : Do not format any code.
--format-style=<value>
Sets the formatting style.
The values are:
  • =llvm
    : Use the LLVM coding style.
  • =google
    : Use the Google* coding style.
  • =custom
    : Use the coding style defined in the
    .clang-format
    file (default).
Example for the .clang-format file content:
BasedOnStyle: LLVM IndentWidth: 4 TabWidth: 4 UseTab: ForIndentation
--help
Provides list of
Intel®
DPC++
Compatibility Tool
specific options.
--in-root=<dir>
The directory path for the root of the source tree that needs to be migrated. Only files under this root are migrated. Default:
  • The current directory, if the input source files are not provided.
  • The directory of the first input source file, if the input source files are provided.
Details:
Any source within the directory specified by
--in-root
(at any nesting level) may be migrated. Any header file within the directory specified by
--in-root
(at any nesting level) included by the source or header file, which is being migrated, is also migrated. Files from outside the
--in-root
directory are considered system files and they will not be migrated even if they are included by any of the program source files.
--keep-original-code
Keeps the original code in the comments of generated
Data Parallel C++ (
DPC++
)
files. Default:
off
.
--no-cl-namespace-inline
Do not use cl namespace (
cl::
) inlining. Default:
off
.
--no-dry-pattern
Do not use a Don't Repeat Yourself (DRY) pattern when functions from the
dpct
namespace are inserted. Default:
off
.
--out-root=<dir>
The directory path for root of generated files. A directory is created if it does not exist. Default:
dpct_output
.
The relative paths for the generated files are maintained, and the extension is changed as follows:
  • *.cu → *.dp.cpp
  • *.cpp → *.cpp.dp.cpp
  • *.cc → *.cc.dp.cpp
  • *.cxx → *.cxx.dp.cpp
  • *.C → *.C.dp.cpp
  • *.cuh → *.dp.hpp
  • *.h *.hpp *.hxx
    → extensions are kept the same
--output-file=<file>
Redirects the
stdout
/
stderr
output to
<file>
in the output directory specified by the
--out-root
option.
--output-verbosity=<value>
Sets the output verbosity level:
  • =silent
    : Only messages from clang.
  • =normal
    : 'silent' and warnings, errors, and notes from the
    Intel®
    DPC++
    Compatibility Tool
    .
  • =detailed
    : 'normal' and messages about which file is being processed.
  • =diagnostics
    : 'detailed' and information about the detected conflicts and crashes (default).
-p=<dir>
The directory path for the compilation database (
compile_commands.json
). When no path is specified, a search for
compile_commands.json
is attempted through all parent directories of the first input source file.
--process-all
Migrates/copies all files from the
--in-root
directory to the
--out-root
directory. The
--in-root
option should be explicitly specified. Default:
off
.
--report-file-prefix=<prefix>
Prefix for the report file names. The full file name will have a suffix derived from the
report-type
and an extension derived from the
report-format
. For example:
<prefix>.apis.csv
or
<prefix>.stats.log
. If this option is not specified, the report goes to
stdout
. The report files are created in the directory, specified by
-out-root
.
--report-format=<value>
Format of the reports:
  • =csv
    : The output is lines of comma separated values. The report name extension will be
    .csv
    (default).
  • =formatted
    : The output is formatted for easier human readability. The report file name extension is
    log
    .
--report-only
Only reports are generated. No
DPC++
code is generated. Default:
off
.
--report-type=<value>
Comma separated list of report types:
  • =apis
    : Information about API signatures that need migration and the number of times they were encountered. The report file name has the
    .apis
    suffix added.
  • =stats
    : High level migration statistics: Lines Of Code (LOC) that are migrated to
    DPC++
    , LOC migrated to
    DPC++
    with helper functions, LOC not needing migration, LOC needing migration but are not migrated. The report file name has the
    .stats
    suffix added (default).
  • =all
    : All of the reports.
--stop-on-parse-err
Stop migration and generation of reports if parsing errors happened. Default:
off
.
--suppress-warnings=<value>
Comma separated list of migration warnings to suppress. Valid warning IDs range from 1000 to 1047. Hyphen-separated ranges are also allowed. For example:
-suppress-warnings=1000-1010,1011
.
--suppress-warnings-all
Suppresses all migration warnings. Default:
off
.
--sycl-named-lambda
Generates kernels with the kernel name. Default:
off
.
--usm-level=<value>
Sets the Unified Shared Memory (USM) level to use in source code generation:
  • =restricted
    : Uses API from
    DPC++
    Explicit and Restricted Unified Shared Memory extension for memory management migration (default).
  • =none
    : Uses helper functions from
    Intel®
    DPC++
    Compatibility Tool
    header files for memory management migration.
--vcxprojfile=<file>
The file path of
vcxproj
.
--version
Shows the version of the tool.
Specifying any of these options will trigger report generation.
  • --report-file-prefix
  • --report-type
  • --report-format
  • --report-only

Source Files

To work with source files use
<source0> ...
to create paths for your input source files. These paths can be found in the compilation database.
Examples:
  • Migrate single source file:
    dpct source.cpp
  • Migrate single source file with C++11 features:
    dpct --extra-arg="-std=c++11" source.cpp
  • Migrate all files available in compilation database:
    dpct -p=<path to location of compilation database file>
  • Migrate one file in compilation database:
    dpct -p=<path to location of compilation database file> source.cpp

Product and Performance Information

1

Performance varies by use, configuration and other factors. Learn more at www.Intel.com/PerformanceIndex.