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

The v++ command supports options and directives for compilation, linking, and packaging processes as described below.

platform=xilinx_u50_gen3x16_xdma_5_202210_1

--advanced

Applies to

Compile, Link, Package

Specifies parameters and properties for use by the v++ command. See --advanced Options for more information.

--board_connection

Applies to

Link

--board_connection

Specifies a dual in-line memory module (DIMM) board file for each DIMM connector slot. Specify the board with the Vendor:Board:Name:Version (vbnv) attribute of the DIMM card. This is the attribute in the board repository.

For example:

<DIMM_connector>:<vbnv_of_DIMM_board>

-c | --compile

Applies to

Compile

--compile

Required for compilation, but mutually exclusive with --link and --package. Run v++ -c to generate XO files from kernel source files.

--clock

Applies to

Link

Provides a method for assigning clocks to kernels during the linking process. See --clock Options for more information.

--config

Applies to

Compile, Link, Package

--config <config_file> ...

Specifies a configuration file containing v++ command options. The configuration file can be used to capture compilation, linking, or packaging strategies. You can reuse the strategies d by referring to the config file on the v++ command line. In addition, the config file allows the v++ command line to be shortened to include only the options that are not specified in the config file. Refer to the Vitis Compiler Configuration File for more information.

v++ -l --config system.cfg --config vivado.cfg ...

--connectivity

Applies to

Link

Specifies directives to the v++ linker to integrate compiled components. See --connectivity Options for more information.

--custom_script

Applies to

Link

--custom_script <kernel_name>:<file_name>

Lets you specify a custom Tcl script to use during compilation of a Vitis HLS kernel. Use it with the --export_script option to extract the default Tcl script, edit it, and resubmit it — this lets you customize how Vitis HLS compiles the kernel.

v++ -c -k kernel1 --export_script ...
*** Modify the exported script to customize in some way, then resubmit. ****
v++ -c --custom_script kernel1:./kernel1.tcl ...

You can use this option with the v++ --link command for the hardware build target (-t hw). The option lets you specify the absolute path to an run_script_map.dat file.

The run_script_map.dat file contains a list of steps in the build process and Tcl scripts. The Vitis or Vivado tool runs these steps during the build process. You can edit run_script_map.dat to specify custom Tcl scripts to run at various steps in the build process. Use the following steps to customize the Tcl scripts:

1. Run the build process to specify the --export_script option.

   v++ -t hw -l -k kernel1 --export_script ...

2. Copy the Tcl scripts in the run_script_map.dat file for any of the steps you want to customize. For example, copy the Tcl file specified for the synthesis run, or the implementation run. You must copy the file to a separate location, outside of the project build structure.
3. Edit the Tcl script that you copied. Add or modify any of the existing commands to create a new custom Tcl script.
4. Edit the run_script_map.dat file to point a specific implementation step to the new custom script.
5. Relaunch the build process using the --custom_script option. Specify the absolute path to the run_script_map.dat file as shown below.

   v++ -t hw -l -k kernel1 --custom_script /path/to/run_script_map.dat

read_xdc dont_touch.xdc
set_property used_in_implementation false [get_files dont_touch.xdc]

--debug

Applies to

Link

Specifies the addition of debug IP core insertion into the hardware design. See --debug Options for more information.

-D | --define

Applies to

Compile, Link

--define <arg>

Predefines name as a macro with definition. This option passes to the v++ preprocessor.

Valid macro name and definition pair: <name>=<definition>.

--export_archive

Applies to

Link

--export_archive

Instructs the v++ linker to generate a Vitis metadata archive (.vma). You can import the archive into a Vivado hardware project in lieu of a fixed hardware XSA or .xclbin file. Refer to Packaging for Vitis Export to Vivado Flow in the Embedded Design Development Using Vitis (UG1701) for details on using the .vma file.

--export_script

Applies to

Link

--export_script

Runs the build process up to the point of exporting one or more script files, and then stops execution. You must use the --custom_script option to complete the build process. The --custom_script option lets you edit the exported script, or list of scripts, and then rerun the build using your custom scripts.

v++ -c -k kernel1 -export_script ...

When used with the v++ --link command for the hardware build target (-t hw), this option exports a run_script_map.dat file in the current directory. This file contains a list of steps in the build process. The file also contains Tcl scripts that Vitis and Vivado tools run during those steps. You can edit the specified Tcl scripts, customizing the build process in those scripts, and relaunch the build using the --custom_script option. Export the run_script_map.dat file using the following command:

v++ -l -t hw --export_script ...

--freqhz

