Building the System

When building the system, it best practice to use the three available build targets described in Build Targets. Each build target is represented in a separate build configuration in the Assistant view. Work through these build configurations in the following order:

Emulation-SW: Build for software emulation (sw_emu) to confirm the algorithm functionality of both the host program and kernel code working together.
Emulation-HW: Build for hardware emulation (hw_emu) to compile the kernel into a hardware description language (HDL), confirm the correctness of the generated logic, and evaluate its simulated performance.
Hardware: Perform a system hardware build (hw) to implement the application running on the target platform.

Before launching the build command, configure each of these build configurations to ensure it meets your needs. Select the specific build configuration, and click the Settings icon to open the Build Configuration Settings dialog box. For more information on using this dialog box, refer to Vitis Build Configuration Settings.

Beyond the build configuration settings, many of the settings that will affect your application are contained in the Hardware Function, accessed through the Vitis Hardware Function Settings dialog box. It is a good idea to review each of the Settings dialog boxes as discussed in Configuring the Vitis IDE.

From the Assistant view, with the various options of the build configuration specified, you can start the build process by selecting a build configuration and clicking on the Build () button. The Vitis core development kit uses a two part build process that generates the FPGA binary (.xclbin) for the hardware kernels using the Vitis™ compiler v++ command, and compiles and links the host program code using the g++ compiler.

After the build process is complete, the Assistant view shows the specific build configuration with a green check mark to indicate it has been successfully built, as shown in the following figure. You can open any of the build reports, such as the Compile Summary in the hardware function, or the Link Summary in the binary container. Right-click the report in the Assistant view and select Open in Vitis Analyzer.

Figure 1: Assistant View - Successful Builds

With the build complete, you can now run the application in the context provided by the specific build configuration. For instance, exercise a C-model of the host program and FPGA binary working together in the Emulation-SW build, or review the host program and the RTL kernel code in simulation in the Emulation-HW build, or run the application on the target platform in the Hardware build.

To run the application from within the Vitis IDE, select the build configuration, and click the Run button () to launch the default run configuration. You can also right-click the build configuration and use the Run menu to select a specific run configuration, or edit a run configuration as described in Vitis Run and Debug Configuration Settings.

TIP: The Vitis IDE creates a folder named after the run configuration in the specific build configuration being run. For instance ./project/Emulation-HW/run_config. The output files and logs from the application run are written to this folder. All arguments passed to the host program should be written relative to this folder.

Vitis IDE Guidance View

After building or running a specific build configuration, the Guidance tab of the Console view displays a list of errors, warnings, and suggestions related to the build and run process. The Guidance view is automatically populated and displayed in the tabs located in the Console view. You can review the guidance messages to make any changes that might be needed in your code or build process.

After running hardware emulation, the Guidance view might look like the following figure.

TIP: The Guidance report can also be viewed in Vitis analyzer as discussed in the Using the Vitis Analyzer.

To simplify sorting through the Guidance view information, the Vitis IDE lets you search, and filter the Guidance view to locate specific guidance rule entries. You can collapse or expand the tree view, or even suppress the hierarchical tree representation and visualize a condensed representation of the guidance rules. Finally, you can select what is shown in the Guidance view by enabling or disabling the display of warnings, as well as rules that have been met, and also restrict the specific content based on the source of the messages such as build and emulation.

By default, the Guidance view shows all guidance information for the project selected in the drop down. To restrict the content to an individual build or run step, do the following:

Select Window > Preferences
Select the category Guidance.
Deselect Group guidance rule checks by project.

Working with Vivado Tools from the Vitis IDE

The Vitis core development kit calls the Vivado Design Suite during the linking process to automatically run RTL synthesis and implementation when generating the FPGA binary (.xclbin). You also have the option of launching the Vivado tool directly from within the Vitis IDE to interact with the project for synthesizing and implementing the FPGA binary. There are three commands to support interacting with the Vivado tool from the Vitis IDE, accessed through the Xilinx > Vivado Integration menu:

TIP: The hw_link project must be opened and be the current project in the IDE for these options to be available.

Open Vivado Project: This automatically opens the Vivado project (.xpr) associated with the Hardware build configuration. In order for this feature to work, you must have previously completed the Hardware build so that a Vivado project exists for the build.
Opening the Vivado project launches the Vivado IDE and opens the implementation design checkpoint (DCP) file to edit the project, to let you manage the results of synthesis and implementation more directly. You can then use the results of this effort for generating the FPGA binary by selecting Import Design Checkpoint.
Import Design Checkpoint: Lets you specify a Vivado DCP file to use as the basis for the Hardware build, and for generating the FPGA binary.
Import Vivado Settings: Lets you specify a configuration file used by the Vivado tools, as described in Vitis Compiler Configuration File, for use during the linking process.

Using the Vivado IDE in standalone mode enables the exploration of various synthesis and implementation options for further optimizing the kernel for performance and area. There are additional options available to let you interact with the FPGA build process. See Managing Vivado Synthesis and Implementation Results for more information.

IMPORTANT: The optimization switches applied in the standalone project are not automatically incorporated back into the Vitis IDE build configurations. You need to ensure that the various synthesis and implementation properties are specified for the build using the v++ --config file options. Fore more information, refer to Vitis Compiler Command.