Creating a Vitis IDE Project

In the Vitis™ IDE, you can create a new application project, or platform development project. The following section shows you how to set up a workspace, create a new Vitis IDE project, and use key features of the IDE.

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 Getting Started with Vitis.
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.
Note: If you selected Data Center accelerator card as your project platform in Step 2, the following page is not displayed and you can skip to Step 6.
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 from the System Project Settings in the Project Editor window.
Click Next to open the Templates page letting you select an application acceleration template for your new project.

Select an Empty Application (XRT Native API) to create a blank project to import XRT API source files into as described in Host Programming, and build the project from scratch. Also, 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 in the IDE.
TIP: The Vitis IDE opens in the Design perspective as described in Understanding the Vitis IDE. Review this information if you are unfamiliar with the display.
When a new application acceleration project is created in the Vitis IDE, it includes a top-level system project, and nested within an application project for the host-code, a hardware kernels project for compiling kernel objects, and a hw_link project that is used for linking hardware kernels to the target platform and to each other. These projects are displayed in the Explorer view as shown in the following figure.

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 page present on both New Application and New Platform wizards.

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

Add (): 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 (): 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.

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 Design perspective shown in the following figure.

Figure 2: 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

A project consists of many different source files, including C/C++ files and headers for the Host Programming, C/C++ Kernels, compiled Xilinx object (XO) files containing RTL kernels as discussed in RTL Kernels, or HLS kernels as described in Compiling Kernels with Vitis HLS. You can add these source files as needed to support your application.

Each individual project within a system project requires its own source and data files. The host application code (host.cpp) is added to the ./src folder in the processor application project, and the kernel code (kernel.cpp), or the compiled kernel.xo files are added to the ./src folder of the kernel application project. You can add these files using the Import Sources command as explained in the next section.

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 the 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.

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 a top-level system project, host processor project, hardware kernel project, and hw_link project. Both the host and kernel projects contain source code in the src folder, as imported or created in the project. Any of these projects can be opened in the Project Editor view, shown in the following figure, which gives a top-level view of the project and its various build configurations.

Depending on the type of project you are viewing, system project, host, kernel, or link, the Project Editor provides the following details:

General information about the project name
Target platform
Active build configuration
Several configuration options related to the selected project

These include boot files for system project, debug options for the host or kernel projects, and a menu to select the report level of the hardware kernel project as discussed in Controlling Report Generation.

The bottom portion of the Project Editor view displays Application Projects contained in the top-level system project, as shown in the figure above, or displays the Hardware Functions that will be compiled in a hardware kernel project, or assigned to the binary container in the hw_link project to be built into the xclbin.

To specify a function to be compiled in a hardware kernel project, click the Add Hardware Function () button in the upper right of the Hardware Functions pane. This opens the Add Hardware Functions dialog box displaying a list of functions defined in the source code of the current project, as shown below.

Figure 4: Adding Hardware Functions to a Binary Container

Select a function from the list to specify the hardware function, and click OK. The selected function becomes the target of the build process for the hardware kernel project and is also added to the device binary in the hw_link project.

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 it in the default Vitis IDE perspective. The following figure shows an example Assistant view and its tree structure.

The objects displayed in the Assistant view hierarchy include the top-level system project, host project, hardware kernel projects, and the hw_link project. For each of these projects the different build configurations are also displayed: the software emulation and hardware emulation build configurations, and the hardware build configuration. The build configurations define the build target as described in Build Targets, and specify options for the compilation and linking process.

TIP: The status of build configurations can be quickly determined from the icons displayed in the figure above:

Emulation-SW builds are complete as indicated by the green check box
Emulation-HW builds need to be updated for the hardware kernel and hw_link projects, as indicated by the yellow exclamation (!)
Hardware builds are not built

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.

Within the hierarchy of these build configuration is the binary container (or .xclbin), the hardware function or functions, 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 this dialog box to specify the number of compute units for each kernel, assign compute units to SLRs, and assign kernel ports to global memory.

After a specific build configuration has been built, launch configurations become available for the project. There are two types of launch configurations:

Run configurations specify the profile used for running the compiled and linked application; it defines the environment and options for running the host application and kernel code. Use the Run command () on the toolbar menu to access run configurations. This opens the Vitis Run and Debug Configuration Settings dialog box, where you can configure the run before launching it.
Debug configurations specify the profile for debugging the application. It launches the environment needed to interactively debug both the host and kernel code. You can access debug configurations through the Debug command () on the toolbar menu. Refer to Vitis IDE Debug Flow for more information.

