Migrating Command-line Projects to the Vitis Unifed IDE - 2024.1 English

This page describes the steps to use the Vitis Unified IDE to build and run user's command-line Makefile based designs for various projects such as AI Engine graph applications, heterogeneous system projects, Data Center acceleration, or embedded software flows.

This flow lets you configure the tool to build the components of your design using the available commands, Makefile, source files, and configuration files. It does not require a Makefile, but works well with one. You can also specify command-line tools and compilation commands as needed. Using the Vitis Unified IDE with the user-managed flow lets you import existing projects, report files, and view them in the context of the IDE. See the steps below for a run-down of the Flow.

1. Launch the Vitis Unified IDE tool and open the project folder as a workspace by selecting the Open Workspace command. The project folder can contain a Makefile, although a Makefile is not mandatory.

   The Vitis Components Explorer will report that the workspace has no recognizable components, and encourage you to create a component or to switch to Open Explorer View to work with Makefile projects.

   
   
   
2. Select the Open Explorer View from the Vitis Components Explorer.

   The Vitis Components Explorer view is replaced with the Explorer view to provide a view of the files and folders in the workspace without enhancement.

3. In the workspace folder, right-click and select the Edit Build Configurations command from the pop-up menu.

   A build.json file is added to the current workspace, and the Build Configurations editor is opened in the IDE.

4. In the Build Configurations editor, create a new build configuration by selecting the New Build Configuration command, or the + button in the toolbar menu.

   A new build configuration is created.

   • Specify a Build config name
   • Specify the Build command to be used. The build command can be taken from a Makefile in the folder. For example:

     make all TARGET=hw_emu PLATFORM=$PLATFORM_REPO_PATHS/xilinx_vck190_base_202320_1

     The build command can also be a command line command:

     v++ -c -t sw_emu --platform xilinx_u250_gen3x16_xdma_4_1_202210_1 --config ../src/u250.cfg -k vadd -I../src ../src/vadd.cpp -o sw_emu/vadd.xo

     Tip: You can expand the Build command field by selecting the double-headed arrow on the right of the UI. This will provide more space for editing and viewing the command text.
   • Specify a Clean command command, also taken from a Makefile:

     make clean TARGET=hw_emu

     or command-line:

     rm -rf sw_emu

   • Specify a Run directory where the build will occur. The current workspace is the default Run directory.
5. Create additional build configurations as needed for your project.
6. With the build configurations created, you can build components by right-clicking in the Explorer view and selecting the Build command.

   If you created multiple build configurations, the IDE will list the available configurations letting you select one. If there is only a single build configuration, the Vitis tool will run it.

   Important: Make sure the shell or terminal window from which the Vitis Unified IDE is launched is properly configured to run the specified build commands. Any environment variables required by a Makefile for example will also be required by the tool.
7. The component or system will build according to the build configuration commands. The output of the process will be reported to the Output view. If needed, you can open this view from the View > Output menu command.

After build the components of your design, you can run or debug them as needed in the IDE by creating a launch configuration for the component. Use the following steps to create and run or debug the components or system project.

1. Right-click in the workspace folder in the Explorer view and select the Edit Launch Configurations command from the popup menu.

   A launch.json file is added to the current workspace, and the Launch Configurations editor is opened in the IDE.

2. Select the New Launch Configuration command to define a launch configuration, or select the + button in the toolbar menu.
   The Create Launch Configuration dialog box is opened as shown in the following figure.
   
   
   Tip: The Vitis tool will indicate any problems with the specified build directory, for example if it cannot find a summary file generated by v++ during the build process. The warning could indicate that the component or system is not valid, or did not build properly, in which case the Vitis tool will not proceed.

   The Create Launch Configurations dialog box offers three configurations that can be run or debug.

   AI Engine Graph

   Select this option for any AI Engine graph application or template. The specified build directory is automatically populated with the available Work directories output by the v++ command, to enable x86simulator or aiesimulator.

   Click Submit to create the launch configuration for AI Engine application. In the launch configuration, specify preferences such as Pipeline View, Trace and Profiling. Select the Play command to run the component, or select the Debug button for debug.

   Accelerated Application

   Select this option for a System project using an extensible platform for embedded system designs or Data Center application acceleration. The specified build directory is automatically mapped with the build target, platform and binary container info.

   Launch configuration with the few sections are created for the app. Provide the necessary information, and run/debug it.

   Embedded Application

   There are four options for the Embedded Application, as described below. Refer to Vitis Embedded Software Development User Guide (UG1400) for more information.

   • Attach to Running Target: To debug the already running target, select this option. Provide the target connection and start running or debugging the application.
   • Baremetal: If you have an XSA and want to create a run configuration, map the XSA and click Submit. Launch configuration with the few sections are created for the app. Provide the target connection, fsbl and other necessary information and run or debug it.
   • Attach to Running Process on Linux Target: To debug a Linux application on an already running Linux target, select this option and click submit. Launch configuration with the few sections are created for the app. Provide the target connection and host executable information, and run or debug it.
   • Linux Application with ELF: If a Linux application has to be run/debugged, select this option and provide the ELF. Launch configuration with the few sections are created for the app. Provide the necessary information and run or debug it.

3. Configure the Launch Configuration as required for the component or system you are trying to run or debug. Refer to Launch Configurations for additional details.
4. After creating the launch configuration, you can run or debug the configuration by right-clicking in the Explorer view and selecting either Run or Debug commands from the popup menu.
5. If the launch configuration is for an embedded system running under QEMU, you must start the emulator before launching the configuration. You can do this by selecting Start Emulator from the popup menu. This will open the Start Emulator dialog box to review and configure if needed, and click Start. Once the emulator is fully up and running, use the launch configuration to run the application or debug it.