v++ General Compilation Options - v++ General Compilation Options - 2026.1 English - UG1702

Vitis Reference Guide (UG1702)
Document ID
UG1702
Release Date
2026-06-23
Version
2026.1 English

The general v++ compilation options can appear on the command-line or in a configuration file. It can include the -c (or --compile) option, a --mode when generating an AI Engine component or HLS component, the --platform or --part, the build --target, and a --config file as shown below:

v++ -c --mode aie --platform vek385_base --target hw \
-config ./aie_config.cfg <input_files...>
Tip: Relative paths on the command line are relative to the current working directory where you launch the command. Relative paths in the config file are relative to the location of the config file.

You can use most v++ command options in a config file or on the command line. However, the following options work only on the command line.

-c [ --compile ]

Run compilation mode.

--config <file_name>
Specifies the config file path and name.
--mode [ aie | hls ]

Specifies the compilation mode as either compile an AI Engine component, or an HLS component.

Important: The absence of --mode puts the v++ -c command in the traditional top-down compilation mode for the Vitis kernel flow as described in Compiling C/C++ PL Kernels in the Data Center Acceleration using Vitis (UG1700).
-h [ --help ]

Prints usage message for options. Can be combined with the --mode option to list the available options for the AI Engine or HLS components.

-v [ --version ]

Prints version information.

--input_files <arg>

Specify input file(s). Input file(s) can also be specified positionally without using the --input_files option.

-o [ --output ] <arg>

Applies to: Link, Package. Specify the output file name and path. Default: a.xclbin for the v++ --link command.

-f [--platform]

Specifies a path to a Vitis platform file that defines the hardware and software components available for AI Engine components, HLS components, and Applications. The argument can be a hardware platform (XSA) as recommended for hardware target in Versal devices, or a base platform (XPFM).

--log_dir <arg>

Specify a directory to copy internally generated log files.

--macro_dir <arg>

Specify a macro to define a base directory: <macro_name>=<base_directory> Macros with a $ sign can be used to specify a relative path.

--report_dir <arg>

Specify a directory to copy report files.

--work_dir <arg>

Optionally specify a working directory for the build and output files. For --mode aie the work directory defaults to ./Work. For --mode hls it defaults to the top-level function specified by hls.syn.top. Specify this option only on the command line.

e.

--aie_legacy

Use legacy options for aiecompiler.

You can use the following options in a config file or on the command-line:

Tip: As these are general options they do not need to be placed under a header (such as [AIE] or [HLS]) in the config file.
-t [ --target ] <arg>

The --target argument has different values when used with or without --mode.

  • Used with --mode the target defines the compilation target of the AI Engine or HLS component.
    • x86: Specifies compilation for x86 simulation of an AI Engine component, or for C-simulation of the HLS component.
    • hw: Specifies compilation for
      • AI Engine simulator (AI Engine components)
      • C/RTL Co-Simulation (HLS components)
      • Running on the pysical device (either AI Engine or HLS components).
  • Used without --mode: the target defines the tradition build targets (hw_emu, hw) of the Application flow as described in Creating an Integration Project Component.

Specify hw_emu or hw for classic v++ compilation, and specify x86 simulation or hw for AI Engine modes. The default target is hw.

The default target is hw.

--part <arg>

Specify part family or part value. Note this option is mutually exclusive with --platform or --hls.board.

-D [ --define ] <name=definition>

Predefine <name> as a macro with <definition>.

-I [ --include ] <arg>

Include the specified directory in the list of directories to be searched for header files.