Difference between revisions of "Embedded Studio project file format"
Line 4: | Line 4: | ||
'''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 ''' |
'''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= |
+ | ==Format description== |
− | ==Project Layout== |
+ | ===Project Layout=== |
Project files are essentially solution files, as such could include more than one project. |
Project files are essentially solution files, as such could include more than one project. |
||
Line 47: | Line 47: | ||
</solution> |
</solution> |
||
</source> |
</source> |
||
− | ==Project Options== |
+ | ===Project Options=== |
In ES Project Options can be set on every level, per build configuration. |
In ES Project Options can be set on every level, per build configuration. |
||
Line 114: | Line 114: | ||
</source> |
</source> |
||
− | ==Overriding project properties== |
+ | ===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. |
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. |
||
Line 120: | Line 120: | ||
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. |
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=== |
+ | ====Overriding properties==== |
Unique properties have one value. For each element the inherited unique property values can be overridden by changing it for this element. |
Unique properties have one value. For each element the inherited unique property values can be overridden by changing it for this element. |
||
Line 134: | Line 134: | ||
</pre> |
</pre> |
||
− | ===Aggregating Properties=== |
+ | ====Aggregating Properties==== |
Aggregating properties are values which are collected from the hierarchy. For each element aggregating values can be extended. Example for preprocessor definitions: |
Aggregating properties are values which are collected from the hierarchy. For each element aggregating values can be extended. Example for preprocessor definitions: |
||
<pre> |
<pre> |
Latest revision as of 11:22, 22 October 2020
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
Contents
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