add_bsp_based_executable

Adds an embedded executable that is based on a previously loaded BSP.

Syntax

add_bsp_based_executable(
    NAME <executable name>
    SOURCES <sources>

    LINKER_SCRIPT <relative path>
    BSP_ALIAS <alias>
    TESTFW_ALIAS <alias>
    MEMORY_LIST_FILE <file>
    ENTRY_POINT <entry point>
    EXCLUDED_PLATFORMS <platform list>

    [GENERATE_BIN]
    [GENERATE_HEX]
    [GENERATE_MAP]
    [PREPROCESS_LINKER_SCRIPT]
    [BUILD_UNIT_TESTS]
    [OUTPUT_RELOCATION_RECORDS]
)

Overview

The add_bsp_based_executable statement creates an embedded executable based on a BSP loaded with the find_bsp command. It is similar to the regular add_executable statement in CMake, but will automatically manage BSP references, linker script preprocessing, map files, differences between GCC, IAR and Keil, as many other nuances specific to embedded projects.

Parameters

NAME
Specifies the name of the executable. Can include an extension if desired.

SOURCES
Specifies the list of source files separated with spaces. The paths can be absolute, or relative to the current source directory. Use the ${BSP_ROOT} syntax to specify paths inside the BSP directory.

LINKER_SCRIPT
Optional. Specifies the linker script used to link the executable. If omitted, VisualGDB will automatically use the default linker script included in the BSP.

BSP_ALIAS
Optional. If the project loads multiple BSPs, this parameter allows selecting a specific BSP instance.

TESTFW_ALIAS
Optional. If BUILD_UNIT_TESTS is specified and the project loads multiple test frameworks, this parameter allows selecting a specific test framework instance.

MEMORY_LIST_FILE
Optional. Specifies the file containing the list of additional memories used by the project. Used by VisualGDB to generate various auxiliary files and does not affect build directly.

ENTRY_POINT
Optional. Allows overriding the entry point in a compiler-invariant way. Works with the GCC, IAR and Keil compilers.

EXCLUDED_PLATFORMS
Optional. Can specify a list of project platforms, separated with spaces, where the executable will not be built.

GENERATE_BIN
If specified, building the project will generate a .bin file. This option works with the GCC, IAR and Keil compilers.

GENERATE_HEX
If specified, building the project will generate a .hex file. This option works with the GCC, IAR and Keil compilers.

GENERATE_MAP
If specified, building the project will generate a .map file. This option works with the GCC, IAR and Keil compilers.

PREPROCESS_LINKER_SCRIPT
If specified, VisualGDB will preprocess the linker script specified via the LINKER_SCRIPT parameter and will pass the preprocessing output to the linker.

BUILD_UNIT_TESTS
If specified, the executable will reference a test framework loaded with find_test_framework.

OUTPUT_RELOCATION_RECORDS
Enables the generation of relocation records in the output file. This option is required for tracking references between symbols, or for running dynamic analysis and profiling. It does not affect the memory footprint.

Remarks

You can configure most of the add_bsp_based_executable parameters by opening the Properties window for the executable node in Solution Explorer. In most cases there is no need to edit them manually.

Examples

The following example loads the STM32 BSP into the project and creates an executable based on it:

find_bsp(ID com.sysprogs.arm.stm32
         VERSION 2020.10
         MCU STM32F407VG)
add_bsp_based_executable(NAME Application1
                         SOURCES Application1.cpp)

The syntax below references another instance of the STM32 BSP, targeting the STM32F746NG device, and creates another executable using it:

find_bsp(ID com.sysprogs.arm.stm32
         VERSION 2020.10
         MCU STM32F746NG
         ALIAS AuxiliaryBSP)

add_bsp_based_executable(NAME Application2
                         SOURCES Application2.cpp
                         BSP_ALIAS AuxiliaryBSP)

See also

Statements for Creating Targets, add_bsp_based_library