Creating a Vitis IDE Project

Launch a Vitis IDE Workspace

Launch the Vitis IDE directly from the following command line.
```
$vitis
```
IMPORTANT: When opening a new target platform, to enter a Vitis core development kit command, ensure that you set it up as described in Setting up the Vitis Environment.
The Vitis IDE opens.
Select a workspace as shown in the following figure.

The workspace is the folder that stores your projects, source files, and results while working in the IDE. You can define separate workspaces for each project, or have a single workspace with multiple projects and types. The following instructions show you how to define a workspace for a Vitis IDE project.
Click Browse to navigate to and specify the workspace, or type the appropriate path in the Workspace field.
Optionally enable Use this as the default and do not ask again to set the specified workspace as your default choice and eliminate this dialog box in subsequent uses of the IDE.
Note: To restore the dialog box, navigate to Window > Preference > Additional > General > Startup and Shutdown > Workspaces, and select Prompt for workspace on startup
Click Launch.
TIP: To change the current workspace from within the Vitis IDE, select File > Switch Workspace.

You have now created a workspace and can populate it with projects.

Create an Application Project

TIP: Example designs are provided with the Vitis core development kit installation and also on the Xilinx Vitis Examples GitHub repository. For more information, see Getting Started with Examples.

After launching the Vitis IDE, you can create a new Application Project.

Select File > New > Vitis Application Project, or if this is the first time the Vitis IDE has been launched, you can select Create Application Project on the Welcome screen.

The New Application Project wizard opens displaying a Welcome page that explains the process for new users. You can disable this from being shown again by enabling Skip welcome page next time.
Click Next to open the Platform page of the New Application Project wizard to specify a target platform.
A target platform is composed of a base hardware design and the meta-data used in attaching accelerators to declared interfaces. Use the Select a platform from repository tab to choose a platform for your project. You can enter a value in the Find field to limit the choices displayed to make it easier to locate the required platform. The bottom portion displays information related to the currently selected platform, as shown in the following figure.

Note: For platforms supported by a specific release refer to the Release Notes in the Introduction to the Vitis Unified Software Platform.
You can also add custom defined or third-party platforms into a repository. For more information, see Managing Platforms and Repositories.
In the Application Project Details page, specify the name in the Application project name field, as shown in the following figure.

By default, the tool creates a new system project for your application project. However, you can also add your application project to an existing system project, if one exists. The system project is a top-level manager for different projects that combine to create the system view.
Click Next to proceed.
If you select an Embedded Acceleration target platform on the Platform page, as displayed in the Flow column, the Domain page opens next as shown in the following figure.

Select a Domain from the list of existing domains on the platform, and Domain details are populated from your selection. The Domain defines the processor and operating used for running the host program on the target platform. You must also set the following Application Settings for the project to build correctly on the embedded platform:

Sysroot path

The sysroot is part of the platform where the basic system root file structure is defined. The Sysroot path lets you define a new sysroot for your application.

Root FS

Specify the location of the root file system.

Kernel Image

Specify the location of the operating system kernel.

These option can be changed after the project is created in C/C++ Build Settings > Build Variables.
Click Next to open the Templates page letting you select an application template for your new project.

You can select an Empty Application to create a blank project that you can import files and build from scratch. Also, you can use one of the provided template projects as a foundation for your new application project to help start your project, or help you learn the tool.
TIP: Click the Vitis IDE Examples button, or the Vitis IDE Libraries button to install additional examples as discussed in Getting Started with Examples.
Click Finish to close the New Application Project wizard, and open the project.

Managing Platforms and Repositories

You can manage the platforms that are available for use in Vitis IDE projects, from Xilinx > Add Custom Platform in the main menu of an open project, or from the Platform dialog box. This lets you add a new platform, or a new platform repository.

From the Platform dialog box, manage the available platforms and platform repositories using one of the following options:

Add Custom Platform (): Add your own platform to the list of available platforms. To add a new platform, navigate to the top-level directory of the custom platform, select it, and click OK. The custom platform is immediately available for selection from the list of available platforms.
Manage Platform Repositories (): Add or remove standard and custom platforms. If a custom platform is added, the path to the new platform is automatically added to the repositories. When a platform is removed from the list of repositories, it no longer displays in the list of available platforms.
Add Devices/Platforms (): Manage the Xilinx devices and platforms installed as part of the standard software installation. If a device or platform was not selected during the installation process, you can add it later using this option. This launches the Vitis Installer so you can select extra content to install. To directly add custom platforms to the tool, select Help > Add Devices/Platforms.

Understanding the Vitis IDE

When you open a project in the Vitis IDE, the workspace is arranged in a series of different views and editors, also known as a perspective in the Eclipse-based IDE. The tool opens with the default perspective shown in the following figure.

Figure 1: Vitis IDE – Default Perspective

Some key views and editors in the default perspective include:

Explorer view: Displays a file-oriented tree view of the project folders and their associated source files, plus the build files, and reports generated by the tool. You can use this to explore your project file hierarchy.
Assistant view: Provides a central location to view and manage the projects of the workspace, and the build and run configurations of the project. You can interact with the various project settings and reports of the different configurations. From this view, you can build and run your Vitis IDE application projects, and launch the Vitis analyzer to view reports and performance data as explained in Using the Vitis Analyzer.
Project Editor view: Displays the current project, the target platform, the active build configuration, and specified hardware functions; allows you to directly edit project settings.
Console view: Presents multiple views including the command console, design guidance, project properties, logs, and terminal views.

