Embedded Studio project file format

From SEGGER Wiki
Revision as of 10:22, 22 October 2020 by Nino (talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

This article will explain the generic Embedded Studio project format.

Note: The following project format description is only meant as a reference. We do not recommend manual modifications of Embedded Studio Project Files. For modifications we recommend to always use the Embedded Studio GUI. Otherwise the project file may be

Format description

Project Layout

Project files are essentially solution files, as such could include more than one project.

The basic layout is:

<!DOCTYPE CrossStudio_Project_File>
<solution Name="Project_Example" target="8" version="2">
  <project Name="Project Name">
  </project>
</solution>

A project can contain

1. Files:

  <file file_name="RelativePathToFile"/> or <file file_name="RelativePathToFile"></file>

2. "Virtual" Folders

  <folder Name="Folder Name"></folder>

3. Dynamic Folders

  <folder Name="Folder Name" exclude="Exclude Filter" filter="Include Filter" path="RelativePathToFolder" recurse="Yes|No" />

Virtual Folders can contain more virtual and dynamic folders, and files.

So a project setup might be:

<!DOCTYPE CrossStudio_Project_File>
<solution Name="Solution Name" target="8" version="2">
  <project Name="Project Name">
    <folder Name="Src" filter="*.c;*.cpp;*.h;*.s" path="Src" recurse="Yes"/>
    <folder Name="Doc>
      <file file_name="README.txt"/>
      <file file_name="Doc/index.html"/>
    </folder>
  </project>
</solution>

Project Options

In ES Project Options can be set on every level, per build configuration. Options are inherited from upper levels and configurations.

The basic tag is:

  <configuration name="ConfigurationName" [option="value"]/>

Regular projects define the build configurations "Debug" and "Release" and set standard options on solution level;

<solution Name="Solution Name" target="8" version="2">
  <configuration Name="Debug" c_preprocessor_definitions="DEBUG" gcc_debugging_level="Level 3" gcc_optimization_level="None" />
  <configuration Name="Release" c_preprocessor_definitions="NDEBUG" gcc_debugging_level="Level 2" gcc_omit_frame_pointer="Yes" gcc_optimization_level="Level 2 balanced" />
  [...]
</solution>

The configuration of the project includes the options to configure the device, build options, debugging options, ... There is a configuration "Common", which defines the defaults to be inherited by the other build configurations, so that the options need to be set only once:

<solution Name="Solution Name" target="8" version="2">
  [...]
  <project Name="Project Name">
    <configuration Name="Common"
      Name="Common"
      arm_architecture="v7M"
      arm_compiler_variant="SEGGER"
      arm_core_type="Cortex-M3"
      arm_endian="Little"
      arm_fpu_type=""
      arm_linker_heap_size="1024"
      arm_linker_process_stack_size="0"
      arm_linker_stack_size="1024"
      arm_linker_variant="SEGGER"
      arm_rtl_variant="SEGGER"
      arm_simulator_memory_simulation_parameter="RX 00000000,00100000,FFFFFFFF;RWX 10000000,00020000,CDCDCDCD"
      arm_target_device_name="YourTargetDeviceName"
      arm_target_interface_type="SWD"
      debug_target_connection="J-Link"
      LIBRARY_IO_TYPE="RTT"
      link_linker_script_file="Setup/SEGGER_Flash.icf"
      link_symbol_definitions="getchar=getchar_rtt;putchar=putchar_rtt;gets=gets_rtt;puts=puts_rtt;printf=printf_rtt;scanf=scanf_rtt;vprintf=vprintf_rtt;vscanf=vscanf_rtt"
      linker_output_format="hex"
      linker_section_placements_segments="FLASH1 RX 0x00000000 0x00100000;RAM1 RWX 0x10000000 0x00020000"
      project_directory=""
      project_type="Executable" />
  </project>
  [...]
/solution>

If you would want to for example change the optimization level of a file in Release from "Level 2 balanced" (set on solution level) to "Level 2 for size", it would look like this:

<solution Name="Solution Name" target="8" version="2">
  [...]
  <project Name="Project Name">
    [...]
    <folder Name="Src">
      <file file_name="Src/main.c">
        <configuration Name="Release" gcc_optimization_level="Level 2 for size"/>
      </file>
    [...]
  </project>
  [...]
</solution>

Overriding project properties

With Embedded Studio you can set properties for solutions, projects, folders and files to configure the build system and debugging behavior. Property values can be set in the properties window, which is accessible as a docked window via View → Properties Window, which shows the property values for the currently selected file in the project explorer or via right-click on a project, folder or file in the project explorer to show the property values of this element.

Properties can be set for all build configurations with the private configuration "Common" and separately for each build configuration. The properties are grouped by their specific purpose. The properties window allows searching for specific properties. Not all properties might be available for all kind of elements and project types. Properties are inherited from parent elements. A project inherits from the Solution, a folder from the project, a sub-folder from its parent folder and files from folders.

Overriding properties

Unique properties have one value. For each element the inherited unique property values can be overridden by changing it for this element.

MySolution      Exclude: No  - Will be built
  MyProject     Exclude: No  - Will be built
    MyFolder    Exclude: Yes - Will not be built
      MyFile.c  Exclude: --  - Will not be built
      MyFile1.c Exclude: No  - Will be built
    MyFolder1   Exclude: --  - Will be built
      MyFile.h  Exclude: --  - Will  be built
      MyFile1.h Exclude: Yes - Will not be built

Aggregating Properties

Aggregating properties are values which are collected from the hierarchy. For each element aggregating values can be extended. Example for preprocessor definitions:

MySolution      Property Value: SolDefine      Resulting Definition: SolDefine
  MyProject     Property Value: PrjDefine      Resulting Definition: SolDefine PrjDefine
    MyFolder    Property Value: FolderDefine   Resulting Definition: SolDefine PrjDefine FolderDefine
      MyFile.c  Property Value: FileDefine     Resulting Definition: SolDefine PrjDefine FolderDefine FileDefine
    MyFolder1   Property Value: <none>         Resulting Definition: SolDefine PrjDefine
      MyFile1.h Property Value: File1Define    Resulting Definition: SolDefine PrjDefine File1Define