v++ General Compilation Options - 2025.1 English - UG1702

Vitis Reference Guide (UG1702)
Document ID
UG1702
Release Date
2025-07-08
Version
2025.1 English

The general v++ compilation options typically appear on the command-line rather than 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 xilinx_vck190_base_202420_1 --target hw \
-config ./aie_config.cfg <input_files...>
Tip: Relative paths used on the command line are relative to the current working directory where the command is launched. Relative paths in the config file are relative to the location of the config file.

Command options for v++ can be generally be used in a config file or on the command-line. However, the following options are only available for use 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 ]

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

This is a path to a Vitis platform file that defines the hardware and software components available for AI Engine components, HLS components, and Applications. The platform can be a platform specification (XPFM) or a hardware specification (XSA).

--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. This option can only be specified on the command line.

--aie_legacy

Use legacy options for aiecompiler.

The following options can either be used 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 use with AI Engine simulator for AI Engine components, for C/RTL Co-simulation for HLS components, or to run on the physical device for either components.
  • Used without --mode: the target defines the tradition build targets (hw_emu, hw) of the Application flow as described in Creating a System Project for Heterogeneous Computing.

Specify a target as hw_emu, or hw for the classic v++ compilation mode; or as x86 simulation for AI Engine compilation mode or hw for AI Engine simulation. 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.