The Vitis IDE includes several predefined perspectives, such as the Vitis IDE perspective, the Debug perspective, and the Performance Analysis perspective. To quickly switch between perspectives, click the perspective name in the upper right of the Vitis IDE.

You can arrange views to suit your needs by dragging and dropping them into new locations in the IDE, and the arrangement of views is saved in the current perspective. You can close windows by selecting the Close (X) button on the View tab. You can open new windows by using the Window > Show View command and selecting a specific view.

To restore a perspective to the default arrangement of views, make the perspective active and select Window > Reset Perspective.

To open different perspectives, select Window > Open Perspective.

Adding Sources

The project consists of many different source files, including C/C++ files and headers, OpenCL files and headers, compiled Xilinx object files (.xo) containing RTL kernels as discussed in RTL Kernels, or HLS kernels as described in Compiling Kernels with Vitis HLS.

Add Source Files

With the project open in the Vitis IDE, to add source files, right-click the src folder in the Project Explorer, and click Import Sources.
This displays the Import Sources dialog box shown in the following figure.
In the dialog box, for the From directory field, click the Browse button to select the directory from which you will import sources.
In the Into folder field, make sure the folder specified is the src folder of your application project.
Select the desired source files by enabling the check box next to the file name, and click Finish.
IMPORTANT: When you import source files into a workspace, it copies the file into the workspace. Any changes to the files are lost if you delete the workspace.

After adding source files to your project, you are ready to begin configuring, building, and running the application. To open a source file in the built-in text editor, expand the src folder in the Project Explorer and double-click on a specific file.

Create and Edit New Source Files

You can also create and edit new source files directly in the Vitis IDE.

From the open project, right-click the src folder and select New > File.
The New File dialog box is displayed as shown in the following figure.
Select the folder in which to create the new file and enter a file name.
Click Finish to add the file to the project.

After adding source files to your project, you are ready to begin configuring, building, and running the application. To open a source file in the built-in text editor, expand the src folder in the Project Explorer and double-click on a specific file.

Working in the Project Editor View

Building the system requires compiling and linking both the host program and the FPGA binary (xclbin). Your defined application project includes both the host and kernel code in the src folder, as imported or created in the project. The Project Editor view, shown in the following figure, gives a top-level view of the project, and its various build configurations. It provides:

General information about the project name
Target platform
Active build configuration
Several configuration options related to that build configuration
These include debug options to enable debug features of the host program or kernel code, and a menu to select the report level for the build as discussed in Controlling Report Generation.

The bottom portion of the Editor view displays the Hardware Functions window, which shows the kernels that are assigned to the binary container to be built into the xclbin. To add a kernel to the binary container, click the Add Hardware Function () button in the upper right of the window. It displays a list of kernels defined in the project. Select the kernel from the Add Hardware Functions dialog box as shown in the following figure.

Figure 3: Adding Hardware Functions to a Binary Container

After adding the kernel, in the Hardware Functions window, enter a value under Compute Units to instantiate multiple instances of the kernel as described in Creating Multiple Instances of a Kernel.

Working in the Assistant View

The Assistant view provides a project tree to manage build configurations, run configurations, and set the attributes of these configurations. It is a companion view to the Explorer view and displays directly below the view in the default Vitis IDE perspective. The following figure shows an example Assistant view and its tree structure.

Figure 4: Assistant View Tree Structure Example

The objects displayed in the Assistant view hierarchy include the top-level system project, the application project, the software and hardware emulation build configurations, and the system hardware build configuration.

The build configurations define the build target as described in Build Targets, and specify options for the build process. When you select a build configuration, such as Emulation-HW build and click the Settings icon (), the Vitis Build Configuration Settings dialog box opens. You will use this Settings dialog box to configure the build process for the specific emulation or hardware target.

TIP: You can also open the Settings dialog box by double-clicking the configuration object.

Within the hierarchy of each build configuration is the binary container (or .xclbin), the hardware function or functions in the binary container, the run configuration, and any reports or summaries generated by the build or run process. When you select the hardware function for a specific build configuration and click the Settings icon, the Vitis Hardware Function Settings dialog box is displayed. You will use theHardware Function Settings dialog box to specify the number of compute units for each kernel, assign compute units to SLRs, and assign kernel ports to global memory.

The run configuration is the profile used for running the compiled and linked application; it defines the environment and options for running the application. Selecting a build configuration and using the right-click menu to navigate to Run > Run Configurations, opens the Vitis Run Configuration Settings dialog box, where you can configure the run.

Within the Assistant view, the View menu includes options that affect what the Assistant view displays, which does not affect project data. Open the View menu by left-clicking the downward pointing arrow to display the following options:

Show Active Build Configurations Only: When enabled, the Assistant view will only show the active build configuration for each project. This option can be useful to reduce the clutter in the Assistant view. Select Active build configuration in the Application Project Settings tab of the Project Editor view.

Link with Console: When enabled, the build console in the Console view switches automatically to match the currently selected build configuration in the Assistant view. If not enabled, the build console does not automatically change to match the Assistant view.

Link with Guidance: When enabled, the Guidance tab of the Console view automatically switches to match the current selection in the Assistant view.

For each of the build configurations, reports are generated during the build and run process, and are displayed in the Assistant view, as shown below. You can right-click a report, and select Open in Vitis Analyzer to review the results as explained in Using the Vitis Analyzer.