Working with Application Projects

Building Projects

The first step in developing a software application is to create a board support package to be used by the application. Then, you can create an application project.

When you build an executable for this application, Vitis automatically performs the following actions. Configuration options can also be provided for these steps.

  1. The Vitis software platform builds the board support package. This is sometimes called a platform.
  2. The Vitis software platform compiles the application software using a platform-specific gcc/g++ compiler.
  3. The object files from the application and the board support package are linked together to form the final executable. This step is performed by a linker which takes as input a set of object files and a linker script that specifies where object files should be placed in memory.

The following sections provide an overview of concepts involved in building applications.

Build Configurations

Software developers typically build different versions of executables, with different settings used to build those executables. For example, an application that is built for debugging uses a certain set of options (such as compiler flags and macro definitions), while the same application is built with a different set of options for eventual release to customers. The Vitis software platform makes it easier to maintain these different profiles using the concept of build configurations.

A build configuration is a named collection of build tools options. The set of options in a given build configuration causes the build tools to generate a final binary with specific characteristics. When the wizard completes its process, it generates launch configurations with names that follow the pattern <projectname>, where <projectname> represents the name of the project.

Each build configuration can customize:

  • Compiler settings: debug and optimization levels
  • Macros passed for compilation
  • Linker settings

By default, the Vitis software platform provides two build configurations, as listed in the following table:

Table 1. Build Configurations
Configuration Type Compiler Flags
Debug -O0 -g
Release -O2

Changing the Build Configuration

Use the Tool Settings properties view to customize the tools and tool options used in your build configuration. Follow these steps to change build settings:

  1. Select the project for which you want to modify the build settings in the Project Explorer view.
  2. Select Project > Properties. The Properties for <project> view appears. The left panel of the view has a properties list. This list shows the build properties that apply to the current project.
  3. Expand the C/C++ Build property.
  4. Select Settings.
  5. Use the Configuration list to select the configuration that needs to be modified.
  6. Click the Tool Settings view.
  7. Select the tool and change the settings as per your requirement.
  8. Click Apply to save the settings.
  9. When you finish updating the tools and their settings, click OK to save and close the Properties for <project> view.

Adding Symbols or Definitions

Definitions and symbols are tokenized and processed as if they have appeared during a preprocessor translation phase in a #define directive. You can add or remove symbols in the Vitis IDE with the following steps:
  1. Right-click your application project and select C/C++ Build Settings. Alternatively, select Properties and navigate to C/C++ Build > Settings.
  2. Under gcc compiler, select Symbols.
  3. Click the Add... () button to add symbols, or the Delete () button to remove existing symbols.

Adding Libraries and Library Paths

You can add libraries and library paths for Application projects. If you have a custom library to link against, you should specify the library path and the library name to the linker.

To set properties for your Application project:

  1. Right-click your Application project and select C/C++ Build Settings. Alternatively, select Properties and navigate to C/C++ Build > Settings.
  2. Expand the target linker section and select the libraries to which you want to add the custom library path and library name.

Specifying the Linker Options

You can specify the linker options for Application projects. Any other linker flags not covered in the Tool Settings can be specified here.

To set properties for your project:

  1. Right-click your managed make project and select C/C++ Build Settings. Alternatively, select Properties and navigate to C/C++ Build > Settings.
  2. Under the Tool Settings view, expand the target linker section.
  3. Select Miscellaneous.
  4. Specify linker options in the Linker Flags field by clicking the Add button. Options can be deleted using the Delete button, or modified using the Edit button.

Specifying Debug and Optimization Compiler Flags

Based on the build configuration selected, the Vitis software platform assigns a default optimization level and debug flags for compilation. You can change the default value for your project.

To set properties for your project:

  1. Right-click your managed make project.
  2. Select Properties. Alternatively, to set properties for a specific source file in your project, right-click a source file within your standard make project and select Properties to open the properties page.
  3. Expand the list under C/C++ Build.
  4. Click on Settings.
  5. Under the Tool Settings view, expand the gcc compiler list.
  6. Select Optimization to change the optimization level and Debugging to change the debugging level.

Specifying Miscellaneous Compiler Flags

You can specify any other compiler flags not covered in the Tool Settings for program compilation.

To set properties for your project:

  1. Right-click your managed make project and select Properties. Alternatively, to set properties for a specific source file in your project, right-click a source file within your standard make project and select Properties.
  2. Click C/C++ Build to expand the list and click on Settings.
  3. In the Tool Settings view, expand the gcc compiler list.
  4. Select Miscellaneous.
  5. In the Other flags field, specify compiler flags.

Restoring Build Configuration

Follow these steps to restore the build properties to have a factory-default configuration, or to revert to a last-known working build configuration:

  1. Select the project for which you want to modify the build settings in the Project Explorer view.
  2. Select Project > Properties. The Properties for <project> view appears. The left panel of the view has a properties list. This list shows the build properties that apply to the current project.
  3. Click the Restore Defaults button.
  4. When you finish restoring the build settings, click OK to save and close the Properties for <project> view.

Makefiles

Compilation of source files into object files is controlled using Makefiles. With the Vitis software platform, there are two possible options for Makefiles:

Managed Make
For managed make projects, the Vitis software platform automatically creates Makefiles. Makefiles created by the Vitis software platform typically compile the sources into object files, and finally link the different object files into an executable. In most cases, managed make eliminates the job of writing Makefiles. This is the suggested option.
Standard Make
If you want ultimate control over the compilation process, use standard make projects. In this case, you must manually write a Makefile with steps to compile and link an application. Using the standard make flow hides a number of dependencies from the Vitis software platform. You must follow manual steps for other tasks such as debugging or running the application from within the Vitis software platform. Therefore, the standard make flow is not recommended for general use.

Debugging Projects

The debugger in the Vitis software platform enables you to see what is happening to a program while it executes. You can set breakpoints or watchpoints to stop the processor, step through program execution, view the program variables and stack, and view the contents of the memory in the system.

The debugger supports debugging through Xilinx System Debugger and GNU Debugger (GDB). Xilinx System Debugger is derived from open-source tools and is integrated with the Vitis software platform.

Hardware Debug Target

The Vitis software platform supports debugging of a program on a processor running on an FPGA or a Zynq-7000 SoC device. All processor architectures (MicroBlaze and Arm® Cortex A9 processors) are supported. The Vitis software platform communicates to the processor on the FPGA or Zynq-7000 SoC device.

Before you debug the processor on the FPGA, configure the FPGA with the appropriate system bitstream.

The debug logic for each processor enables program debugging by controlling the processor execution. The debug logic on soft MicroBlaze processor cores is configurable and can be enabled or disabled by the hardware designer when building the embedded hardware. Enabling the debug logic on MicroBlaze processors provides advanced debugging capabilities such as hardware breakpoints, read/write memory watchpoints, safe-mode debugging, and more visibility into MicroBlaze processors. This is the recommended method for debugging MicroBlaze software.

Working with GDB

This topic describes how to use GDB to debug bare-metal applications.

To debug bare-metal applications:

  1. Create a sample Hello World project.
  2. Select the application and click Run > Debug As > Single Application Debug (GDB). The Debug Configuration view opens with the Main view selected.

  3. By default, the GDB shipped within the Vitis software platform is used with the default port, but you can specify the GDB and the port in the Debugger view in Debug Configurations.
    Note: Default ports used by the GDB server for different architectures are as follows:
    • Arm: 3000
    • Arm: AArch64
    • MicroBlaze: 3002
  4. Click the Debug button to start debugging the application.