Applies to

Compile and Link

--freqhz <value>::<cu>[.<clk_pin>][,<cu_n>[.<clk_pin_n>]]

Specifies a frequency for a PL component during compilation, or for the system during linking. The --freqhz option overrides any default clock frequency and applies the stated frequency during compilation and linking.

Specify a clock frequency and a list of associated compute unit names and, optionally, their clock pins:

<value>

Specify this as MHz or without units. Without units, the value is in Hertz. For example, specify 150 MHz as 150000000.

[cu[.clk_pin]]

Optionally specifes a PL kernel or instance of a PL kernel (Compute Unit) target for the specified clock frequency. The PL kernel or instance of a PL kernel lets you specify a different frequency for different instances of kernels. You can also specify the clock pin of the CU by adding the .clk_pin syntax. You can add multiple CU and clock pins in a single --freqhz option with a single frequency value.

For example:

v++ -l -t hw -–platform <pfm_name> --freqhz=200000000:mm2s \
--freqhz=300000000:s2mm –config system.cfg

--from_step

Applies to

Compile, Link, Package

--from_step <arg>

Specifies a step name for the Vitis compiler to start the build process. If intermediate results are available, the link process fast forwards and begins execution at the named step when possible. You can run the build through a --to_step, and then resume the build process at the --from_step. You can use the --list_steps option to determine the list of valid steps.

For example:

v++ --link --from_step vpl.update_bd

-g

Applies to

Compile, Link

-g

Generates code for debugging the kernel during hardware emulation. Using this option adds features to help debugging the kernel during compilation.

For example:

v++ -g ...

-h | --help

Applies to

Compile, Link, Package

-h

Prints the help contents for the v++ command. For example:

v++ -h

--hls

Applies to

Compile

Specifies commands for the Vitis HLS synthesis process during kernel compilation.

-I | --include

Applies to

Compile, Link

--include <arg>

Adds the specified directory to the list of directories for searching header files. This option passes to the Vitis compiler pre-processor.

Classic Compile Mode (v++ -c -k)

Usage: v++ -c -k --include <path>

HLS Mode (v++ -c --mode hls)

Usage: do not use the --include <path> format. Specify include paths in an HLS configuration file instead of with compiler flags.

AIE Mode (v++ -c --mode aie)

Usage: v++ -c -k --include <path>

--input_files <input_file>

Applies to

Compile, Link, Package

--input_files <input_file1> <input_file2> ...

Specifies a C/C++ kernel source file for v++ -c -k classic or v++ -c --mode aie. You can also specify XO files for v++ linking.

For example:

v++ -l --input_files kernel1.xo kernelRTL.xo ...

v++ -l kernel1.xo kernelRTL.xo ...

The --input_files option can be used to specify positional arguments on the command line, but typically, file names are provided directly without the option.

Example for Linking:

is more commonly written as:

Classic Compilation:

v++ -c -k mykernel --input_files mykernel.cpp is commonly used as: v++ -c -k mykernel mykernel.cpp

AIE Mode:

v++ -c --mode aie --input_files mygraph.cpp is typically: v++ -c --mode aie mygraph.cpp

HLS Mode:

Usage of --input_files with HLS mode: v++ -c --mode hls --input_files myhlskernel.cpp is not supported.

Linking:

The --input_files option can specify files like libadf.a, .xo, and .vss. Specify these arguments directly as positional arguments.

Packaging:

When packaging, --input_files can include libadf.a, .vss, fixed.xsa, and .xclbin files, especially for AMD Zynq™ UltraScale+™ devices. The output from linking is typically fixed.xsa or .xclbin files.

--interactive

Applies to

Link

--interactive [ impl ]

v++ configures the required environment and launches the Vivado tool with the implementation project.

Because you are interactively launching the Vivado tool, the linking process stops after the vpl step. This is the equivalent of using the --to_step vpl option in your v++ command.

When you finish interacting with the Vivado tool, save the design checkpoint (DCP). You can then resume the Vitis compiler linking process using the v++ --from_step rtdgen. You can also use the --reuse_impl or --reuse_bit options to read in the implemented DCP file or bitstream.

For example:

v++ --interactive impl
## Interactively use the Vivado tool
v++ --from_step rtdgen

-k | --kernel

Applies to

Compile

--kernel <arg>

Compiles only the specified kernel from the input file. Only one -k option is allowed per v++ command. Valid values include the name of the kernel to be compiled from the input .c/.cpp kernel source code.

Vitis tools requires this option for C/C++ kernels. You must identify the kernel by -k or --kernel.

