Command Line Options Reference

This topic shows the command line options with a short description, current deprecated options, and information for working with source files.

Command Line Options

The following table lists all current Intel® DPC++ Compatibility Tool command line options in alphabetical order.

Option

Description

--always-use-async-handler

Always create cl::sycl::queue with the async exception handler. Default: off.

--assume-nd-range-dim=<value>

Provides a hint to the tool on the dimensionality of nd_range to use in generated code. The values are:

  • =1: Generate kernel code assuming 1D nd_range where possible, and 3D in other cases.

  • =3: Generate kernel code assuming 3D nd_range (default).

--build-script-file=<file>

Specifies the name of generated makefile for migrated file(s). Default name: Makefile.dpct.

--comments

Insert comments explaining the generated code. Default: off.

--cuda-include-path=<dir>

The directory path of the CUDA* header files.

--custom-helper-name=<name>

Specifies the helper headers folder name and main helper header file name. Default: dpct.

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

--gen-build-script

Generates makefile for migrated file(s) in -out-root directory. Default: off.

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

DEPRECATED: Do not use cl:: namespace inline. Default: off. This option will be ignored if the replacement option --use-explicit-namespace is used.

--no-dpcpp-extensions=<value>

Comma separated list of DPC++ extensions not to be used in migrated code. By default, these extensions will be used in migrated code.

  • =enqueued_barriers: Enqueued barriers DPC++ extension.

--no-dry-pattern

Do not use a Don’t Repeat Yourself (DRY) pattern when functions from the dpct namespace are inserted. Default: off.

--no-incremental-migration

Tells the tool to not perform an incremental migration. Default: off (incremental migration happens).

--optimize-migration

Generates DPC++ code applying more aggressive assumptions that potentially may alter the semantics of your program. 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 or copies all files, except hidden, from the --in-root directory to the --out-root directory. The --in-root option should be explicitly specified. Default: off.

Details:

If --process-all and --in-root options are specified, but no input files are provided, the tool migrates or copies all files, except hidden, from the --in-root directory to the output directory.

  • If there is a compilation database:

    • Files from the compilation database are migrated with the options specified in the compilation database

    • Files with the .cu extension that are not listed in the compilation database are migrated as standalone

    • Remaining files are copied to the –out-root directory

  • If there is no compilation database:

    • Files with the .cu extension are migrated as standalone

    • Remaining files are copied to the -out-root directory

--process-all is ignored if input files are provided on the command line.

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

Specifies the type of report. Values are:

  • =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 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.

--use-custom-helper=<value>

Customize the helper header files for migrated code. The values are:

  • =none: No customization (default).

  • =file: Limit helper header files to only the necessary files for the migrated code and place them in the --out-root directory.

  • =api: Limit helper header files to only the necessary APIs for the migrated code and place them in the --out-root directory.

  • =all: Generate a complete set of helper header files and place them in the --out-root directory.

--use-experimental-features=<value>

Comma separated list of experimental features to be used in migrated code. By default, experimental features will not be used in migrated code.

The values are:

  • =nd_range_barrier: Experimental helper function used to help cross group synchronization during migration.

--use-explicit-namespace=<value>

Defines the namespaces to use explicitly in generated code. The value is a comma separated list. Default: dpct, sycl.

Possible values are:

  • =none: Generate code without namespaces. Cannot be used with other values.

  • =cl: Generate code with cl::sycl:: namespace. Cannot be used with sycl or sycl-math values.

  • =dpct: Generate code with dpct:: namespace.

  • =sycl: Generate code with sycl:: namespace. Cannot be used with cl or sycl-math values.

  • =sycl-math: Generate code with sycl:: namespace, applied only for SYCL math functions. Cannot be used with cl or sycl values.

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

Note

Specifying any of these options will trigger report generation.

  • --report-file-prefix

  • --report-type

  • --report-format

  • --report-only

Deprecated Command Line Options

The following table lists Intel® DPC++ Compatibility Tool command line options that are currently deprecated.

Deprecated Options

Suggested Replacement

--no-cl-namespace-inline

--use-explicit-namespace

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