Within the Assistant view, the View menu includes options that affect what the Assistant view displays, or affect how the Assistant view interacts with other views. Open the View menu by left-clicking the menu command 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. To change the active configuration, select Active build configuration in 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. The different reports are grouped into Compile Summary, Link Summary, Package Summary, and Run Summary which can be viewed in the Vitis analyzer tool as described in Using the Vitis Analyzer. You can right-click one of these summary reports in the Assistant view and select Open in Vitis Analyzer as shown below.

Output Directories from the Vitis IDE

The following example shows the directory structure automatically generated by the Vitis IDE for a sample application acceleration project which includes:

Top-level system project
Host application project
Hardware kernel compilation project
Hardware kernel linking project

The default directory structure of the Vitis IDE is similar but not identical to that created by the command-line flow.

### Vitis IDE Directory Structure
workspace
	>pathwayKernel - a hardware kernel project in the Vitis application acceleration development flow. The top-level project can contain multiple kernel projects. 
		>Emulation-HW - the hardware emulation build folder. 
			>build
				> The build folder for the compiled hardware kernel (.XO)
			>guidance.html
			>guidance.json
			>guidance.pb
			>makefile
			>mmult-compile.cfg
			>pathwayKernel_Emulation-HW.build.ui.log
			>xcd.log
		>Emulation-SW
			>Files related to the Software Emulation Build
		>pathwayKernel.prj - Hardware kernel project 
		>src - Hardware kernel source files
			>kernel.cpp
	>pathwayTest - The host application project
		>Emulation-HW
			>au250_image.jpg
			>bd_d216_ddr4_mem00_0_microblaze_mcs_bd.tcl
			>bd_d216_ddr4_mem00_0_microblaze_mcs.hwh
			>bd_d216_ddr4_mem01_0_microblaze_mcs_bd.tcl
			>bd_d216_ddr4_mem01_0_microblaze_mcs.hwh
			>bd_d216_ddr4_mem02_0_microblaze_mcs_bd.tcl
			>bd_d216_ddr4_mem02_0_microblaze_mcs.hwh
			>bd_d216_ddr4_mem03_0_microblaze_mcs_bd.tcl
			>bd_d216_ddr4_mem03_0_microblaze_mcs.hwh
			>bd_d216_interconnect_DDR4_MEM00_0_bd.tcl
			>bd_d216_interconnect_DDR4_MEM00_0.hwh
			>bd_d216_interconnect_DDR4_MEM01_0_bd.tcl
			>bd_d216_interconnect_DDR4_MEM01_0.hwh
			>bd_d216_interconnect_DDR4_MEM02_0_bd.tcl
			>bd_d216_interconnect_DDR4_MEM02_0.hwh
			>bd_d216_interconnect_DDR4_MEM03_0_bd.tcl
			>bd_d216_interconnect_DDR4_MEM03_0.hwh
			>bd_d216_interconnect_PLRAM_MEM00_0_bd.tcl
			>bd_d216_interconnect_PLRAM_MEM00_0.hwh
			>bd_d216_interconnect_PLRAM_MEM01_0_bd.tcl
			>bd_d216_interconnect_PLRAM_MEM01_0.hwh
			>bd_d216_interconnect_PLRAM_MEM02_0_bd.tcl
			>bd_d216_interconnect_PLRAM_MEM02_0.hwh
			>bd_d216_interconnect_PLRAM_MEM03_0_bd.tcl
			>bd_d216_interconnect_PLRAM_MEM03_0.hwh
			>bd_d216_interconnect_S00_AXI_0_bd.tcl
			>bd_d216_interconnect_S00_AXI_0.hwh
			>bd_d216_interconnect_S01_AXI_0_bd.tcl
			>bd_d216_interconnect_S01_AXI_0.hwh
			>bd_d216_interconnect_S02_AXI_0_bd.tcl
			>bd_d216_interconnect_S02_AXI_0.hwh
			>bd_d216_interconnect_S03_AXI_0_bd.tcl
			>bd_d216_interconnect_S03_AXI_0.hwh
			>binary_container_1.xclbin
			>board
				>board files for the selected hardware platform
			>dsa.xml
			>emconfig.json
			>emu
				>dynamic_post_sys_link.tcl
				>dynamic_pre_sys_link.tcl
				>emu.bd
				>emu.bxml
				>emu.xml
				>hdl
					>emu_wrapper.v
				>ip
					>IP files from the selected platform
				>ipshared
					>
				>prop.json
				>sim
					>
				>synth
					>
			>emulation_debug.log
			>ext_metadata.json
			>firmware
				>xilinx_u250_xdma_201830_3.mcs
				>xilinx_u250_xdma_201830_3.prm
			>guidance.html
			>guidance.json
			>guidance.pb
			>launch_options.cfg
			>makeemconfig.mk
			>makefile
			>pathwayTest
			>pathwayTest_Emulation-HW.build.ui.log
			>pfm_dynamic_bd.tcl
			>pfm_dynamic_debug_bridge_xsdbm_0_bd.tcl
			>pfm_dynamic_debug_bridge_xsdbm_0.hwh
			>pfm_dynamic.hwh
			>pfm_dynamic_memory_subsystem_0_bd.tcl
			>pfm_dynamic_memory_subsystem_0.hwh
			>pfm_top_bd.tcl
			>pfm_top.hwh
			>pfm_top_jtag_fallback_0_bd.tcl
			>pfm_top_jtag_fallback_0.hwh
			>pfm_top_mgmt_debug_bridge_0_bd.tcl
			>pfm_top_mgmt_debug_bridge_0.hwh
			>pfm_top_mgmt_debug_hub_0_bd.tcl
			>pfm_top_mgmt_debug_hub_0.hwh
			>pfm_top_user_debug_bridge_0_bd.tcl
			>pfm_top_user_debug_bridge_0.hwh
			>pfm_top_user_debug_hub_0_bd.tcl
			>pfm_top_user_debug_hub_0.hwh
			>src
				>host.cpp
			>sysdef.xml
			>SystemDebugger_pathwayTest_system_pathwayTest
				>binary_container_1.xclbin.run_summary
				>guidance.html
				>guidance.json
				>guidance.pb
				>profile_guidance.json
				>profile_guidance.pb
				>profile_kernels.csv
				>opencl_summary.csv
				>profile_summary.xprf
				>timeline_kernels.csv
				>opencl_trace.csv
				>xilinx_u250_xdma_201830_3-0-binary_container_1.protoinst
				>xilinx_u250_xdma_201830_3-0-binary_container_1_simulate.log
				>xilinx_u250_xdma_201830_3-0-binary_container_1.wcfg
				>xilinx_u250_xdma_201830_3-0-binary_container_1.wdb
				>xilinx_u250_xdma_201830_3-0-binary_container_1_xsc_report.log
				>xrc.log
				>xrt.ini
			>SystemDebugger_pathwayTest_system_pathwayTest.launch.log
			>SystemDebugger_pathwayTest_system_pathwayTest.launch.ui.log
			>tcl_hooks
				>dynamic_postlink.tcl
				>dynamic_postopt.tcl
				>dynamic_prelink.tcl
				>xilinx_u250_xdma_201830_3_dynamic_impl.xdc
			>update_dsa.log
			>xilinx_u250_xdma_201830_3.hpfm
		>Emulation-SW
		>pathwayTest.prj
		>src
			>kernel.cpp
	>pathwayTest_system
		>binary_container_1.xclbin
		>binary_container_1.xclbin.package_summary
		>makefile
		>package.build
			>logs
			>package
				>system diagram and package project
			>reports
				>package
					>v++_package_binary_container_1_guidance.html
			>v++_package_binary_container_1_guidance.json
			>v++_package_binary_container_1_guidance.pb
		>package.cfg
		>pathwayTest_system_Emulation-HW.build.ui.log
		>v++_binary_container_1.log
		>xcd.log
		>xrc.log
	>pathwaytTest_system_hw_link
		>binary_container_1.build
			>link
				>activetask.json
				>int
					>address_map.xml
					>appendSection.rtd
					>behav_waveform
						>xsim
					>behav.xse
					>binary_container_1_build.rtd
					>binary_container_1.gpp_so.log
					>binary_container_1.rtd
					>binary_container_1.so
					>binary_container_1.xml
					>binary_container_1_xml.rtd
					>cf2sw_full.rtd
					>cf2sw.rtd
					>consolidated.cf
					>debug_ip_layout.rtd
					>dr.bd.tcl
					>kernel_info.dat
					>_kernel_inst_paths.dat
					>kernel_service.json
					>mmult
						>
					>_new_clk_freq
					>sdsl.dat
					>syslinkConfig.ini
					>systemDiagramModel.json
					>systemDiagramModelSlrBaseAddress.json
					>vplConfig.ini
					>vplsettings.json
					>xclbin_orig.1.xml
					>xclbin_orig.xml
					>xclbin_orig.xml.tmp
					>xo
						>ip_repo
						>mmult
							>cpu_sources
							>debug
							>kernel.xml
							>mmult.design.xml
				>link.spr
				>link.steps.log
				>run_link

				>sys_link

				>vivado

			>logs
				>link
			>reports
				>link
		>binary_container_1-link.cfg
		>binary_container_1.mdb
		>binary_container_1.xclbin
		>binary_container_1.xclbin.info
		>binary_container_1.xclbin.link_summary
		>binary_container_1.xclbin.sh
		>guidance.html
		>guidance.json
		>guidance.pb
		>makefile
		>pathwayTest_system_hw_link_Emulation-HW.build.ui.log
		>xcd.log