Classic compilation

Use -k with v++ -c to identify the kernel to compile from a source file.

AIE mode

Do not use -k with v++ -c --mode aie.

HLS mode

Do not use -k with v++ -c --mode hls.

Invalid combination

v++ -c -k --mode hls is not a valid command.

--kernel_frequency

Applies to

Link

--kernel_frequency <freq> | <clockID>:<freq>[<clockID>:<freq>]

Specifies a user-defined clock frequency (in MHz) for the kernel, overriding the default clock frequency defined on the hardware platform. The <freq> specifies a single frequency for kernels with only a single clock. It can also be used to specify the <clockID> and the <freq> for kernels that support two clocks.

The syntax for overriding the clock on a platform with only one kernel clocks to specify the frequency in MHz:

v++ --kernel_frequency 300

To override a specific clock on a platform with two clocks, specify the clock ID and frequency:

v++ --kernel_frequency 0:300

To override both clocks on a multi-clock platform, specify each clock ID and the corresponding frequency. For example:

v++ --kernel_frequency 0:300|1:500

-l | --link

Applies to

Link

--link

A required option for the linking process, which follows compilation, but is mutually exclusive with --compile or --package. Run v++ in link mode to link XO input files and generate a fixed hardware platform (XSA). For MPSoC and UltraScale targets, generates an .xclbin file instead of fixed .xsa.

--linkhook

Applies to

Link

Lets you customize the build process for the device binary by specifying Tcl scripts to be run at specific steps in the implementation flow. See --linkhook Options for more information.

--list_steps

Applies to

Compile, Link, Package

--list_steps

Lists valid run steps for a given target. This option returns steps that can be used in the --from_step or --to_step options. You must specify this command with the following options:

• -t | --target [hw_emu | hw ]:
• [ --compile | --link ]: Specifies the list of steps from either the compile or link process for the specified build target.

For example:

v++ -t hw_emu --link --list_steps

--log_dir

Applies to

Compile, Link, Package

--log_dir <dir_name>

Specifies a directory to store log files into. If you do not specify --log_dir, the tool saves the log files to ./_x/logs. Refer to Output Directories of the v++ Command for more information.

For example:

v++ --log_dir /tmp/myProj_logs ...

--message_rules

Applies to

Compile, Link, Package

--message-rules <file_name>

Specifies a message file with rules for controlling messages. Refer to Using the Message Rule File for more information.

For example:

v++ --message_rules ./minimum_out.mrf ...

--mode

Applies to

Compile, Link

Specifies a compilation mode for the v++ command. The mode is specified as one of aie, hls or vss. The mode targets AI Engine, PL, or to create a Vitis subsystem, respectively.

v++ -c --mode aie

Creates a libadf.a component. See AI Engine Tools and Flows User Guide (UG1076) for more details. Configuration commands in v++ Mode AI Engine.

v++ -c --mode hls

Creates an .xo kernel or IP as an HLS component (refer to Vitis High-Level Synthesis User Guide (UG1399). You can also use this mode with configuration file commands in v++ Mode HLS.

v++ -l --mode vss

The v++ --mode vss selects a link flow that creates a Vitis Subsystem (VSS) artifact. The accepted value is vss. If you do not specify the mode, the tool uses the standard link flow.

A VSS is a platform-independent, reusable design component consisting of compiled .xo and libadf.a sub-components.

The flow generates a subsystem package with metadata and binaries. You can instantiate and link the package within a system context on the target platform later.

See Linking a VSS Component in the Embedded Design Development Using Vitis (UG1701) for details.

--no_ip_cache

Applies to

Link

--no_ip_cache

Disables the IP cache for out-of-context (OOC) synthesis for Vivado Synthesis. Disabling the IP cache repository requires the tool to regenerate the IP synthesis results for every build, and can increase the build time. However, it also results in a clean build, eliminating earlier results for IP in the design.

For example:

v++ --no_ip_cache ...

-O | --optimize

Applies to

Link

--optimize <arg>

Specifies the optimization level of the Vivado implementation results. Valid optimization values include the following:

• 0: Default optimization. Reduces compilation time.
• 1: Optimizes to reduce power consumption by running Vivado implementation strategy Power_DefaultOpt. This takes more time to build the design.
• 2: Optimizes to increase kernel speed. This option increases build time, but also improves the performance of the generated kernel by adding the PHYS_OPT_DESIGN step to implementation.
• 3: This optimization provides the highest level performance in the generated code, but compilation time can increase considerably. This option specifies retiming during synthesis, and enables both PHYS_OPT_DESIGN and POST_ROUTE_PHYS_OPT_DESIGN during implementation.
• s: Optimizes the design for size. This reduces the logic resources of the device used by the kernel by running the Area_Explore implementation strategy.
• quick: Reduces Vivado implementation time, but can reduce kernel performance, and increases the resources used by the kernel. This enables the Flow_RuntimeOptimized strategy for both synthesis and implementation.

For example:

v++ --link --optimize 2

-o | --output

Applies to

Compile, Link, Package

-o <output_name>

Specifies the name of the output file generated by the v++ command.

• The compilation (-c) process output name must end with the XO file suffix, for Xilinx object file.
• This applies for v++ -c -k classic compilation.
• The linking (-l) process output file must end with an .xsa (or an .xclbin for Zynq platforms).
• The --export_archive command requires the .vma suffix.
• The --package command takes the .xsa as input and outputs the .xclbin.

For example:

v++ -o krnl_vadd.xo

If you do not specify --o or --output, the output file names default to the following:

Compilation

a.o

Linking

An .xsa (or an .xclbin for Zynq platforms)

Packaging

a.xclbin

-p | --package

Applies to

Package

Specifies options for the Vitis compiler to package your design for either running emulation or running on hardware. See v++ Command for more information.

--part

Applies to

Compile, Link, Package

--part <part_name>

Specifies an AMD part for use in compiling, linking, and packaging the components of your design. You can use the --part command to specify a device rather than a full platform or XSA. Specifying v++ --link --part <Versal Gen 1 part only> instructs the tools to generate a simple hardware emulation platform for the specified AMD Versal™ device.

For example:

v++ --link --part xcvc1902-vsva2197-2MP-e-S --target hw_emu ...

-f | --platform

Applies to

Compile, Link, Package

--platform <platform_name>

Specifies the name of a supported acceleration platform. The $PLATFORM_REPO_PATHS environment variable determines the name. You can also use this command to specify the full path to the extensible hardware .xsa or base platform .xpfm file. For a list of supported platforms for the release, see the Vitis Software Platform Installation in the Vitis Software Platform Release Notes (UG1742).

This is a required option for both compilation and linking. The --platform option accepts either a platform name, or the path to a platform file xpfm, using the full or relative path. The preferred usage is to specify the fixed.xsa.

For example:

v++ --platform vek385_base

--profile

Applies to

Compile, Link

Specifies options to configure the Xilinx Runtime environment to capture application performance information. See --profile Options for more information.

--remote_ip_cache

Applies to

Link

--remote_ip_cache <dir_name>

Specifies the location of the remote IP cache directory for Vivado Synthesis to use during out-of-context (OOC) synthesis of IP. The Vivado synthesis tool reuse synthesis results for IP in unchanged in iterations of a design. This can reduce the time to build your .xclbin files, due to reusing synthesis results.

If you do not specify the --remote_ip_cache, the IP cache writes to the current working directory launching v++. You can use this option to provide a different cache location, and locations that multiple projects use.

For example:

v++ --remote_ip_cache /tmp/IP_cache_dir ...

--report_dir

Applies to

Compile, Link, Package

--report_dir <dir_name>

Specifies a directory to store report files into. If --report_dir is not specified, the tool saves the report files to ./_x/reports. Refer to Output Directories of the v++ Command for more information.

For example:

v++ --report_dir /tmp/myProj_reports ...

-R | --report_level

Applies to

Compile, Link, Package

--report_level <arg>

Valid report levels: 0, 1, 2, estimate.

These report levels have mappings kept in the optMap.xml file. You can override the installed optMap.xml to define custom report levels.

• -R0 specification turns off all intermediate design checkpoint (DCP) generation during Vivado implementation. Turns on post-route timing report generation.
• The -R1 specification includes everything from -R0, plus report_qor_assessment pre-opt_design, report_qor_assessment post-opt_design, and enables all intermediate DCP generation.
• The -R2 specification includes everything from -R1, plus report_qor_assessment post-route_design.
• The -Restimate specification forces Vitis HLS to generate a design.xml file if it does not exist. The tool then generates a System Estimate report (refer to System Estimate Report in the Data Center Acceleration using Vitis (UG1700).

For example:

v++ -R2 ... 

--reuse_bit

--reuse_bit <arg>

Applies to

Link

Specifies the path and file name of generated bitstream file (.bit) to use when generating the device binary (xclbin) file. You can specify the --to_step option to interrupt the Vitis build process and manually place and route a synthesized design to generate the bitstream. See Using --to_step and Launching Vivado Interactively in the Data Center Acceleration using Vitis (UG1700) for details.

For example:

v++ --link --reuse_bit ./project.bit

--reuse_impl

--reuse_impl <arg>

Applies to

Link

Specifies the path and file name of an implemented design checkpoint (DCP) file to use when generating the device binary (xclbin) file. The link process uses the specified implemented DCP to extract the FPGA bitstream and generates the xclbin. You can manually edit theVivado project that a previous Vitis build created. You can also specify the --to_step option to interrupt the Vitis build process and manually place and route a synthesized design. This allows you to work interactively with Vivado Design Suite to change the design and use DCP in the build process.

For example:

v++ --link --reuse_impl ./manual_design.dcp

-s | --save-temps

Applies to

Compile, Link, Package

--save-temps

Directs the v++ command to save intermediate files/directories created during the compilation and link process. Use the --temp_dir option to specify a location to write the intermediate files to.

For example:

v++ --save-temps ...

-t | --target

Applies to

Compile, Link, Package

-t [ hw_emu | hw ]

Specifies the build target, as described in Selecting the Build Target in the Data Center Acceleration using Vitis (UG1700). The build target determines the results of the compilation and linking processes. You can choose to build an emulation model for debug and test, or build the actual system to run in hardware. The build target defaults to hw if -t is not specified.

The valid values are as follows:

• hw_emu: Hardware emulation
• hw: Hardware

For example:

v++ --link -t hw_emu

--temp_dir

Applies to

Compile, Link, Package

--temp_dir <dir_name>

This allows you to manage the location where the tool writes temporary files created during the build process. The temporary results are written by the v++ compiler, and then removed, unless the --save-temps option is also specified.

If --temp_dir is not specified, the tool saves the temporary files to ./_x/temp. Refer to Output Directories of the v++ Command for more information.

For example:

v++ --temp_dir /tmp/myProj_temp ...

--to_step

Applies to

Compile, Link, Package

--to_step <arg>

Specifies a step name, for either the compile or link process, to run the build process through that step. You can use the --list_step option to determine the list of valid compile or link steps.

The build process terminates after completing the named step. At this time, you can interact with the build results. You can manually access the HLS project or the Vivado Design Suite project to perform specific tasks before returning to the build flow. You can also launch the v++ command with the --from_step option.

You must also specify --save-temps when using --to_step to preserve the temporary files required by the Vivado tools. For example:

v++ --link --save-temps --to_step vpl.update_bd

--user_board_repo_paths

Applies to

Link

--user_board_repo_paths

Specifies an existing user board repository for DIMM board files. This value is pre-pended to the board_part_repo_paths property of the Vivado project.

--user_ip_repo_paths

Applies to

Link

--user_ip_repo_paths <repo_dir>

Specifies the directory location of one or more user IP repository paths to be searched first for IP used in the kernel design. The Vivado tool uses the value that appends to the start of ip_repo_paths to locate IP cores. Vivado uses IP definitions from these specified paths ahead of IP repositories from the hardware platform (.xsa) or the AMD IP catalog.

The following lists show the priority order for locating IP definitions during the build process, from highest to lowest.

• For the system hardware build (-t hw):
  1. IP definitions from --user_ip_repo_paths.
  2. Kernel IP definitions (vpl --iprepo switch value).
  3. IP definitions from the IP repository associated with the platform.
  4. IP cache from the installation area (for example, <Install_Dir>/Vitis/2026.1/data/cache/).
  5. AMD IP catalog from the installation area (for example, <Install_Dir>/Vitis/2026.1/data/ip/)
• For the hardware emulation build (-t hw_emu):
  1. IP definitions and User emulation IP repository from --user_ip_repo_paths.
  2. Kernel IP definitions (vpl --iprepo switch value).
  3. IP definitions from the IP repository associated with the platform.
  4. IP cache from the installation area (for example, <Install_Dir>/Vitis/2026.1/data/cache/).
  5. $::env(XILINX_VITIS)/data/emulation/hw_em/ip_repo
  6. $::env(XILINX_VIVADO)/data/emulation/hw_em/ip_repo
  7. AMD IP catalog from the installation area (for example, <Install_Dir>/Vitis/2026.1/data/ip/)

For example:

v++ --user_ip_repo_paths ./myIP_repo ...

-v | --version

-v

Prints the version and build information for the v++ command. For example:

v++ -v

--vivado

Applies to

Link

Specifies properties and parameters to configure the Vivado synthesis and implementation environment prior to building the device binary. See --vivado Options for more information.