diff --git a/docs/CreateApplications.md b/docs/CreateApplications.md index 756cf5e..e979a52 100644 --- a/docs/CreateApplications.md +++ b/docs/CreateApplications.md @@ -74,7 +74,7 @@ An application is based on a *device* and/or *board* supported by a Device Famil - For simple projects, the default settings should be sufficient. -- The [build information file](YML-CBuild-Format.md#cbuild-output-files) `.cbuild.Debug+.yml` lists configuration files of components and other useful information such as links to documentation of the component. +- The [build information file](YML-CBuild-Format.md) `.cbuild.Debug+.yml` lists configuration files of components and other useful information such as links to documentation of the component. ### Step 6: Add application functionality @@ -296,15 +296,13 @@ A potential solution is discussed [here](https://github.com/Open-CMSIS-Pack/devt **Duplicate Heap definition in Assembler startup file** When using memory allocation functions (i.e. `malloc`), the application ends in a hard fault handler. This is typically caused by different methods of stack and heap definitions. -The Arm Compiler offers [three ways to configure stack and heap](https://developer.arm.com/documentation/100073/0623/The-Arm-C-and-C---Libraries/Stack-and-heap-memory-allocation-and-the-Arm-C-and-C---libraries/Stack-pointer-initialization-and-heap-bounds). -- Use a scatter file to define `ARM_LIB_STACKHEAP`, `ARM_LIB_STACK`, or `ARM_LIB_HEAP` regions. +The Arm Compiler offers [three ways to configure stack and heap](https://developer.arm.com/documentation/100073/0623/The-Arm-C-and-C---Libraries/Stack-and-heap-memory-allocation-and-the-Arm-C-and-C---libraries/Stack-pointer-initialization-and-heap-bounds). Only one of the following methods should be used: + +- Use a linker scatter file to define `ARM_LIB_STACKHEAP`, `ARM_LIB_STACK`, or `ARM_LIB_HEAP` regions. - Use the symbols `__initial_sp`, `__heap_base`, and `__heap_limit`. - Implement `__user_setup_stackheap()` or `__user_initial_stackheap()`. -!!! Warning - You have to choose one of these three ways. - The [C startup code](https://arm-software.github.io/CMSIS_6/latest/Core/startup_c_pg.html) recommended by CMSIS Version 6 uses the linker scatter file for stack and heap definition. The C startup code is generic and works across all toolchains that are supported by the CMSIS-Toolbox. However, some assembler startup files define stack and heap with other methods, for example by using the symbols `__initial_sp`, `__heap_base`, and `__heap_limit`. @@ -313,7 +311,7 @@ There are two options to solve the problem. 1. Remove the stack and heap definition in the assembler startup code. -2. Disable in the [Regions Header File](#regions-header-file) the stack and heap definition by setting `__STACK_SIZE` and `__HEAP_SIZE` to 0 as shown below. +2. Disable in the [Regions Header File](#regions-header-file) the stack and heap definition by setting `__STACK_SIZE` and `__HEAP_SIZE` to 0 as shown below. This removes the definition in the linker scatter file. ```txt // Stack / Heap Configuration diff --git a/docs/YML-CBuild-Format.md b/docs/YML-CBuild-Format.md index 9f444c3..f6682c9 100644 --- a/docs/YML-CBuild-Format.md +++ b/docs/YML-CBuild-Format.md @@ -2,26 +2,26 @@ -The following chapter explains the YAML cbuild format that describes how to build a complete application. +The following chapter explains the output files are generated by the `csolution` tool. Depending on options, the files `*.cbuild-pack.yml` and `*.cbuild-set.yml` are also used as input file. The build information files are used for: -## cbuild Output Files - -The following output files are generated by the `csolution` tool. Depending on options, the files `*.cbuild-pack.yml` and `*.cbuild-set.yml` are also used as input file. +- generate CMake input files via the [cbuild2cmake](build-operation.md#cbuild2cmake-generate-cmakelists-files) tool. +- provide details for the graphical user interface in [VS Code extension Arm CMSIS Solution](https://marketplace.visualstudio.com/items?itemName=Arm.cmsis-csolution). +- obtain a list of licenses used in a project. File | Description :-------------------------------------------------------|:---------------------- -[`*.cbuild-idx.yml`](#file-structure-of-cbuild-idxyml) | Index file of all `*.cbuild.yml` build descriptions; contains also overall information for the application. -[`*.cbuild.+.yml`](#file-structure-of-cbuildyml) | Build description of a single [`*.cproject.yml`](YML-Input-Format.md#project-file-structure) input file; contains all information for the build step for a specific [context](build-overview.md#context) including references to the content used from software packs. -[`*.cbuild-pack.yml`](#file-structure-of-cbuild-packyml)| Software packs recorded for the all input files ([`*.csolution.yml`](YML-Input-Format.md#project-file-structure), `cproject.yml`, and `.clayer.yml`); used as input file to ensure [reproducible builds](build-overview.md#reproducible-builds) that use the same software packs and pack versions. -[`*.cbuild-set.yml`](#file-structure-of-cbuild-setyml) | [Context selection](build-overview.md#working-with-context-set) for the build process, enabled with option [--context-set:](build-tools.md#use-context-set). +[`*.cbuild-idx.yml`](#cbuild-idxyml) | Index file of all `*.cbuild.yml` build descriptions; contains also overall information for the application. +[`*.cbuild.yml`](#cbuildyml) | Build description of a single [`*.cproject.yml`](YML-Input-Format.md#project-file-structure) input file; contains all information for the build step for a specific [context](build-overview.md#context) including references to the content used from software packs. +[`*.cbuild-pack.yml`](#cbuild-packyml)| Software packs recorded for the all input files ([`*.csolution.yml`](YML-Input-Format.md#project-file-structure), `cproject.yml`, and `.clayer.yml`); used as input file to ensure [reproducible builds](build-overview.md#reproducible-builds) that use the same software packs and pack versions. +[`*.cbuild-set.yml`](#cbuild-setyml) | [Context selection](build-overview.md#working-with-context-set) for the build process, enabled with option [--context-set:](build-tools.md#use-context-set). -### Directory Structure +## Directory Structure -As `csolution` based projects should be portable across different host computers, **relative file references** are used within the directory structure. +The `csolution` based projects are portable across different host computers and use therefore **relative file references**. - All file references use relative paths to the base directory of the related `*.yml` file. Files that are within the file structure of the `csolution` base directory are also referenced using relative paths, i.e. `../layers/layer1/source-file1.c`. -- Files that are located in the [CMSIS-Pack root directory](https://github.com/Open-CMSIS-Pack/cmsis-toolbox/blob/main/docs/installation.md#environment-variables) are prefixed with `${CMSIS_PACK_ROOT}`. +- Files that are located in the [CMSIS-Pack root directory](installation.md#environment-variables) are prefixed with `${CMSIS_PACK_ROOT}`. !!! Note All file references to user source code should be relative paths. The prefixes `${CMSIS_PACK_ROOT}` and `${CMSIS_COMPILER_ROOT}` are used to refer to base directories of files that relate to software packs and compiler specific files. These base directories can also be on different filesystem drives. @@ -38,28 +38,27 @@ A typical directory structure of a `csolution` based application that uses commo ┣ myapp.cbuild-set.yml ┣ 📂 project1 ┃ ┣ mypro1.cproject.yml - ┃ ┣ mypro1.cbuild.yml # file references are relative to directory project1 + ┃ ┣ mypro1.cbuild.Debug+Target.yml # file references are relative to directory project1 ┣ 📂 project2 ┃ ┣ mypro2.cproject.yml - ┃ ┣ mypro2.cbuild.yml # file references are relative to directory project2 + ┃ ┣ mypro2.cbuild.Debug+Target.yml # file references are relative to directory project2 ┣ 📂 layer ┃ ┣ mylayer.clayer.yml ``` -### Pack locking +## Lock Pack Versions -An application contains a set of packs coming from different places, e.g. from the `csolution` directly, or indirectly from `cprojects` or `clayers`. -In order to have consistent pack usage in the application, as well as allowing projects to evolve and add new `target-types` or `build-types` but still remain on the same shared pack versions, the `cbuild-pack.yml` is introduced. +A *csolution project* refers to packs in different files (`*.csolution.yml`, `*.cproject.yml` or `*.clayer.yml`). To ensure consistent pack usage during application development (for example when new `target-types` or `build-types` are introduced) the `*.cbuild-pack.yml` file records the exact pack versions. -It works in the following way. An entire application has a set of `pack requirements`. These requirements can come from many different locations or contexts, and may be: +The required packs can be specified in *csolution project files* in the following ways: -- specified exactly, e.g. `ARM::CMSIS@5.9.0` -- specified with range, e.g. `ARM::CMSIS@>=5.8.0` -- specified without version, e.g. `ARM::CMSIS` -- specified with wildcards on the pack name, e.g. `ARM::CMSI*` -- specified without pack name, e.g. `ARM` +- exactly, e.g. `ARM::CMSIS@5.9.0` +- with range, e.g. `ARM::CMSIS@>=5.8.0` +- without version, e.g. `ARM::CMSIS` +- with wildcards on the pack name, e.g. `ARM::CMSI*` +- without pack name, e.g. `ARM` -All these `pack requirements` are `resolved` into exact versions in the `cbuild-pack.yml` file as a list of items on the following format: +The required packs are resolved to an exact pack version that is recorded in the `*.cbuild-pack.yml` file as shown below: ```yml cbuild-pack: @@ -73,51 +72,38 @@ cbuild-pack: - ARM::CMSIS@5.9.0 ``` -If a context is added or changed, the `selected-by` is used to ensure that the `pack requirements` are resolved to a `consistent` pack version, reducing surprising versions being selected in the entire application. -If a `pack requirement` is no longer present in the application, then the `cbuild-pack.yml` file will be *cleaned* from the relevant entries during the `cbuild-pack.yml` generation step. - -The location of the `cbuild-pack.yml` file follows the `csolution.yml` file. - -- `csolution convert` - Uses **and updates** `cbuild-pack.yml` -- `csolution list ...` - Uses `cbuild-pack.yml` -- `csolution run` - Uses `cbuild-pack.yml` -- `csolution update-rte` - Uses **and updates** `cbuild-pack.yml` - -```mermaid -graph TD; - csolution.yml - cbuild-pack.yml - cproject.yml - -subgraph Loading - res1["
Resolving step 1 (PopulateContexts)
  • Reading the files
  • Adds cbuild-pack.yml\npack requirements to the solution
"] - res2["
Resolving step 2 (AddPackRequirements)
  • Pack version ranges are matched to fully qualified versions using cbuild-pack.yml
  • Pack wildcards are matched to fully qualified versions using cbuild-pack.yml
  • Pack wildcards are kept for further expansion in the model
  • Local packs are left as-is
"] - style res1 text-align:left - style res2 text-align:left -end - - action["Some action
e.g. convert, list, run, update-rte, ..."] - -subgraph Saving - res3["
Resolving step 3 (GenerateCbuildPack)
  • Rebuild list of packs required by all contexts
  • Ensure that original 'pack expression' are kept in cbuild-pack.yml
"] - write["
Potentially write cbuild-pack.yml
  • Only done for the [convert, update-rte] commands
"] - style res3 text-align:left -end - - csolution.yml --> res1 - cbuild-pack.yml --> res1 - cproject.yml --> res1 - - res1 --> res2 - res2 --> action - action --> res3 - res3 --> write -``` +If *csolution project files* are modified, the `selected-by-pack` information ensures that consistent pack versions are used. If a required pack is no longer used in present in the *csolution project*, the relevant entry `resolved-pack:` in the `*.cbuild-pack.yml` file is removed. + +The `*.cbuild-pack.yml` file is located in the same directory as the `*.csolution.yml` file and is used by the `csolution` for every command that uses a `*.csolution.yml` file. Examples are: + +- `csolution convert` - uses **and updates** the `*.cbuild-pack.yml` file. +- `csolution list ...` - uses the `*.cbuild-pack.yml` file +- `csolution run` - uses the `*.cbuild-pack.yml` file. +- `csolution update-rte` - uses **and updates** the `*.cbuild-pack.yml` file. + +The operation of the `csolution` command is as follows: + +- Load the *csolution project files* (`*.csolution.yml`, `*.cproject.yml` or `*.clayer.yml`). +- Initially there is no `*.cbuild-pack.yml` file. If it exists, the `*.cbuild-pack.yml` file is loaded. The packs are aligned with the `resolved-pack:` information of the `*.cbuild-pack.yml` file in these steps: + - *PopulateContexts*: Add `resolved-pack:` information to the *solution data model*. + - *AddPackRequirements*: Pack version ranges and pack wildcards are matched to fully qualified versions of the *solution data model*. Pack wildcards are expanded to fully qualified packs using cbuild-pack.yml. Pack wildcards are kept for further expansion in the *solution data model*. +- Execute the `csolution` command, for example `convert`, `list`, `run`, or `update-rte`. +- Update the `*.cbuild-pack.yml` file (only if the content changes): + - *GenerateCbuildPack*: Generate the `resolved-pack:` list of packs required by all *contexts*. The original `pack:` specification is stored under `selected-by-pack:`. -This means that the `cbuild-pack.yml` information is used to load the appropriate fully qualified pack versions, matching previously used version ranges and pack wildcards. -Subsequent runs, and newly added contexts, can therefore use the least surprising versions. +With subsequent `csolution` command the information of the `*.cbuild-pack.yml` file is used to load the appropriate fully qualified pack versions, matching previously used packs. -### File Structure of `*.cbuild-idx.yml` +## File Format + +The following sections describe the format of the *build information files*. Many nodes are identical with the [**CSolution Project Format**](YML-Input-Format.md), but optional information is fully expanded. The nodes that are different are explained below under: + +- [**Nodes for Project Management**](#nodes-for-project-management) +- [**Nodes for File Management**](#nodes-for-file-management) +- [**Nodes for License Information**](#nodes-for-license-information) + +### `*.cbuild-idx.yml` + +The `.cbuild-idx.yml` file is generated for the *csolution project* and refers all *contexts* that are generated. It is structured as outlined below. `build-idx:` | Content :-------------------------------------------------------------|:------------------------------------ @@ -164,9 +150,9 @@ build-idx: - pack: ARM::CMSIS@6.0.0 # with specified version ``` -### File Structure of `*.cbuild.yml` +### `*.cbuild.yml` -The `cbuild.yml` file is structured into several sections. The top-level structure is outlined below. +The `.+.cbuild.yml` contains all information for one *context*. It is structured as outlined below. `build:` | Content :--------------------------------------------------------|:------------------------------------ @@ -287,9 +273,9 @@ build: category: header ``` -### File Structure of `*.cbuild-pack.yml` +### `*.cbuild-pack.yml` -The `cbuild-pack.yml` file is structured into several sections. The top-level structure is outlined below. +The `.cbuild-pack.yml` file contains the [pack information](#lock-pack-versions) for the *csolution project*. It is structured as outlined below. `cbuild-pack:` | Content :------------------------------------------------------------------|:------------------------------------ @@ -316,9 +302,9 @@ cbuild-pack: - Keil::ARM_Compiler ``` -### File Structure of `*.cbuild-set.yml` +### `*.cbuild-set.yml` -The `cbuild-set.yml` file is structured into several sections. The top-level structure is outlined below. +The `.cbuild-set.yml` file selects the [context set](build-overview.md#working-with-context-set) for the *csolution project*. The structure is outlined below. `cbuild-set:` | Content :------------------------------------------------------------------|:------------------------------------ @@ -335,9 +321,9 @@ cbuild-set: - context: CM33_ns.Debug+AVH ``` -## cbuild-specific Nodes +### Nodes for Project Management -### `configurations:` +#### `configurations:` The `configurations:` node lists possible configurations for [reference applications](ReferenceApplications.md) that have undefined variable settings. @@ -386,7 +372,7 @@ The `configurations:` node lists possible configurations for [reference applicat copy-to: board/frdmk22f ``` -### `cprojects:` +#### `cprojects:` The `cprojects:` node lists all `*.cproject.yml` input files along with `*.clayer.yml` files that are used to compose the application. @@ -407,7 +393,7 @@ The `cprojects:` node lists all `*.cproject.yml` input files along with `*.claye : ``` -### `cbuilds:` +#### `cbuilds:` The `cbuilds:` node lists all project context configurations that are generated with this build. @@ -435,7 +421,7 @@ The `cbuilds:` node lists all project context configurations that are generated - test.cbuild-set.yml - file is already up-to-date ``` -### `select-compiler:` +#### `select-compiler:` If no compiler is specified in the *csolution project*, the [`cbuild setup` command](build-operation.md#details-of-the-setup-mode) lists the available compilers based on the [compiler registration](installation.md#compiler-registration) and `select-compiler:` node in the file [`*.csolution.yml`](YML-Input-Format.md#solution) or [`cdefault.yml`](YML-Input-Format.md#cdefault). @@ -443,7 +429,7 @@ If no compiler is specified in the *csolution project*, the [`cbuild setup` comm :----------------------|:------------------------------------ `- compiler:` | Name (optionally with version) of the compiler toolchain; copied from the `select-compiler:` node in the *csolution project*. -### `packs:` +#### `packs:` The `packs:` node is the start of a pack list that is used for the project context. @@ -453,7 +439,7 @@ The `packs:` node is the start of a pack list that is used for the project conte    `path:` | Path name that stores the software pack (see note). !!! Note - Packs that are located in the [CMSIS-Pack root directory](https://github.com/Open-CMSIS-Pack/cmsis-toolbox/blob/main/docs/installation.md#environment-variables) are prefixed with `%CMSIS_PACK_ROOT%`. + Packs that are located in the [CMSIS-Pack root directory](installation.md#environment-variables) are prefixed with `%CMSIS_PACK_ROOT%`. **Example:** @@ -468,7 +454,7 @@ The `packs:` node is the start of a pack list that is used for the project conte path: ../IoT_Socket ``` -### `generators:` +#### `generators:` The `generators:` node contains information for calling a generator. @@ -495,14 +481,21 @@ The `generators:` node contains information for calling a generator. - ${CMSIS_PACK_ROOT}/Keil/STM32L4xx_DFP/2.6.1 ``` -## Source File Management +#### `generator:` + +`generator:` | Content +:--------------------------------------------------------------|:------------------------------------ +`- id:` | Generator identifier used for this component +    `path:` | File name and path to the *.cgen.yml file that is generated. + +### Nodes for File Management Keyword | Description :----------------|:------------------------------------ `groups:` | Start of a list that adds source groups and files. `components:` | Start of a list that adds software components. -### `linker:` +#### `linker:` `linker:` | Content :-------------------------------------------------|:-------------------------------- @@ -510,7 +503,7 @@ Keyword | Description `- script:` | Path and file name of the Linker Script template that is pre-processed. [`- define:`](YML-Input-Format.md#define) | Define symbol settings for the linker script file preprocessor. -### `groups:` +#### `groups:` `groups:` | Content :--------------------------------------------------------------|:------------------------------------ @@ -524,7 +517,7 @@ Keyword | Description     [`groups:`](#groups) | Start a nested list of groups.     [`files:`](#files-of-a-group) | List of files that belong to a group -### `files:` of a group +#### `files:` of a group `files:` | Content :--------------------------------------------------------------|:------------------------------------ @@ -537,7 +530,17 @@ Keyword | Description     [`add-path:`](YML-Input-Format.md#add-path) | Additional include file paths.     [`misc:`](YML-Input-Format.md#misc) | Literal tool-specific controls. -### `components:` +#### `apis:` + +`apis:` | Content +:--------------------------------------------------------------|:------------------------------------ +`- api:` | Name of the API. +    [`condition:`](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/pdsc_conditions_pg.html#element_condition) | Reference to the condition ID of the software pack that triggered inclusion of this API. +    `from-pack:` | Pack that defines this API. +    `implemented-by:` | Refers to the software componeent that implements the API. +    [`files:`](#files-of-a-component) | List of files that belong to this API. + +#### `components:` `components:` | Content :--------------------------------------------------------------|:------------------------------------ @@ -556,24 +559,7 @@ Keyword | Description     `implements:` | Refers to the API that the component is based on.     [`files:`](#files-of-a-component) | List of files that belong to this component. -### `apis:` - -`apis:` | Content -:--------------------------------------------------------------|:------------------------------------ -`- api:` | Name of the API. -    [`condition:`](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/pdsc_conditions_pg.html#element_condition) | Reference to the condition ID of the software pack that triggered inclusion of this API. -    `from-pack:` | Pack that defines this API. -    `implemented-by:` | Refers to the software componeent that implements the API. -    [`files:`](#files-of-a-component) | List of files that belong to this API. - -### `generator:` - -`generator:` | Content -:--------------------------------------------------------------|:------------------------------------ -`- id:` | Generator identifier used for this component -    `path:` | File name and path to the *.cgen.yml file that is generated. - -### `files:` of a component +#### `files:` of a component `files:` | Content :--------------------------------------------------------------|:------------------------------------ @@ -587,7 +573,7 @@ Keyword | Description     [`update:`](build-overview.md#plm-of-configuration-files) | New configuration file from an updated *software pack*.     `status:` | Action for configuration file update: suggested, recommended, required. -### `constructed-files:` +#### `constructed-files:` A list of files that are generated by the RTE management of the `csolution` tool. @@ -596,9 +582,12 @@ A list of files that are generated by the RTE management of the `csolution` tool `- file:` | Name and path to the file.     [`category:`](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/pdsc_components_pg.html#FileCategoryEnum) | File category according Open-CMSIS-Pack specification -## `licenses:` +### Nodes for License Information + +The `*.cbuild.+.yml` files contains license information about each software component that is included from software packs. + +#### `licenses:` -The `*.cbuild.yml` files contains license information about each software component that is included from software packs. Each different license that is used in an a project context has a sepearate section. `licenses:` | Content @@ -644,7 +633,7 @@ The `csolution run` command generates the following build information files in t File | Description :-----------------------|:---------------------- `*.cbuild-gen-idx.yml` | Index file of all `*.cbuild-gen.yml` build descriptions; contains also overall information for the application. -`*.cbuild-gen.yml` | Build description of a single [`*.cproject.yml`](YML-Input-Format.md#project-file-structure) input file. The format is identical with the [`*.cbuild.yml`](#file-structure-of-cbuildyml) file. +`*.cbuild-gen.yml` | Build description of a single [`*.cproject.yml`](YML-Input-Format.md#project-file-structure) input file. The format is identical with the [`*.cbuild.yml`](#cbuildyml) file. ### File Structure of `*.cbuild-gen-idx.yml` @@ -664,7 +653,7 @@ File | Description `cbuild-gens:` | Content :--------------------------------------------------|:------------------------------------ -`- cbuild-gen:` | Build information file with name `.cbuild-gen.yml`; structure identical with [*.cbuild.yml](#file-structure-of-cbuildyml). +`- cbuild-gen:` | Build information file with name `.cbuild-gen.yml`; structure identical with [*.cbuild.yml](#cbuildyml).     `project:` | Project name (used as name for `*.cgen.yml` when `name:` is not specified)     `configuration:` | Specifies `.build-type+target-type` of this context.     `name:` | Explicit name for the `*.cgen.yml` [generator import file](#generator-import-file) specified by [`generator options`](YML-Input-Format.md#generators-options). @@ -691,7 +680,7 @@ build-gen-idx: ## Generator Import File -The `*.cgen.yml` file is lists the generated *csolution project* part and starts with the node `generator-import:`. It defines similar to a [Software Layer](./build-overview.md#software-layers) additional parameters, files, and components that are included in the project. +The `*.cgen.yml` file lists the generated *csolution project* part and starts with the node `generator-import:`. It defines similar to a [Software Layer](build-overview.md#software-layers) additional parameters, files, and components that are included in the project. ### File Structure of `*.cgen.yml` diff --git a/docs/YML-Input-Format - Preinclude.md b/docs/YML-Input-Format - Preinclude.md deleted file mode 100644 index 1ccdfcb..0000000 --- a/docs/YML-Input-Format - Preinclude.md +++ /dev/null @@ -1,2032 +0,0 @@ -# CMSIS Solution Project File Format - - - - - -The following chapter explains the CMSIS Solution Project File Format (short form *csolution project files*), the YAML files that that describes the software of an embedded application. - -## Name Conventions - -### Filename Extensions - -The **`csolution` Project Manager** recognizes the [categories](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/pdsc_components_pg.html#FileCategoryEnum) of [files](#files) based on the filename extension in the YAML input files as shown in the table below. - -File Extension | [Category](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/pdsc_components_pg.html#FileCategoryEnum) | Description -:--------------------------------------------|:-------------|:--------------------- -`.c`, `.C` | sourceC | C source file -`.cpp`, `.c++`, `.C++`, `.cxx`, `.cc`, `.CC` | sourceCpp | C++ source file -`.h`,`.hpp` | header | Header file -`.asm`, `.s`, `.S` | sourceAsm | Assembly source file -`.ld`, `.scf`, `.sct`, `.icf` | linkerScript | Linker Script file -`.a`, `.lib` | library | Library file -`.o` | object | Object file -`.txt`, `.md`, `.pdf`, `.htm`, `.html` | doc | Documentation -`.scvd` | other | [Software Component View Description](https://arm-software.github.io/CMSIS-View/latest/SCVD_Format.html) for CMSIS-View - -### `pack:` Name Conventions - -The **`csolution` Project Manager** uses the following syntax to specify the `pack:` names in the `*.yml` files. - -```yml -vendor [:: pack-name [@[~ | >=] version] ] -``` - -Element | | Description -:------------|--------------|:--------------------- -`vendor` | **Required** | Vendor name of the software pack. -`pack-name` | Optional | Name of the software pack; wildcards (\*, ?) can be used. -`version` | Optional | Version number of the software pack, with `@1.2.3` that must exactly match, `@~1.2`/`@~1` that matches with semantic versioning, or `@>=1.2.3` that allows any version higher or equal. - -!!! Note - -When no version is specified, the **`csolution` Project Manager** only loads the latests version of a software pack. This also applies when wildcards are used in the `pack-name`. - -**Examples:** - -```yml -- pack: ARM::CMSIS@5.5.0 # 'CMSIS' Pack (with version 5.5.0) -- pack: Keil::MDK-Middleware@>=7.13.0 # 'MDK-Middleware' Software Pack from vendor Keil (with version 7.13.0 or higher, latest available to the tool) -- pack: Keil::TFM # 'TFM' Software Pack from vendor Keil (with latest version available to the tool) -- pack: AWS # All latest versions of Software Packs from vendor 'AWS' -- pack: Keil::STM* # All latest versions of Software Packs that start with 'STM' from vendor 'Keil' -``` - -### `component:` Name Conventions - -The **`csolution` Project Manager** uses the following syntax to specify the `component:` names in the `*.yml` files. - -```yml -[Cvendor::] Cclass [&Cbundle] :Cgroup [:Csub] [&Cvariant] [@[~ | >=]Cversion] -``` - -Components are defined using the [Open-CMSIS-Pack - `` element](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/pdsc_components_pg.html#element_component). Several parts of a `component` are optional. For example it is possible to just define a component using `Cclass` and `Cgroup` name. All elements of a component name are summarized in the following table. - -Element | | Description -:----------|--------------|:--------------------- -`Cvendor` | Optional | Name of the component vendor as defined in `` element or by the package vendor of the software pack. -`Cclass` | **Required** | Component class name as defined in `` element of the software pack. -`Cbundle` | Optional | Bundle name of the component class as defined in `` element of the software pack. -`Cgroup` | **Required** | Component group name as defined in `` element of the software pack. -`Csub` | Optional | Component sub-group name as defined in `` element of the software pack. -`Cvariant` | Optional | Component sub-group name as defined in `` element of the software pack. -`Cversion` | Optional | Version number of the component, with `@1.2.3` that must exactly match, `@~1.2`/`@~1` that matches with semantic versioning, or `@>=1.2.3` that allows any version higher or equal. - -**Partly defined components** - -A component can be partly defined in *csolution project files* (`*.cproject.yml`, `*.clayer.yml`, `*.genlayer.yml`) by omitting `Cvendor`, `Cvariant`, and `Cversion`, even when this are part of the `components` element of the software pack. The component select algorithm resolves this to a fully defined component by: - -- when a partly specified component resolves to several possible choices, the tool selects: - - (a) the default `Cvariant` of the component as defined in the PDSC file. - - (b) the component with the higher `Cversion` value. - - (c) and error message is issued when two identical components are defined by multiple vendors and `Cvendor` is not specified. -- the partly specified component is extended by: - - version information from the software pack. - - default variant definition from the software pack. - -The fully resolved component name is shown in the [`*.cbuild.yml`](YML-CBuild-Format.md) output file. - -**Multiple component definitions are rejected** - -- If a component is added more then once in the *csolution project files* and an *error* is issued. -- An attempt to select multiple variants (using `Cvariant`) of a component results in an *error*. - -**Examples:** - -```yml -- component: CMSIS:CORE # CMSIS Core component (vendor selected by `csolution` ARM) -- component: ARM::CMSIS:CORE # CMSIS Core component from vendor ARM (any version) -- component: ARM::CMSIS:CORE@5.5.0 # CMSIS Core component from vendor ARM (with version 5.5.0) -- component: ARM::CMSIS:CORE@>=5.5.0 # CMSIS Core component from vendor ARM (with version 5.5.0 or higher) - -- component: Device:Startup # Device Startup component from any vendor - -- component: CMSIS:RTOS2:Keil RTX5 # CMSIS RTOS2 Keil RTX5 component with default variant (any version) -- component: ARM::CMSIS:RTOS2:Keil RTX5&Source@5.5.3 # CMSIS RTOS2 Keil RTX5 component with variant 'Source' and version 5.5.3 - -- component: Keil::USB&MDK-Pro:CORE&Release@6.15.1 # USB CORE component from bundle MDK-Pro in variant 'Release' and version 6.15.1 -``` - -### `device:` Name Conventions - -The device specifies multiple attributes about the target that ranges from the processor architecture to Flash -algorithms used for device programming. The following syntax is used to specify a `device:` value in the `*.yml` files. - -```yml -[ [ Dvendor:: ] Dname] [:Pname] -``` - -Element | | Description -:-------------|----------|:--------------------- -`Dvendor` | Optional | Name (without enum field) of the device vendor defined in `` element of the software pack. -`Dname` | Optional | Device name (Dname attribute) or when used the variant name (Dvariant attribute) as defined in the \ element. -`Pname` | Optional | Processor identifier (Pname attribute) as defined in the `` element. - -!!! Note - -- All elements of a device name are optional which allows to supply additional information, such as the `:Pname` at - different stages of the project. However the `Dname` itself is a mandatory element and must be specified in - context of the various project files. -- `Dvendor::` must be used in combination with the `Dname`. - -**Examples:** - -```yml -device: NXP::LPC1768 # The LPC1788 device from NXP -device: LPC1788 # The LPC1788 device (vendor is evaluated from DFP) -device: LPC55S69JEV98 # Device name (exact name as defined in the DFP) -device: LPC55S69JEV98:cm33_core0 # Device name (exact name as defined in the DFP) with Pname specified -device: :cm33_core0 # Pname added to a previously defined device name (or a device derived from a board) -``` - -### `board:` Name Conventions - -Evaluation Boards define indirectly a device via the related BSP. The following syntax is used to specify a `board:` -value in the `*.yml` files. - -```yml -[vendor::] board_name [:revision] -``` - -Element | | Description -:------------|--------------|:--------------------- -`vendor` | Optional | Name of the board vendor defined in `` element of the board support pack (BSP). -`Bname` | **Required** | Board name (name attribute) as defined in the \ element of the BSP. -`revision` | Optional | Board revision (revision attribute) as defined in the \ element of the BSP. - -!!! Note - -When a `board:` is specified, the `device:` specification can be omitted, however it is possible to overwrite the device setting in the BSP with an explicit `device:` setting. - -**Examples:** - -```yml -board: Keil::MCB54110 # The Keil MCB54110 board (with device NXP::LPC54114J256BD64) -board: LPCXpresso55S28 # The LPCXpresso55S28 board -board: STMicroelectronics::NUCLEO-L476RG:Rev.C # A board with revision specification -``` - -### `context:` Name Conventions - -A `context:` name combines `project-name`, `built-type`, and `target-type` and is used on various places in the CMSIS-Toolbox. The following syntax is used to specify a `context:` name. - -```yml -[project-name][.build-type][+target-type] -``` - -Element | | Description -:-------------------|--------------|:--------------------- -`project-name` | Optional | Project name of a project (base name of the *.cproject.yml file). -`.build-type` | Optional | The [`build-type`](#build-types) name that is currently processed (specified with `- type: name`). -`+target-type` | Optional | The [`target-type`](#target-types) name that is currently processed (specified with `- type: name`). - -!!! Note - -The `.build-type` and `+target-type` name allows letters (A-Z, a-z), digits (0-9), dash ('-'), and underscore ('_'); the maximum length is 32 characters. - -- When `project-name` is omitted, the `project-name` is the base name of the `*.cproject.yml` file. -- When `.build-type` is omitted, it matches with any possible `.build-type`. -- When `+target-type` is omitted, it matches with any possible `+target-type`. - -By default, the specified `- type: name` of [`build-types:`](#build-types) and [`target-types:`](#target-types) nodes in the `*.csolution.yml` file are directly mapped to the `context` name. -Using the [`context-map:`](#context-map) node it is possible to assign a different `.build-type` and/or `+target-type` mapping for a specific `project-name`. - -**Example:** - -Show the different possible context settings of a `*.csolution.yml` file. - -```txt -AWS_MQTT_MutualAuth_SW_Framework>csolution list contexts -s Demo.csolution.yml -Demo.Debug+AVH -Demo.Debug+IP-Stack -Demo.Debug+WiFi -Demo.Release+AVH -Demo.Release+IP-Stack -Demo.Release+WiFi -``` - -The `context` name is also used in [`for-context:`](#for-context) and [`not-for-context:`](#not-for-context) nodes that allow to include or exclude items depending on the `context`. In many cases the `project-name` can be omitted as the `context` name is within a specific `*.cproject.yml` file or applied to a specific `*.cproject.yml` file. - -## Access Sequences - -The following **access sequences** allow to use arguments from the CMSIS Project Manager as arguments of the various -`*.yml` files in the key values for `define:`, `add-path:`, `misc:`, `files:`, and `executes:`. The **access sequences** -can refer in a different project and provide therefore a method to describe project dependencies. - -Access Sequence | Description -:----------------------------------------------|:-------------------------------------- -**Target** | **Access to target and build related settings** -`$Bname$` | [Bname](#board-name-conventions) of the selected board as specified in the [`board:`](#board) node. -`$Dname$` | [Dname](#device-name-conventions) of the selected device as specified in the [`device:`](#device) node. -`$Pname$` | [Pname](#device-name-conventions) of the selected device as specified in the [`device:`](#device) node. -`$BuildType$` | [Build-type](#build-types) name of the currently processed project. -`$TargetType$` | [Target-type](#target-types) name of the currently processed project. -`$Compiler$` | [Compiler](#compiler) name of the compiler used in this project context as specified in the [`compiler:`](#compiler) node. -**YML Input** | **Access to YML Input Directories and Files** -`$Solution$` | Solution name (base name of the *.csolution.yml file). -`$SolutionDir()$` | Path to the directory of the current processed `csolution.yml` file. -`$Project$` | Project name of the current processed `cproject.yml` file. -`$ProjectDir(context)$` | Path to the directory of a related `cproject.yml` file. -**Output** | **Access to Output Directories and Files** -`$OutDir(context)$` | Path to the output directory of a related project that is defined in the `*.csolution.yml` file. -`$bin(context)$` | Path and filename of the binary output file generated by the related context. -`$cmse-lib(context)$` | Path and filename of the object file with secure gateways of a TrustZone application generated by the related context. -`$elf(context)$` | Path and filename of the ELF/DWARF output file generated by the related context. -`$hex(context)$` | Path and filename of the HEX output file generated by the related context. -`$lib(context)$` | Path and filename of the library file of the related context. - -For a [`context`](#context-name-conventions) the `project-name`, `.build-type`, and `+target-type` are optional; when omitted the current processed context is used. Example: `$ProjectDir()$` is the directory of the current processed `cproject.yml` file. - -!!! Note - -The access sequences below are not completed yet, as they require a change to CMSIS-Build. - -Access Sequence | Description -:----------------------------------------------|:-------------------------------------- -`$Bpack$` | Path to the pack that defines the selected board (BSP). -`$Dpack$` | Path to the pack that defines the selected device (DFP). -`$Pack(vendor.name)$` | Path to a specific pack. Example: `$Pack(NXP.K32L3A60_DFP)$`. - -**Example:** - -For the example below we assume the following `build-type`, `target-type`, and `projects` definitions. - -```yml -solution: - target-types: - - type: Board # target-type: Board - board: NUCLEO-L552ZE-Q # specifies board - - - type: Production-HW # target-type: Production-HW - device: STM32U5X # specifies device - - build-types: - - type: Debug # build-type: Debug - optimize: none - debug: on - - - type: Release # build-type: Release - optimize: size - - projects: - - project: ./bootloader/Bootloader.cproject.yml # relative path - - project: /MyDevelopmentTree/security/TFM.cproject.yml # absolute path - - project: ./application/MQTT_AWS.cproject.yml # relative path -``` - -The `project: /application/MQTT_AWS.cproject.yml` can now use **Access Sequences** to reference files or directories in -other projects that belong to a solution. For example, these references are possible in the file `MQTT_AWS.cproject.yml`. - -The example below uses the `build-type` and `target-type` of the current processed context. In practice this means that -the same `build-type` and `target-type` is used as for the `MQTT_AWS.cproject.yml` project. - -```yml - files: - - file: $cmse-lib(TFM)$ # use the symbol output file of the TFM Project -``` - -The example below uses from the TFM project always `build-type: Debug` and the `target-type: Production-HW`. - -```yml - files: - - file: `$cmse-lib(TFM.Release+Production-HW)$` # use the symbol output file of the TFM Project -``` - -The example below uses the `build-type: Debug`. The `target-type` of the current processed context is used. - -!!! Note - -Implementation of `executes:` is scheduled for implementation in CMSIS-Toolbox 2.4 (Q2'24) - -```yml - executes: - - execute: Generate Image - run: gen_image %input% -o %output% # DFP the get_image tool - input: - - $elf(TFM.Debug)$ - - $elf(Bootloader.Release)$ - output: - - $OutDir(TFM.Debug)$ -``` - -The example below creates a `define` that uses the device name. - -```yml -groups: - - group: "Main File Group" - define: - - $Dname$ # Generate a #define 'device-name' for this file group -``` - -## Variables - -The `variables:` node defines are *key/value* pairs that can be used to refer to `*.clayer.yml` files. The *key* is the name of the *variable* and can be used in the following nodes: [`layers:`](#layers), [`define:`](#define), [`add-path:`](#add-path), [`misc:`](#misc), [`files:`](#files), and [`executes:`](#executes) - -Using variables that are defined in the `*.csolution.yml` file, a `*.cproject.yml` file requires no modifications when new `target-types:` are introduced. The required `layers:` could be instead specified in the `*.csolution.yml` file using a new node `variables:`. - -**Example:** - -*Example.csolution.yml* - -```yml -solution: - target-types: - - type: NXP Board - board: IMXRT1050-EVKB - variables: - - Socket-Layer: ./Socket/FreeRTOS+TCP/Socket.clayer.yml - - Board-Layer: ./Board/IMXRT1050-EVKB/Board.clayer.yml - - - type: ST Board - board: B-U585I-IOT02A - variables: - - Socket-Layer: ./Socket/WiFi/Socket.clayer.yml - - Board-Layer: ./Board/B-U585I-IOT02A/Board.clayer.yml -``` - -*Example.cproject.yml* - -```yml - layers: - - layer: $Socket-Layer$ - type: Socket - - - layer: $Board-Layer$ # no `*.clayer.yml` specified. Compatible layers are listed - type: Board # layer of type `Board` is expected -``` - -## Order of List Nodes - -The *key*/*value* pairs in a list node can be in any order. The two following list nodes are logically identical. This -might be confusing for `yml` files that are generated by an IDE. - -```yml - build-types: - - type: Release # build-type name - optimize: size # optimize for size - debug: off # generate no debug information for the release build -``` - -```yml - build-types: - - debug: off # generate no debug information for the release build - optimize: size # optimize for size - type: Release # build-type name -``` - -## Project File Structure - -The table below explains the top-level elements in each of the different `*.yml` input files that define the overall application. - -Keyword | Description -:--------------------------------|:------------------------------------ -[`default:`](#cdefault) | Start of `cdefault.yml` file that is used to setup the compiler along with some compiler-specific controls. -[`solution:`](#solution) | Start of `*.csolution.yml` file that [collects related projects](build-overview.md#project-examples) along with `build-types:` and `target-types:`. -[`project:`](#project) | Start of `*.cproject.yml` file that defines files, components, and layers which can be independently translated to a binary image or library. -[`layer:`](#layer) | Start of `*.clayer.yml` file that contains pre-configured software components along with source files. - -### `cdefault:` - -When [`cdefault:`](#solution) is specified in the `*.csolution.yml` file, the **`csolution` Project Manager** uses a file with the name `cdefault.yml` or `cdefault.yaml` to setup -the compiler along with some specific default controls. The search order for this file is: - -- A `cdefault.yml` or `cdefault.yaml` file in the same directory as the `.csolution.yml` file. -- A `cdefault.yml` or `cdefault.yaml` file in the directory specified by the environment variable [`CMSIS_COMPILER_ROOT`](https://github.com/Open-CMSIS-Pack/cmsis-toolbox/blob/main/docs/installation.md#environment-variables). -- A `cdefault.yml` or `cdefault.yaml` file in the directory [`/etc`](https://github.com/Open-CMSIS-Pack/cmsis-toolbox/blob/main/docs/installation.md##etccmake). - -The `default:` node is the start of a `cdefault.yml` or `cdefault.yaml` file and contains the following. - -`default:` | Content -:-----------------------------------------------------|:------------------------------------ -   [`compiler:`](#compiler) | Toolchain selection. -   [`misc:`](#misc) | Literal tool-specific controls. - -**Example:** - -```yml -default: - compiler: AC6 - misc: - - ASM: - - -masm=auto - - - Link: - - --info sizes --info totals --info unused --info veneers --info summarysizes - - --map -``` - -### `solution:` - -The `solution:` node is the start of a `*.csolution.yml` file that collects related projects as described in the section -["Project setup for related projects"](build-overview.md#project-setup-for-related-projects). - -`solution:` | | Content -:----------------------------------------------------|:-----------|:------------------------------------ -    `created-by:` | Optional | Identifies the tool that created this solution. -    `created-for:` | Optional | Specifies the tool for building this solution, i.e. **CMSIS-Toolbox@2.2.0** -    `description:` | Optional | Brief description text of this solution. -    `cdefault:` | Optional | When specified, the [`cdefault.yml`](#cdefault) file is used to setup compiler specific controls. -    [`compiler:`](#compiler) | Optional | Overall toolchain selection for this solution. -    [`language-C:`](#language-c) | Optional | Set the language standard for C source file compilation. -    [`language-CPP:`](#language-cpp) | Optional | Set the language standard for C++ source file compilation. -    [`pre-include:`](#pre-include) | Optional | Add pre-include files for C and C++ source files. -    [`output-dirs:`](#output-dirs) | Optional | Control the output directories for the build output. -    [`generators:`](#generators) | Optional | Control the directory structure for generator output. -    [`packs:`](#packs) | Optional | Defines local packs and/or scope of packs that are used. -    [`target-types:`](#target-types) |**Required**| List of target-types that define the target system (device or board). -    [`build-types:`](#build-types) | Optional | List of build-types (i.e. Release, Debug, Test). -    [`projects:`](#projects) |**Required**| List of projects that belong to the solution. -    [`executes:`](#executes) | Optional | Additional pre or post build steps using external tools. - -**Example:** - -```yml -solution: - created-for: cmsis-toolbox@2.0 # minimum CMSIS-Toolbox version required for project build - cdefault: # use default setup of toolchain specific controls. - compiler: GCC # overwrite compiler definition in 'cdefaults.yml' - - packs: - - pack: ST # add ST packs in 'cdefaults.yml' - - build-types: # additional build types - - type: Test # build-type: Test - optimize: none - debug: on - packs: # with explicit pack specification - - pack: ST::TestSW - path: ./MyDev/TestSW - - target-types: - - type: Board # target-type: Board - board: NUCLEO-L552ZE-Q - - - type: Production-HW # target-type: Production-HW - device: STM32U5X # specifies device - - projects: - - project: ./blinky/Bootloader.cproject.yml - - project: /security/TFM.cproject.yml - - project: /application/MQTT_AWS.cproject.yml -``` - -### `project:` - -The `project:` node is the start of a `*.cproject.yml` file and can contain the following: - -`project:` | | Content -:---------------------------------------------------|:-----------|:------------------------------------ -    `description:` | Optional | Brief description text of this project. -    [`output:`](#output) | Optional | Configure the generated output files. -    [`generators:`](#generators) | Optional | Control the directory structure for generator output. -    [`rte:`](#rte) | Optional | Control the directory structure for [RTE (run-time environment)](build-overview.md#rte-directory-structure) files. -    [`packs:`](#packs) | Optional | Defines packs that are required for this project. -    [`language-C:`](#language-c) | Optional | Set the language standard for C source file compilation. -    [`language-CPP:`](#language-cpp) | Optional | Set the language standard for C++ source file compilation. -    [`pre-include:`](#pre-include) | Optional | Add pre-include files for C and C++ source files. -    [`optimize:`](#optimize) | Optional | Optimize level for code generation. -    [`linker:`](#linker) | Optional | Instructions for the linker. -    [`debug:`](#debug) | Optional | Generation of debug information. -    [`define:`](#define) | Optional | Preprocessor (#define) symbols for code generation. -    [`undefine:`](#undefine) | Optional | Remove preprocessor (#define) symbols. -    [`add-path:`](#add-path) | Optional | Additional include file paths. -    [`del-path:`](#del-path) | Optional | Remove specific include file paths. -    [`misc:`](#misc) | Optional | Literal tool-specific controls. -    [`device:`](#device) | Optional | Device setting (specify processor core). -    [`processor:`](#processor) | Optional | Processor specific settings. -    [`groups:`](#groups) |**Required**| List of source file groups along with source files. -    [`components:`](#components) | Optional | List of software components used. -    [`layers:`](#layers) | Optional | List of software layers that belong to the project. -    [`connections:`](#connections) | Optional | List of consumed and provided resources. -    [`executes:`](#executes) | Optional | Additional pre or post build steps using external tools. - -**Example:** - -```yml -project: - misc: - - compiler: AC6 # specify misc controls for Arm Compiler 6 - C: [-fshort-enums, -fshort-wchar] # set options for C files - add-path: - - $OutDir(Secure)$ # add the path to the secure project's output directory - components: - - component: Startup # Add startup component - - component: CMSIS CORE - - component: Keil RTX5 Library_NS - groups: - - group: Non-secure Code # Create group - files: - - file: main_ns.c # Add files to group - - file: $Source(Secure)$interface.h - - file: $Output(Secure)$_CMSE_Lib.o -``` - -### `layer:` - -The `layer:` node is the start of a `*.clayer.yml` file and defines a [Software Layer](./build-overview.md#software-layers). It can contain the following nodes: - -`layer:` | | Content -:------------------------------------------------------------|:-----------|:------------------------------------ -    [`type:`](#layer-type) | Optional | Layer type for combining layers; used to identify [compatible layers](ReferenceApplications.md#usage). -    `description:` | Optional | Brief description text of the layer. -    [`language-C:`](#language-c) | Optional | Set the language standard for C source file compilation. -    [`language-CPP:`](#language-cpp) | Optional | Set the language standard for C++ source file compilation. -    [`pre-include:`](#pre-include) | Optional | Add pre-include files for C and C++ source files. -    [`optimize:`](#optimize) | Optional | Optimize level for code generation. -    [`debug:`](#debug) | Optional | Generation of debug information. -    [`warnings:`](#warnings) | Optional | Control generation of compiler diagnostics. -    [`define:`](#define) | Optional | Define symbol settings for code generation. -    [`undefine:`](#undefine) | Optional | Remove define symbol settings for code generation. -    [`add-path:`](#add-path) | Optional | Additional include file paths. -    [`del-path:`](#del-path) | Optional | Remove specific include file paths. -    [`misc:`](#misc) | Optional | Literal tool-specific controls. -    [`generators:`](#generators) | Optional | Control the directory structure for generator output. -    [`packs:`](#packs) | Optional | Defines packs that are required for this layer. -    [`for-device:`](#device-name-conventions) | Optional | Device information, used for consistency check (device selection is in `*.csolution.yml`). -    [`for-board:`](#board-name-conventions) | Optional | Board information, used for consistency check (board selection is in `*.csolution.yml`). -    [`connections:`](#connections) | Optional | List of consumed and provided resources. -    [`processor:`](#processor) | Optional | Processor specific settings. -    [`linker:`](#linker) | Optional | Instructions for the linker. -    [`groups:`](#groups) | Optional | List of source file groups along with source files. -    [`components:`](#components) | Optional | List of software components used. - -**Example:** - -```yml -layer: - type: Board - description: Setup with Ethernet and WiFi interface - processor: - trustzone: secure # set processor to secure - components: - - component: Startup - - component: CMSIS CORE - groups: - - group: Secure Code - files: - - file: main_s.c - - group: CMSE - files: - - file: interface.c - - file: interface.h - - file: tz_context.c -``` - -## Directory Control - -The following nodes control the directory structure for the application. - -### `output-dirs:` - -Allows to control the directory structure for build output files. - -!!! Note - This control is only possible at `csolution.yml` level. - -Only relative paths to the base directory of the `csolution.yml` file are permitted. Use command line options of the `cbuild` tool to redirect the absolute path for this working directory. - -`output-dirs:` | | Content -:----------------------------------|--------------|:------------------------------------ -    `intdir:` | Optional | Specifies the directory for the interim files (temporary or object files) when using `cbuild` with option -    `outdir:` | Optional | Specifies the directory for the build output files (ELF, binary, MAP files). -    `tmpdir:` | Optional | Specifies the directory for the interim temporary files. - -The default setting for the `output-dirs:` are: - -```yml - tmpdir: tmp - outdir: $SolutionDir()$/out/$TargetType$ -``` - -**Example:** - -```yml -output-dirs: - intdir: ./tmp2 # relative path to csolution.yml file - outdir: ./out/$Project$/$TargetType$ # $BuildType$ no longer part of the outdir -``` - -### `generators:` - -Allows to control the directory structure for generator output files. - -When no explicit `generators:` is specified, the **`csolution` Project Manager** uses as path: - -- The `workingDir` defined in the [generators element](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/pdsc_generators_pg.html#element_generator) of the PDSC file. -- When no `workingDir` is defined the default directory `$ProjectDir()$/generated/` is used; `` is defined by the `id` in the generators element of the PDSC file. - -The `generators:` node can be added at various levels of the `*.yml` input files. The following order is used: - -1. Use `generators:` specification of the `*.clayer.yml` input file, if not exist: -2. Use `generators:` specification of the `*.cproject.yml` input file, if not exist: -3. Use `generators:` specification of the `*.csolution.yml` input file. - -!!! Notes - - Only relative paths are permitted to support portablity of projects. - - The location of the `*.yml` file that contains the `generators:` node is the reference for relative paths. - -`generators:` | | Content -:------------------------------|------------|:------------------------------------ -    `base-dir:` | Optional | Base directory for unspecified generators; default: `$ProjectDir()$/generated`. -    `options:` | Optional | Specific generator options; allows explicit directory configuration for a generator. - -!!! Note - -The base directory is extended for each generator with `/`; `` is defined by the `id` in the generators element of the PDSC file. - -#### `generators: - options:` - -`options:` | | Content -:------------------------------|------------|:------------------------------------ -`- generator:` | Optional | Identifier of the generator tool, specified with `id` in the [generators element](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/pdsc_generators_pg.html#element_generator) of the PDSC file. -    `path:` | Optional | Specifies the directory for generated files. Relative paths used location of `*.cproject.yml` or `*.clayer.yml` file as base directory. -    `name:` | Optional | Specifies the base name of the [generator import file](YML-CBuild-Format.md#generator-import-file) (added in CMSIS-Toolbox 2.4.0); typically used for a board layer. -    `map:` | Optional | Mapping of the *csolution project* to a generator specific run-time context name (added in CMSIS-Toolbox 2.4.0). - -**Example:** - -```yml -generators: - base-dir: $SolutionDir()$/MyGenerators # Path for all generators extended by '/' - - options: - - generator: CubeMX # for the generator id `CubeMX` use this path - path: ./CubeFiles # relative path to generated files and the generator import file - name: MyConf # results in generator import file ./CubeFiles/MyConf.cgen.yml - map: Boot # Map this project part to the CubeMX run-time context Boot -``` - -### `rte:` - -Allows to control the directory structure for [RTE (run-time environment)](build-overview.md#rte-directory-structure) files. - -!!! Notes - - This control is only possible at `*.cproject.yml` level. - - Only relative paths are permitted to support portablity of projects. - - The location of the `*.cproject.yml` file is the reference for relative paths. - -`rte:` | | Content -:------------------------------|------------|:------------------------------------ -    `base-dir:` | Optional | Base directory for unspecified generators; default: `$ProjectDir()$/RTE`. - -```yml -rte: - base-dir: $TargetType$/RTE # Path extended with target-type, results in `$ProjectDir()$/$TargetType$/RTE` -``` - -## Toolchain Options - -The following code translation options may be used at various places such as: - -- [`solution:`](#solution) level to specify options for a collection of related projects -- [`project:`](#projects) level to specify options for a project - -### `compiler:` - -Selects the compiler toolchain used for code generation. -Optionally the compiler can have a version number specification. - -Compiler Name | Supported Compiler -:-----------------------------------------------------|:------------------------------------ -`AC6` | Arm Compiler version 6 -`GCC` | GCC Compiler -`IAR` | IAR Compiler -`CLANG` | CLANG Compiler based on LLVM technlogy - -**Example:** - -```yml -compiler: GCC # Select GCC Compiler -``` - -```yml -compiler: AC6@6.18.0 # Select Arm Compiler version 6 -``` - -### `linker:` - -The `linker:` node specifies an explicit Linker Script and/or memory regions header file. It can be applied in `*.cproject.yml` and `*.clayer.yml` files. -Refer to [Linker Script Management](build-overview.md#linker-script-management) for detailed information. - -`linker:` | | Content -:-----------------------------------------------------------|:-----------|:-------------------------------- -`- regions:` | Optional | Path and file name of `.h`, used to generate a Linker Script. -   `script:` | Optional | Explicit file name of the Linker Script, overrules files provided with [`file:`](#files) or components. -   `auto:` | Optional | Request [automatic Linker Script generation](build-overview.md#automatic-linker-script-generation). -   [`define:`](#define) | Optional | Define symbol settings for the linker script file preprocessor. -   [`for-compiler:`](#for-compiler) | Optional | Include Linker Script for the specified toolchain. -   [`for-context:`](#for-context) | Optional | Include Linker Script for a list of *build* and *target* type names. -   [`not-for-context:`](#not-for-context) | Optional | Exclude Linker Script for a list of *build* and *target* type names. - -!!! Notes - - The `linker:` node must have at least `regions:`, `script:`, `auto:`, or `define:`. - - If no `script:` file is specified, compiler specific [Linker Script template files](build-overview.md#linker-script-templates) are used. - - A Linker Script file is preprocessed when `regions:` or a `define:` is or the file extension is `*.src`. - - If both `auto:` and `script:` is specified a warning is issued and [automatic Linker Script generation](build-overview.md#automatic-linker-script-generation) is performed and the specified `script:` is ignored. - -**Examples:** - -```yml -linker: - - script: MyLinker.scf.src # linker script file - regions: MyRegions.h # pre-processed using header file -``` - -```yml -linker: - - regions: MyRegions.h # Default linker script is used and pre-processed using header file -``` - -```yml -linker: - - script: MyLinker.scf.src # linker script file, not pre-processed - for-compiler: AC6 # for Arm Compiler 6 - - - script: MyLinker.ld # linker script file, not pre-processed - for-compiler: CLANG # for CLANG LLVM based compiler -``` - -```yml -linker: - - script: MyLinker.scf.src # linker script file - for-compiler: AC6 # for Arm Compiler 6 - regions: MyRegions.h # pre-processed using header file - - - script: MyLinker.ld.src # linker script file - for-compiler: CLANG # for CLANG LLVM based compiler - regions: MyRegions.h # pre-processed using header file - define: # with define setting - - Setup: 1 # define with value -``` - -### `output:` - -Configure the generated output files. - -`output:` | | Content -:--------------------------------------|:-----------|:-------------------------------- -    `base-name:` | Optional | Specify a common base name for all output files. -    `type:` | Optional | A list of output types for code generation (see list below). - -`type:` | Description -:-----------------|:------------- -`- lib` | Library or archive. Note: GCC uses the prefix `lib` in the base name for archive files. -`- elf` | Executable in ELF format. The file extension is toolchain specific. -`- hex` | Intel HEX file in HEX-386 format. -`- bin` | Binary image. - -The **default** setting for `output:` is: - -```yml -output: - base-name: $Project$ # used the base name of the `cproject.yml` file. - type: elf # Generate executeable file. -``` - -**Example:** - -```yml -output: # configure output files - base-name: MyProject # used for all output files, including linker map file. - type: - - elf # Generate executeable file. - - hex # generate a HEX file - - bin # generate a BIN file -``` - -Generate a **library**: - -```yml -output: # configure output files - type: lib # Generate library file. -``` - -## Translation Control - -The following translation control options may be used at various places such as: - -- [`solution:`](#solution) level to specify options for a collection of related projects -- [`project:`](#projects) level to specify options for a project -- [`groups:`](#groups) level to specify options for a specify source file group -- [`files:`](#files) level to specify options for a specify source file - -!!! Note - -- The keys `define:`, `add-path:`, `del-path:`, and `misc:` are additive. -- All other keys can only be defined once at the level of `solution:`, `project:`, `setup:`, `layer:`, `build-types:`. or `target-types:`. However, it is possible to overwrite these keys at the level of `group:`, `file:`, or `component:`, for example it is possible to translate a file group with a different optimize level. - -### `language-C:` - -Set the language standard for C source file compilation. - -Value | Select C Language Standard -:-----------------------------------------------------|:------------------------------------ -`c90` | compile C source files as defined in C90 standard (ISO/IEC 9899:1990). -`gnu90` | same as `c90` but with additional GNU extensions. -`c99` (default) | compile C source files as defined in C99 standard (ISO/IEC 9899:1999). -`gnu99` | same as `c99` but with additional GNU extensions. -`c11` | compile C source files as defined in C11 standard (ISO/IEC 9899:2011). -`gnu11` | same as `c11` but with additional GNU extensions. - -### `language-CPP:` - -Set the language standard for C++ source file compilation. - -Value | Select C++ Language Standard -:-----------------------------------------------------|:------------------------------------ -`c++98` | compile C++ source files as defined in C++98 standard (ISO/IEC 14882:1998). -`gnu++98` | same as `c++98` but with additional GNU extensions. -`c++03` | compile C++ source files as defined in C++03 standard (ISO/IEC 14882:2003). -`gnu++03` | same as `c++03` but with additional GNU extensions. -`c++11` | compile C++ source files as defined in C++11 standard (ISO/IEC 14882:2011). -`gnu++11` | same as `c++11` but with additional GNU extensions. -`c++14` (default) | compile C++ source files as defined in C++14 standard (ISO/IEC 14882:2014). -`gnu++14` | same as `c++14` but with additional GNU extensions. -`c++17` | compile C++ source files as defined in C++17 standard (ISO/IEC 14882:2014). -`gnu++17` | same as `c++17` but with additional GNU extensions. -`c++20` | compile C++ source files as defined in C++20 standard (ISO/IEC 14882:2020). -`gnu++20` | same as `c++20` but with additional GNU extensions. - -### `optimize:` - -Generic optimize levels for code generation. - -Value | Code Generation -:-----------------------------------------------------|:------------------------------------ -`balanced` | Balanced optimization -`size` | Optimized for code size -`speed` | Optimized for execution speed -`debug` | Optimize for debug experience -`none` | No optimization - -!!! Note - -- When `optimize:` is not specified, the default optimize setting of the compiler is used. - -**Example:** - -```yml -groups: - - group: "Main File Group" - optimize: none # optimize this file group for debug illusion - files: - - file: file1a.c - - file: file1b.c -``` - -### `debug:` - -Control the generation of debug information. - -Value | Code Generation -:-----------------------------------------------------|:------------------------------------ -`on` | Generate debug information (default) -`off` | Generate no debug information - -**Example:** - -```yml - build-types: - - type: Release - optimize: size # optimize for size - debug: off # generate no debug information for the release build -``` - -### `warnings:` - -Control warning level for compiler diagnostics. - -Value | Control diagnostic messages (warnings) -:-----------------------------------------------------|:------------------------------------ -`on` | Generate warning messages -`all` | Enable all compiler warning messages (compiler option -Wall) -`off` | No warning messages generated - -### `define:` - -Contains a list of symbol #define statements that are passed via the command line to the development tools for C, C++ source files, or the [linker](#linker) script file preprocessor. - -`define:` | Content -:-----------------------------------------------------------|:------------------------------------ -    `- ` | #define symbol passed via command line -    `- : ` | #define symbol with value passed via command line -    `- : \"\"` | #define symbol with string value passed via command line - ->**Note:** - -This control only applies to C and C++ source files (or to the [linker](#linker) script preprocessor). For assembler source files use the `misc:` node. - -**Example:** - -```yml -define: # Start a list of define statements - - TestValue: 12 # add symbol 'TestValue' with value 12 - - TestMode # add symbol 'TestMode' -``` - -### `undefine:` - -Remove symbol #define statements from the command line of the development tools. - -`undefine:` | Content -:----------------------------------------------------|:------------------------------------ -   `- ` | Remove #define symbol - -**Examples:** - -```yml -groups: - - group: "Main File Group" - undefine: - - TestValue # remove define symbol `TestValue` for this file group - files: - - file: file1a.c - undefine: - - TestMode # remove define symbol `TestMode` for this file - - file: file1b.c -``` - -### `add-path:` - -Add include paths to the command line of the development tools for C and C++ source files. - -`add-path:` | Content -:----------------------------------------------------------|:------------------------------------ -    `- ` | Named path to be added - ->**Note:** - -This control only applies to C and C++ source files. For assembler source files use the `misc:` node. - -**Example:** - -```yml -project: - misc: - - for-compiler: AC6 - C: [-fshort-enums, -fshort-wchar] - - for-compiler: GCC - C: [-fshort-enums, -fshort-wchar] - - add-path: - - $OutDir(Secure)$ # add path to secure project's output directory -``` - -### `del-path:` - -Remove include paths (that are defined at the cproject level) from the command line of the development tools. - -`del-paths:` | Content -:----------------------------------------------------------|:------------------------------------ -    `- ` | Named path to be removed; `*` for all - -**Examle:** - -```yml - target-types: - - type: CM3 - device: ARMCM3 - del-paths: - - /path/solution/to-be-removed -``` - -### `pre-include:` - -!!! Note - -**New in CMSIS-Toolbox 2.5.0; requires cbuild2cmake backend (todo) - -Add pre-include files to the command line of the development tools for C and C++ source files. - -`pre-include:` | Content -:----------------------------------------------------------|:------------------------------------ -    `- file:` | Name of the pre-include file. - -**Examle:** - -```yml - groups: - - group: MyGroup - pre-include: - - file: my_include.h -``` - -### `misc:` - -Add miscellaneous literal tool-specific controls that are directly passed to the individual tools depending on the file type. - -`misc:` | | Content -:------------------------------------------|--------------|:------------------------------------ -[`- for-compiler:`](#for-compiler) | Optional | Name of the toolchain that the literal control string applies to. -    `C-CPP:` | Optional | Applies to `*.c` and `*.cpp` files (added before `C` and `CPP:`). -    `C:` | Optional | Applies to `*.c` files only. -    `CPP:` | Optional | Applies to `*.cpp` files only. -    `ASM:` | Optional | Applies to assembler source files only. -    `Link:` | Optional | Applies to the linker (added before `Link-C:` or `Link-CPP:`). -    `Link-C:` | Optional | Applies to the linker; added when no C++ files are part of the project. -    `Link-CPP:` | Optional | Applies to the linker; added when C++ files are part of the project. -    `Library:` | Optional | Applies to the library manager or archiver. - -**Example:** - -```yml - build-types: - - type: Debug - misc: - - for-compiler: AC6 - C-CPP: - - -O1 - - -g - - for-compiler: GCC - C-CPP: - - -Og - - - type: Release - compiler: AC6 - misc: - - C: - - -O3 - - - type: GCC-LibDebug - compiler: GCC - misc: - - Library: - - -lm - - -lc - - -lgcc - - -lnosys -``` - -## Project Setups - -The `setups:` node can be used to create setups that are specific to a compiler, target-type, and/or built-type. - -### `setups:` - -The `setups:` node collects a list of `setup:` notes. For each context, only one setup will be selected. - -The result is a `setup:` that collects various toolchain options and that is valid for all files and components in the -project. It is however possible to change that `setup:` settings on a [`group:`](#groups) or [`file:`](#files) level. - -`setups:` | | Content -:----------------------------------------------------|:-------------|:------------------------------------ -`- setup:` | **Required** | Description of the setup -    [`for-context:`](#for-context) | Optional | Include group for a list of *build* and *target* types. -    [`not-for-context:`](#not-for-context) | Optional | Exclude group for a list of *build* and *target* types. -    [`for-compiler:`](#for-compiler) | Optional | Include group for a list of compilers. -    [`output:`](#output) | Optional | Configure the generated output files. -    [`language-C:`](#language-c) | Optional | Set the language standard for C source file compilation. -    [`language-CPP:`](#language-cpp) | Optional | Set the language standard for C++ source file compilation. -    [`pre-include:`](#pre-include) | Optional | Add pre-include files for C and C++ source files. -    [`optimize:`](#optimize) | Optional | Optimize level for code generation. -    [`debug:`](#debug) | Optional | Generation of debug information. -    [`warnings:`](#warnings) | Optional | Control generation of compiler diagnostics. -    [`define:`](#define) | Optional | Define symbol settings for code generation. -    [`undefine:`](#undefine) | Optional | Remove define symbol settings for code generation. -    [`add-path:`](#add-path) | Optional | Additional include file paths. -    [`del-path:`](#del-path) | Optional | Remove specific include file paths. -    [`linker:`](#linker) | Optional | Remove specific include file paths. -    [`misc:`](#misc) | Optional | Literal tool-specific controls. -    [`processor:`](#processor) | Optional | Processor configuration. - -```yml -project: - setups: - - setup: Arm Compiler 6 project setup - for-compiler: AC6 - linker: - - script: my-project.sct - define: - - test: 12 - - - setup: GCC project setup - for-compiler: GCC - linker: - - script: my-project.inc - define: - - test: 11 -``` - -## Pack Selection - -The `packs:` node can be specified in the `*.csolution.yml` file allows you to: - -- Reduce the scope of software packs that are available for projects. -- Add specific software packs optional with a version specification. -- Provide a path to a local installation of a software pack that is for example project specific or under development. - -The [Pack Name Conventions](#pack-name-conventions) are used to specify the name of the software packs. -The `pack:` definition may be specific to a [`context`](#context) that specifies `target-types:` and/or `build-types:` or provide a local path to a development repository of a software pack. - -!!! Notes - - By default, the **`csolution` Project Manager** only loads the latest version of the installed software packs. It is however possible to request specific versions using the `- pack:` node. - - An attempt to add two different versions of the same software pack results in an error. - -### `packs:` - -The `packs:` node is the start of a pack selection. - -`packs:` | Content -:-----------------------------------------------------|:------------------------------------ -    [`- pack:`](#pack) | Explicit pack specification (additive) - -### `pack:` - -The `pack:` list allows to add specific software packs, optional with a version specification. The version number can -have also the format `@~1.2`/`@~1` that matches with semantic versioning. - -`pack:` | Content -:-----------------------------------------------------------|:------------------------------------ -    `path:` | Explicit path name that stores the software pack. This can be a relative path to your project workspace. -    [`for-context:`](#for-context) | Include pack for a list of *build* and *target* types. -    [`not-for-context:`](#not-for-context) | Exclude pack for a list of *build* and *target* types. - -!!! Note - -- When an explicit `path:` to the pack is specified, an explicit pack version cannot be specified as the path directly specifies the pack to include. - -**Example:** - -```yml -packs: # start section that specifics software packs - - pack: AWS # use packs from AWS - - pack: NXP::*K32L* # use packs from NXP relating to K32L series (would match K32L3A60_DFP + FRDM-K32L3A6_BSP) - - pack: ARM # use packs from Arm - - - pack: Keil::Arm_Compiler # add latest version of Keil::Arm_Compiler pack - - pack: Keil::MDK-Middleware@7.13.0 # add Keil::MDK-Middleware pack at version 7.13.0 - - pack: ARM::CMSIS-FreeRTOS@~10.4 # add CMSIS-FreeRTOS with version 10.4.x - - - pack: NXP::K32L3A60_DFP # add pack for NXP device - path: ./local/NXP/K32L3A60_DFP # with path to the pack (local copy, repo, etc.) - - - pack: AWS::coreHTTP # add pack - path: ./development/AWS/coreHTTP # with path to development source directory - for-context: +DevTest # pack is only used for target-type "DevTest" -``` - -## Target Selection - -### `board:` - -Specifies a [unique board name](#board-name-conventions), optionally with vendor that must be defined in software packs. -This information is used to define the `device:` along with basic toolchain settings. - -### `device:` - -Specifies a [unique device name](#device-name-conventions), optionally with vendor that must be defined in software -packs. This information is used to define the `device:` along with basic toolchain settings. - -A `device:` is derived from the `board:` setting, but an explicit `device:` setting overrules the `board:` device. - -If `device:` specifies a device with a multi-core processor, and no explicit `pname` for the processor core selection is specified, the default `pname` of the device is used. - -At the level of a `cproject.yml` file, only the `pname` can be specified as the device itself is selected at the level of a `csolution.yml` file. - -## Processor Attributes - -### `processor:` - -The `processor:` keyword specifies the usage of processor features for this project. - -`processor:` | Content -:---------------------------------------|:------------------------------------ -    `fpu:` | Select usage of FPU instructions: `dp` (double precision) \| `sp` (single precision) \| `off` (disabled). -    `dsp:` | Select usage of SIMD instructions: `on` (enabled) \| `off` (disabled). -    `mve:` | Select usage of M-Profile vector extension: `fp` (floating point and integer instructions) \| `int` (integer instructions) \| `off` (disabled). -    `trustzone:` | Select TrustZone mode: `secure` \| `non-secure` \| `off`. -    `branch-protection:` | Select Branch Protection mode: `bti` (branch target identification) \| `bti-signret` (branch target identification and pointer authentication) \| `off` (disabled). - -The default setting enables the available features of the device. For example `fpu: dp` is selected for devices that offer double precision floating point hardware. - -For `trustzone:` the default setting is: - -- `off` for devices that support this option, but TrustZone is configurable. -- `non-secure` for devices that have TrustZone enabled. - -**Example:** - -```yml -project: - processor: - trustzone: secure - fpu: off # do not use FPU instructions - mve: off # do not use vector instructions. -``` - -## Context - -A [`context`](#context-name-conventions) is an enviroment setup for a project that is composed of: - -- `project-name` that is the base name of the `*.cproject.yml` file. -- `.build-type` that defines typically build specific settings such as for debug, release, or test. -- `+target-type` that defines typically target specific settings such as device, board, or usage of processor features. - - -The settings of the `target-types:` are processed first; then the settings of the `build-types:` that potentially overwrite the `target-types:` settings. - -### `target-types:` - -The `target-types:` node may include [toolchain options](#toolchain-options), [target selection](#target-selection), and [processor attributes](#processor-attributes): - -`target-types:` | | Content -:--------------------------------------------------|--------------|:------------------------------------ -`- type:` | **Required** | The target-type name that is used to create the [context](#context-name-conventions) name. -    [`compiler:`](#compiler) | Optional | Toolchain selection. -    [`language-C:`](#language-c) | Optional | Set the language standard for C source file compilation. -    [`language-CPP:`](#language-cpp)| Optional | Set the language standard for C++ source file compilation. -    [`pre-include:`](#pre-include) | Optional | Add pre-include files for C and C++ source files. -    [`optimize:`](#optimize) | Optional | Optimize level for code generation. -    [`debug:`](#debug) | Optional | Generation of debug information. -    [`warnings:`](#warnings) | Optional | Control Generation of debug information. -    [`define:`](#define) | Optional | Preprocessor (#define) symbols for code generation. -    [`undefine:`](#undefine) | Optional | Remove preprocessor (#define) symbols. -    [`add-path:`](#add-path) | Optional | Additional include file paths. -    [`del-path:`](#del-path) | Optional | Remove specific include file paths. -    [`misc:`](#misc) | Optional | Literal tool-specific controls. -    [`board:`](#board) | **see Note** | Board specification. -    [`device:`](#device) | **see Note** | Device specification. -    [`processor:`](#processor) | Optional | Processor specific settings. -    [`context-map:`](#context-map) | Optional | Use different `target-types:` for specific projects. -    [`variables:`](#variables) | Optional | Variables that can be used to define project components. - -**Note::** - -Either `device:` or `board:` is required. - -### `build-types:` - -The `build-types:` node may include [toolchain options](#toolchain-options): - -`build-types:` | | Content -:--------------------------------------------------|--------------|:------------------------------------ -`- type:` | **Required** | The build-type name that is used to create the [context](#context-name-conventions) name. -    [`compiler:`](#compiler) | Optional | Toolchain selection. -    [`language-C:`](#language-c) | Optional | Set the language standard for C source file compilation. -    [`language-CPP:`](#language-cpp)| Optional | Set the language standard for C++ source file compilation. -    [`pre-include:`](#pre-include) | Optional | Add pre-include files for C and C++ source files. -    [`optimize:`](#optimize) | Optional | Optimize level for code generation. -    [`debug:`](#debug) | Optional | Generation of debug information. -    [`define:`](#define) | Optional | Preprocessor (#define) symbols for code generation. -    [`undefine:`](#undefine) | Optional | Remove preprocessor (#define) symbols. -    [`add-path:`](#add-path) | Optional | Additional include file paths. -    [`del-path:`](#del-path) | Optional | Remove specific include file paths. -    [`misc:`](#misc) | Optional | Literal tool-specific controls. -    [`context-map:`](#context-map) | Optional | Use different `build-types:` for specific projects. -    [`variables:`](#variables) | Optional | Variables that can be used to define project components. - -**Example:** - -```yml -target-types: - - type: Board # target-type name, used in context with: +Board - board: NUCLEO-L552ZE-Q # board specifies indirectly also the device - - - type: Production-HW # target-type name, used in context with: +Production-HW - device: STM32L552RC # specifies device - -build-types: - - type: Debug # build-type name, used in context with: .Debug - optimize: none # specifies code optimization level - debug: debug # generates debug information - - - type: Test # build-type name, used in context with: .Test - optimize: size - debug: on -``` - -The `board:`, `device:`, and `processor:` settings are used to configure the code translation for the toolchain. These -settings are processed in the following order: - -1. `board:` relates to a BSP software pack that defines board parameters, including the - [mounted device](https://arm-software.github.io/CMSIS_5/Pack/html/pdsc_boards_pg.html#element_board_mountedDevice). - If `board:` is not specified, a `device:` must be specified. -2. `device:` defines the target device. If `board:` is specified, the `device:` setting can be used to overwrite the - device or specify the processor core used. -3. `processor:` overwrites default settings for code generation, such as endianess, TrustZone mode, or disable Floating - Point code generation. - -**Examples:** - -```yml -target-types: - - type: Production-HW - board: NUCLEO-L552ZE-Q # hardware is similar to a board (to use related software layers) - device: STM32L552RC # but uses a slightly different device - processor: - trustzone: off # TrustZone disabled for this project -``` - -```yml -target-types: - - type: Production-HW - board: FRDM-K32L3A6 # NXP board with K32L3A6 device - device: :cm0plus # use the Cortex-M0+ processor -``` - -### `context-map:` - -The `context-map:` node allows for a specific `project-name` the remapping of `target-types:` and/or `build-types:` to a different `context:` which enables: - -- Integrating an existing `*.cproject.yml` file in a different `*.csolution.yml` file that uses different `build-types:` and/or `target-types:` for the overall application. -- Defines how different `*.cproject.yml` files of a `*.csolution.yml` are to the binary image of the final target (needs reflection in cbuild-idx.yml). - -The `context-map:` node lists a remapping of the [`context-name`](#context-name-conventions) for a `project-name` and specific `target-types:` and `build-types:`. - -`context-map:` | | Content -:--------------------------------------------------|--------------|:------------------------------------ -    `- ` | **Required** | Specify an alternative [`context-name`](#context-name-conventions) for a project. - -For the `context-map:` it is required to specify the `` as part of the [`context-name`](#context-name-conventions). This project will use a different `.build-type` and/or `+target-type` as applied in the [`context-name`](#context-name-conventions). This remapping of the context applies for the specific type in the `build-types:` or `target-types:` list. - -**Example 1:** - -This application combines two projects for a multi-processor device, but the project `HelloCM7` requires a different setting for the build-type name `Release` as this enables different settings within the `*.cproject.yml` file. - -```yml - target-types: - - type: DualCore - device: MyDualCoreDevice - - build-types: - - type: Release # When applying build-type name 'release': - context-map: - - HelloCM7.flex_release # project HelloCM7 uses build-type name "flex_release" instead of "release" - - projects: - - project: ./CM7/HelloCM7.cproject.yml - - project: ./CM4/HelloCM4.cproject.yml -``` - -**Example 2:** - -The following example uses three projects `Demo`, `TFM` and `Boot`. The project `TFM` should be always build using the context `TFM.Release+LibMode`. For the target-type name `Board`, the Boot project requires the `+Flash` target, but any build-type could be used. - -```yml - target-types: - - type: Board # When applying target-type: 'Board': - context-map: - - TFM.Release+LibMode # for project TFM use build-type: Release, target-type: LibMode - - Boot+Flash # for project Boot use target-type: Flash - board: B-U585I-IOT02A - - type: AVH # When applying target-type: 'AVH': - context-map: - - context: TFM.Release+LibMode # for project TFM use build-type: Release, target-type: LibMode - device: ARM::SSE-300-MPS3 - - projects: - - project: ./App/Demo.cproject.yml - - project: ./Security/TFM.cproject.yml - - project: ./Loader/Boot.cproject.yml -``` - -## Conditional Build - -It is possible to include or exclude *items* of a [*list node*](#order-of-list-nodes) in the build process. - -- [`for-compiler:`](#for-compiler) includes *items* only for a compiler toolchain. -- [`for-context:`](#for-context) includes *items* only for a [*context*](#context-name-conventions) list. -- [`not-for-context:`](#not-for-context) excludes *items* for a [*context*](#context-name-conventions) list. - -!!! Note - -`for-context` and `not-for-context` are mutually exclusive, only one occurrence can be specified for a - *list node*. - -### `for-compiler:` - -Depending on a [compiler](#compiler) toolchain it is possible to include *list nodes* in the build process. - -**Examples:** - -```yml -for-compiler: AC6@6.16 # add item for Arm Compiler version 6.16 only - -for-compiler: GCC # for GCC Compiler (any version) -``` - -### `for-context:` - -A [*context*](#context-name-conventions) list that adds a list-node for specific `target-type` and/or `build-type` names. - -### `not-for-context:` - -A [*context*](#context-name-conventions) list that removes a list-node for specific `target-types:` and/or `build-types:`. - -### Context List - -It is also possible to provide a [`context`](#context-name-conventions) list with: - -```yml - - [.build-type][+target-type] - - [.build-type][+target-type] -``` - -**Examples:** - -```yml -for-context: - - .Test # add item for build-type: Test (any target-type) - -for-context: # add item - - .Debug # for build-type: Debug and - - .Release+Production-HW # build-type: Release / target-type: Production-HW - -not-for-context: +Virtual # remove item for target-type: Virtual (any build-type) -not-for-context: .Release+Virtual # remove item for build-type: Release with target-type: Virtual -``` - -### Usage - -The keyword `for-context:` and `not-for-context:` can be applied to the following *list nodes*: - -List Node | Description -:------------------------------------------|:------------------------------------ -[`- project:`](#projects) | At `projects:` level it is possible to control inclusion of project. -[`- layer:`](#layers) | At `layers:` level it is possible to control inclusion of a software layer. - -The keyword `for-context:`, `not-for-context:`, and `for-compiler:` can be applied to the following *list nodes*: - -List Node | Description -:------------------------------------------|:------------------------------------ -[`- component:`](#components) | At `components:` level it is possible to control inclusion of a software component. -[`- group:`](#groups) | At `groups:` level it is possible to control inclusion of a file group. -[`- setup:`](#setups) | At `setups:` level it is define toolchain specific options that apply to the whole project. -[`- file:`](#files) | At `files:` level it is possible to control inclusion of a file. - -The inclusion of a *list node* is processed for a given project [*context*](#context-name-conventions) respecting its hierarchy from top to bottom: - -`project` --> `layer` --> `component`/`group` --> `file` - -In other words, the restrictions specified by `for-context:` or `not-for-context` for a *list node* are automatically applied to its children nodes. Children *list nodes* inherit the restrictions from their parent. - -## Multiple Projects - -The section [Project setup for related projects](build-overview.md#project-setup-for-related-projects) describes the -organization of multiple projects. The file `*.csolution.yml` describes the relationship of this projects and may also re-map -`target-types:` and `build-types:` for this projects using [`context-map:`](#context-map). - -### `projects:` - -The YAML structure of the section `projects:` is: - -`projects:` | | Content -:---------------------------------------------------------|--------------|:------------------------------------ -[`- project:`](#project) | **Required** | Path to the project file. -    [`for-context:`](#for-context) | Optional | Include project for a list of *build* and *target* types. -    [`not-for-context:`](#not-for-context) | Optional | Exclude project for a list of *build* and *target* types. - -**Examples:** - -This example uses two projects that are build in parallel using the same `build-type:` and `target-type:`. Such a setup is typical for multi-processor systems. - -```yml - projects: - - project: ./CM0/CM0.cproject.yml # include project for Cortex-M0 processor - - project: ./CM4/CM4.cproject.yml # include project for Cortex-M4 processor -``` - -This example uses multiple projects, but with additional controls. - -```yml - projects: - - project: ./CM0/CM0.cproject.yml # specify cproject.yml file - for-context: +CM0-Addon # build only when 'target-type: CM0-Addon' is selected - for-compiler: GCC # build only when 'compiler: GCC' is selected - define: # add additional defines during build process - - test: 12 - - - project: ./CM0/CM0.cproject.yml # specify cproject.yml file - for-context: +CM0-Addon # specify use case - for-compiler: AC6 # build only when 'compiler: AC6' is selected - define: # add additional defines during build process - - test: 9 - - - project: ./Debug/Debug.cproject.yml # specify cproject.yml file - not-for-context: .Release # generated for any 'build-type:' except 'Release' -``` - -## Source File Management - -Keyword | Used in files | Description -:----------------|:---------------------------------|:------------------------------------ -`groups:` | `*.cproject.yml`, `*.clayer.yml` | Start of a list that adds [source groups and files](#source-file-management) to a project or layer. -`layers:` | `*.cproject.yml` | Start of a list that adds software layers to a project. -`components:` | `*.cproject.yml`, `*.clayer.yml` | Start of a list that adds software components to a project or layer. - -### `groups:` - -The `groups:` keyword specifies a list that adds [source groups and files](#source-file-management) to a project or layer: - -`groups:` | | Content -:---------------------------------------------------------|--------------|:------------------------------------ -`- group:` | **Required** | Name of the group. -    [`for-context:`](#for-context) | Optional | Include group for a list of *build* and *target* types. -    [`not-for-context:`](#not-for-context) | Optional | Exclude group for a list of *build* and *target* types. -    [`for-compiler:`](#for-compiler) | Optional | Include group for a list of compilers. -    [`language-C:`](#language-c) | Optional | Set the language standard for C source file compilation. -    [`language-CPP:`](#language-cpp) | Optional | Set the language standard for C++ source file compilation. -    [`pre-include:`](#pre-include) | Optional | Add pre-include files for C and C++ source files. -    [`optimize:`](#optimize) | Optional | Optimize level for code generation. -    [`debug:`](#debug) | Optional | Generation of debug information. -    [`warnings:`](#warnings) | Optional | Control generation of compiler diagnostics. -    [`define:`](#define) | Optional | Define symbol settings for code generation. -    [`undefine:`](#undefine) | Optional | Remove define symbol settings for code generation. -    [`add-path:`](#add-path) | Optional | Additional include file paths. -    [`del-path:`](#del-path) | Optional | Remove specific include file paths. -    [`misc:`](#misc) | Optional | Literal tool-specific controls. -    [`groups:`](#groups) | Optional | Start a nested list of groups. -    [`files:`](#files) | Optional | Start a list of files. - -**Example:** - -See [`files:`](#files) section. - -### `files:` - -Add source files to a project. - -`files:` | | Content -:---------------------------------------------------------|--------------|:------------------------------------ -`- file:` | **Required** | Name of the file. -    [`for-context:`](#for-context) | Optional | Include file for a list of *build* and *target* types. -    [`not-for-context:`](#not-for-context) | Optional | Exclude file for a list of *build* and *target* types. -    [`for-compiler:`](#for-compiler) | Optional | Include file for a list of compilers. -    [`category:`](#filename-extensions) | Optional | Explicit file category to overwrite [filename extension](#filename-extensions) assignment. -    [`language-C:`](#language-c) | Optional | Set the language standard for C source file compilation. -    [`language-CPP:`](#language-cpp) | Optional | Set the language standard for C++ source file compilation. -    [`pre-include:`](#pre-include) | Optional | Add pre-include files for C and C++ source files. -    [`optimize:`](#optimize) | Optional | Optimize level for code generation. -    [`debug:`](#debug) | Optional | Generation of debug information. -    [`warnings:`](#warnings) | Optional | Control generation of compiler diagnostics. -    [`define:`](#define) | Optional | Define symbol settings for code generation. -    [`undefine:`](#undefine) | Optional | Remove define symbol settings for code generation. -    [`add-path:`](#add-path) | Optional | Additional include file paths. -    [`del-path:`](#del-path) | Optional | Remove specific include file paths. -    [`misc:`](#misc) | Optional | Literal tool-specific controls. - -!!! Note - -It is also possible to specify a [Linker Script](build-overview.md#linker-script-management). Files with the extension `.sct`, `.scf`, `.ld`, and `.icf` are recognized as Linker Script files. - -**Example:** - -Add source files to a project or a software layer. Used in `*.cproject.yml` and `*.clayer.yml` files. - -```yml -groups: - - group: "Main File Group" - not-for-context: # includes this group not for the following: - - .Release+Virtual # build-type 'Release' and target-type 'Virtual' - - .Test-DSP+Virtual # build-type 'Test-DSP' and target-type 'Virtual' - - +Board # target-type 'Board' - files: - - file: file1a.c - - file: file1b.c - define: - - a: 1 - undefine: - - b - optimize: size - - - group: "Other File Group" - files: - - file: file2a.c - for-context: +Virtual # include this file only for target-type 'Virtual' - define: - - test: 2 - - file: file2a.c - not-for-context: +Virtual # include this file not for target-type 'Virtual' - - file: file2b.c - - - group: "Nested Group" - groups: - - group: Subgroup1 - files: - - file: file-sub1-1.c - - file: file-sub1-2.c - - group: Subgroup2 - files: - - file: file-sub2-1.c - - file: file-sub2-2.c -``` - -It is also possible to include a file group for a specific compiler using [`for-compiler:`](#for-compiler) or a specific -target-type and/or build-type using [`for-context:`](#for-context) or [`not-for-context:`](#not-for-context). - -```yml -groups: - - group: "Main File Group" - for-compiler: AC6 # includes this group only for Arm Compiler 6 - files: - - file: file1a.c - - file: file2a.c - - - group: "Main File Group" - for-compiler: GCC # includes this group only for GCC Compiler - files: - - file: file1b.c - - file: file2b.c -``` - -### `layers:` - -Add a software layer to a project. Used in `*.cproject.yml` files. - -`layers:` | | Content -:---------------------------------------------------------|--------------|:------------------------------------ -[`- layer:`](#layer) | Optional | Path to the `*.clayer.yml` file that defines the layer. -    [`type:`](#layer-type) | Optional | Refers to an expected layer type. -    [`for-context:`](#for-context) | Optional | Include layer for a list of *build* and *target* types. -    [`not-for-context:`](#not-for-context) | Optional | Exclude layer for a list of *build* and *target* types. - -**Example:** - -```yml - layers: - # Socket - - layer: ./Socket/FreeRTOS+TCP/Socket.clayer.yml - for-context: - - +IP-Stack - - layer: ./Socket/WiFi/Socket.clayer.yml - for-context: - - +WiFi - - layer: ./Socket/VSocket/Socket.clayer.yml - for-context: - - +AVH - - # Board - - layer: ./Board/IMXRT1050-EVKB/Board.clayer.yml - for-context: - - +IP-Stack - # - +WiFi - - layer: ./Board/B-U585I-IOT02A/Board.clayer.yml - for-context: - - +WiFi - - layer: ./Board/AVH_MPS3_Corstone-300/Board.clayer.yml - for-context: - - +AVH -``` - -#### `layer:` `type:` - -The `layer:` `type:` is used in combination with the meta-data of the [`connections:`](#connections) to check the list of available `*.clayer.yml` files for matching layers. Instead of an explicit `layer:` node that specifies a `*.clayer.yml` file, the `type:` is used to search for matching layers with the `csolution` command `list layers`. - -**Example:** - -```yml - layers: - - type: Socket # search for matching layers of type `Socket` - - - type: Board # search for matching layers of type `Board` -``` - -When combined with [`variables:`](#variables) it is possible to define the required `*.clayer.yml` files at the level of the `*.csolution.yml` file. Refer to [`variables:`](#variables) for an example. - -### `components:` - -Add software components to a project or a software layer. Used in `*.cproject.yml` and `*.clayer.yml` files. - -`components:` | | Content -:---------------------------------------------------------|--------------|:------------------------------------ -`- component:` | **Required** | Name of the software component. -    [`for-context:`](#for-context) | Optional | Include component for a list of *build* and *target* types. -    [`not-for-context:`](#not-for-context) | Optional | Exclude component for a list of *build* and *target* types. -    [`language-C:`](#language-c) | Optional | Set the language standard for C source file compilation. -    [`language-CPP:`](#language-cpp) | Optional | Set the language standard for C++ source file compilation. -    [`pre-include:`](#pre-include) | Optional | Add pre-include files for C and C++ source files. -    [`optimize:`](#optimize) | Optional | Optimize level for code generation. -    [`debug:`](#debug) | Optional | Generation of debug information. -    [`warnings:`](#warnings) | Optional | Control generation of compiler diagnostics. -    [`define:`](#define) | Optional | Define symbol settings for code generation. -    [`undefine:`](#undefine) | Optional | Remove define symbol settings for code generation. -    [`add-path:`](#add-path) | Optional | Additional include file paths. -    [`del-path:`](#del-path) | Optional | Remove specific include file paths. -    [`misc:`](#misc) | Optional | Literal tool-specific controls. -    [`instances:`](#instances) | Optional | Add multiple instances of component configuration files (default: 1) - -**Example:** - -```yml - components: - - component: ARM::CMSIS:RTOS2:FreeRTOS&Cortex-M - - - component: ARM::RTOS&FreeRTOS:Config&CMSIS RTOS2 - - component: ARM::RTOS&FreeRTOS:Core&Cortex-M - - component: ARM::RTOS&FreeRTOS:Event Groups - - component: ARM::RTOS&FreeRTOS:Heap&Heap_5 - - component: ARM::RTOS&FreeRTOS:Stream Buffer - - component: ARM::RTOS&FreeRTOS:Timers - - - component: ARM::Security:mbed TLS - define: - - MBEDTLS_CONFIG_FILE: "aws_mbedtls_config.h" - - component: AWS::FreeRTOS:backoffAlgorithm - - component: AWS::FreeRTOS:coreMQTT - - component: AWS::FreeRTOS:coreMQTT Agent - - component: AWS::FreeRTOS:corePKCS11&Custom - define: - - MBEDTLS_CONFIG_FILE: "aws_mbedtls_config.h" -``` - -!!! Note - -The name format for a software component is described under [Name Conventions - Component Name Conventions](#component-name-conventions). - -### `instances:` - -Allows to add multiple instances of a component and actually applies to configuration files. -For detailed description refer to [Open-CMSIS-Pack specification - Component Instances](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/pdsc_components_pg.html#Component_Instances) - -**Example:** - -```yml - components: - - component: USB:Device - instances: 2 -``` - -If the user selects multiple instances of the same component, all files with attribute `config` in the `*.PDSC` file -will be copied multiple times to the project. The name of the component (for example config_mylib.h) will get a postfix -`_n` whereby `n` is the instance number starting with 0. - -- Instance 0: `config_usb_device_0.h` -- Instance 1: `config_usb_device_1.h` - -The availability of instances in a project can be made public in the `RTE_Components.h` file. The existing way to extend -the `%Instance%` with the instance number `n`. - -## Pre/Post build steps - -The CMSIS-Toolbox supports pre-build and post-build steps that utilize external tools or scripts. Such external commands can be used for various tasks such as: - -- pre-process source files. -- add checksums to a binary file. -- combine multiple ELF files into a single image. -- add a timestamp to an image (`always:` ensures execution in every build). -- sign images for a boot laoder. - -### `executes:` - -Execute and external command for pre or post build steps used in `*.csolution.yml` and `*.cproject.yml` files. The `input:` and `output:` files are used for dependency checking and schedule the execution (as pre-build or post-build step) during the build process. - -The structure of the `executes:` node is: - -`executes:` | | Content -:-------------------------------------------|:-------------|:------------------------------------ -`- execute:` | **Required** | Description of the build step. -    `run:` | **Required** | Command string with name of the program or script (optionally with path) along with argument string. -    `always:` | Optional | When present, the build step always runs and bypasses check for outdated `output:` files. -    `input:` | Optional | A list of input files (may contain [Access Sequences](#access-sequences)). -    `output:` | Optional | A list of output files (may contain [Access Sequences](#access-sequences)). -    [`for-context:`](#for-context) | Optional | Run command for a list of *build* and *target* types (only supported in `*.cproject.yml`). -    [`not-for-context:`](#not-for-context) | Optional | Exclude run command for a list of *build* and *target* types (only supported in `*.cproject.yml`). - -The `run:` command string uses these sequences to access input files and output files: - -`run:` command file access | Description -:-------------------------------------------|:------------------------------------------------- -`$input$` | Comma separated list of all input files. -`$input()$` | Input file in the list with index ``; first item is `=0`. -`$output$` | Comma separated list of all output files. -`$output()$` | Output file in the list with index ``; first item is `=0`. - -**Examples:** - -```yml -solution: # executed as part of a project build - executes: - - execute: Generate Download Image - run: gen_image $input$ -o $output$ --sign # Command line string - input: - - $elf(Application)$ # combine these project parts - - $elf(TFM)$ - - $elf(Bootloader)$ - output: - - $SolutionDir$/$Solution$.out # output file name -``` - -```yml -project: # executed as part of a project build - executes: - - execute: Generate Encryption Keys - run: KeyGen $input$ -o $output$ - always: # always generate the keyfile.c as it contains a timestamp - input: keyfile.txt # contains the key in text format - output: keyfile.c # output as C source file that is part of this project -``` - -```yml -solution: # executed as part of a solution build - executes: # uses a CMake script - - execute: Archive Artifacts - run: ${CMAKE_COMMAND} -DINPUT=$input$ -DOUTPUT=$output$ -P $input(0)$ - always: - input: - - script/archive.cmake - - $elf(project.Release+ARMCM0)$ - - $elf(project.Release+ARMCM0)$.signed - - $elf(bootloader.Release+ARMCM0)$ - output: - - $SolutionDir()$/artifacts.zip -``` - -```yml -project: # executed as part of a project build - executes: # uses a CMake script - - execute: Sign ELF Image - run: ${CMAKE_COMMAND} -DINPUT=$input(1)$ -DOUTPUT=$output$ -P $input(0)$ - input: - - $SolutionDir()$/script/sign.cmake #CMake script - - $elf()$ # ELF file generated by project - output: - - $elf()$.signed - for-context: # only for build-type: Release - - .Release -``` - -## `connections:` - -The `connections:` node contains meta-data that describes the compatiblity of `*.cproject.yml` and `*.clayer.yml` project parts. The `connections:` node lists functionality (drivers, pins, and other software or hardware resources). The node `consumes:` lists required functionality; the node `provides:` is the implemented functionality of that project part. - -This enables [reference applications](ReferenceApplications.md) that work across a range of different hardware targets where: - -- The `*.cproject.yml` file of the reference application lists with the `connections:` node the required functionality with `consumes:`. - -- The `*.clayer.yml` project part lists with the `connections:` node the implemented functionality with `provides:`. - -This works across multiple levels, which means that a `*.clayer.yml` file could also require other functionality using `consumes:`. - -The `connections:` node is used to identify compatible software layers. These software layers could be stored in CMSIS software packs using the following structure: - -- A reference application described in a `*.cproject.yml` file could be provided in a git repository. This reference application uses software layers that are provided in CMSIS software packs. - -- A CMSIS Board Support Pack (BSP) contains a configured board layer desribed in a `*.clayer.yml` file. This software layer is pre-configured for a range of use-cases and provides drivers for I2C and SPI interfaces along with pin definitions and provisions for an Ardunio shield. - -- For a sensor, a CMSIS software pack contains the sensor middleware and software layer (`*.clayer.yml`) that describes the hardware of the Ardunio sensor shield. This shield can be applied to many different hardware boards that provide an Ardunio shield connector. - -This `connections:` node enables therefore software reuse in multiple ways: - -- The board layer can be used by many different reference applications, as the `provided:` functionlity enables a wide range of use cases. - -- The sensor hardware shield along with the middleware can be used across many different boards that provide an Ardunio shield connector along with board layer support. - -The structure of the `connections:` node is: - -`connections:` | | Description -:------------------------------------|--------------|:------------------------------------ -[- `connect:`](#connect) | **Required** | Lists specific functionality with a brief verbal description - -### `connect:` - -The `connect:` node describes one or more functionalities that belong together. - -`connect:` | | Description -:------------------------------------|--------------|:------------------------------------ -[`set:`](#set) | Optional | Specifies a *config-id*.*select* value that identifies a configuration option -`info:` | Optional | Verbal desription displayed when this connect is selected -[`provides:`](#provides) | Optional | List of functionality (*key*/*value* pairs) that are provided -[`consumes:`](#consumes) | Optional | List of functionality (*key*/*value* pairs) that are required - -### `set:` - -Some hardware boards have configuration settings (DIP switch or jumper) that configure interfaces. These settings have impact to the functionality (for example hardware interfaces). With `set:` *config-id*.*select* the possible configration options are considered when evaluating compatible `*.cproject.yml` and `*.clayer.yml` project parts. The **`csolution` Project Manager** iterates the `connect:` node with a `set:` *config-id*.*select* as described below: - -- For each *config-id* only one `connect:` node with a *select* value is active at a time. Each possible *select* value is checked for a matching configuration. - -- When project parts have a matching configuration, the `set:` value along with the `info:` is shown to the user. This allows the user to enable the correct hardware options. - -Refer to [Example: Sensor Shield](#example-sensor-shield) for a usage example. - -### `provides:` - -A user-defined *key*/*value* pair list of functionality that is implemented or provided by a `project:` or `layer:`. - -The **`csolution` Project Manager** combines all the *key*/*value* pairs that listed under `provides:` and matches it with the *key*/*value* pairs that are listed under `consumes:`. For *key*/*value* pairs listed under `provides:` the following rules exist for a match with `consumes:` *key*/*value* pair: - -- It is possible to omit the *value*. It matches with an identical *key* listed in `consumes:` -- A *value* is interpreted as number. Depending on the value prefix, this number must be: - - when `consumes:` *value* is a plain number, identical with this value. - - when `consumes:` *value* is prefixed with `+`, higher or equal then this *value* or the sum of all *values* in multiple `consumes:` nodes. - -### `consumes:` - -A user-defined *key*/*value* pair list of functionality that is requried or consumed by a `project:` or `layer:`. - -For *key*/*value* pairs listed under `consumed:` the following rules exist: - -- When no *value* is specified, it matches with any *value* of an identical *key* listed under `provides:`. -- A *value* is interpreted as number. This number must be identical in the `provides:` value pair. -- A *value* that is prefixed with `+` is interpreted as a number that is added together in case that the same *key* is listed multiple times under `consumes:`. The sum of this value must be lower or equal to the *value* upper limit of the `provides:` *key*. - -### Example: Board - -This `connections:` node of a board layer describes the available interfaces. The WiFi interface requires a CMSIS-RTOS2 function. - -```yml - connections:   # describes functionality of a board layer - - connect: WiFi interface - provides: - - CMSIS-Driver WiFi: - requires: - - CMSIS-RTOS2: - - - connect: SPI and UART interface - provides: - - CMSIS-Driver SPI: - - CMSIS-Driver UART: -``` - -### Example: Simple Project - -This shows a the `connections:` node of a complete application project that is composed of two software layers. - -*MyProject.cproject.yml* - -```yml - connections: - - connect: all resources - provides: - - RTOS2: # implements RTOS2 API interface - consumes: - - IoT_Socket: # requires IoT_Socket interface - - STDOUT: # requires STDOUT interface - - Heap: +30000 # requires additional 30000 bytes memory heap - : - layers: - - layer: MySocket.clayer.yml - - layer: MyBoard.clayer.yml -``` - -*MySocket.clayer.yml* - -```yml - connections: - - connect: - consumes: - - RTOS2: # requires RTOS2 API interface - - VSocket: # requires VSocket interface - - Heap: +20000 # requires additional 20000 bytes memory heap - provides: - - IoT_Socket: # provides IoT_Socket interface -``` - -*MyBoard.clayer.yml* - -```yml - connections: - - connect: - consumes: - - RTOS2: - provides: - - VSocket: - - STDOUT: - - Heap: 65536 -``` - -### Example: Sensor Shield - -This sensor shield layer provides a set of interfaces that are configurable. - -```yml - connections: -   - connect: I2C Interface 'Std' -    set: comm.I2C-Std - info: JP1=Off  JP2=Off - provides: -    - Sensor_I2C: -      consumes: -        - Ardunio_Uno_I2C: - -    - connect: I2C Interface 'Alt' -    set: comm.I2C-Alt - info: JP1=On  JP2=Off - provides: -    - Sensor_I2C: -      consumes: -        - Ardunio_Uno_I2C-Alt: - -    - connect: SPI Interface 'Alt' -    set: comm.SPI - info: JP2=On - provides: -    - Sensor_SPI: -      consumes: -        - Ardunio_Uno_SPI: - -   - connect: Sensor Interrupt INT0 -    set: SensorIRQ.0 - info: JP3=Off -     provides: -      - Sensor_IRQ: -   consumes: -      - Ardunio_Uno_D2: - -   - connect: Sensor Interrupt INT1 -    set: SensorIRQ.1 - info: JP3=On -     provides: -      - Sensor_IRQ: -   consumes: -      - Ardunio_Uno_D3: -``` diff --git a/docs/YML-Input-Format.md b/docs/YML-Input-Format.md index 500ed38..a31f235 100644 --- a/docs/YML-Input-Format.md +++ b/docs/YML-Input-Format.md @@ -1,4 +1,4 @@ -# CMSIS Solution Project File Format +# CSolution Project Format @@ -394,14 +394,13 @@ When [`cdefault:`](#solution) is specified in the `*.csolution.yml` file, the ** the compiler with specific default controls. The search order for this file is: - A [`cdefault.yml`](build-overview.md#cdefaultyml) file in the same directory as the `.csolution.yml` file. -- A [`cdefault.yml`](build-overview.md#cdefaultyml) file in the directory specified by the environment variable [`CMSIS_COMPILER_ROOT`](https://github.com/Open-CMSIS-Pack/cmsis-toolbox/blob/main/docs/installation.md#environment-variables). -- A [`cdefault.yml`](build-overview.md#cdefaultyml) file in the directory [`/etc`](https://github.com/Open-CMSIS-Pack/cmsis-toolbox/blob/main/docs/installation.md##etccmake). +- A [`cdefault.yml`](build-overview.md#cdefaultyml) file in the directory [`/etc`](installation.md#environment-variables). The `default:` node is the start of a [`cdefault.yml`](build-overview.md#cdefaultyml) file and contains the following. `default:` | | Content :---------------------------------------------------------|:-----------|:------------------------------------ -   [`misc:`](#misc) | Optional | Literal tool-specific controls. Refer to [Build Overview - `cdefault.yml`](build-overview.md#cdefaultyml) for an example. +   [`misc:`](#misc) | Optional | Literal tool-specific controls. Refer to [CSolution Project Structure - `cdefault.yml`](build-overview.md#cdefaultyml) for an example. !!! Note The [`compiler:`](#compiler) selection in `cdefault.yml` has been deprecated in CMSIS-Toolbox 2.6.0. diff --git a/docs/build-operation.md b/docs/build-operation.md index 665674e..cfb162b 100644 --- a/docs/build-operation.md +++ b/docs/build-operation.md @@ -56,7 +56,7 @@ Typical IDE environments use a `--context-set` that specifies the [context](buil - Check correctness of all files specified by `.csolution.yml`. - Evaluate the potential [software layers](YML-CBuild-Format.md#configurations) for [Reference Applications](ReferenceApplications.md) using `variables:` to refer to layers (if the value is undefined). All projects are considered in this step. - Evaluate the [selectable compiler toolchains](YML-CBuild-Format.md#select-compiler) when the *csolution project* does not contain a `compiler:` selection or the `--toolchain` option is not applied. The available toolchains are based on the [compiler registration](installation.md#compiler-registration) and the `select-compiler:` node in the file [`.csolution.yml`](YML-Input-Format.md#solution) or [`cdefault.yml`](YML-Input-Format.md#cdefault). -- Create the file `compile_commands.json` in the [output directory](build-overview.md#output-directory-structure) for the context defined in [`*.cbuild-set.yml`](YML-CBuild-Format.md#cbuild-output-files). +- Create the file `compile_commands.json` in the [output directory](build-overview.md#output-directory-structure) for the context defined in [`*.cbuild-set.yml`](YML-CBuild-Format.md). !!! Note The file `compile_commands.json` is generated by `CMake` with the option `--target -database` and contains all source files of the `context` along with compiler options. It is used by the [IntelliSense](https://code.visualstudio.com/docs/editor/intellisense) system of an IDE. @@ -64,7 +64,7 @@ Typical IDE environments use a `--context-set` that specifies the [context](buil The operation is further controlled by options: - The option `--packs` downloads missing software packs. -- The option `--context-set` restricts the operation to the [`context-set`](build-overview.md#working-with-context-set) selected by the file [`.cbuild-set.yml`](YML-CBuild-Format.md#cbuild-output-files). If this file is missing a file `.cbuild-set.yml` with selection of the first `target-type`, the first `build-type`, and first `project` that is specified in the file `.csolution.yml` is created. +- The option `--context-set` restricts the operation to the [`context-set`](build-overview.md#working-with-context-set) selected by the file [`.cbuild-set.yml`](YML-CBuild-Format.md). If this file is missing a file `.cbuild-set.yml` with selection of the first `target-type`, the first `build-type`, and first `project` that is specified in the file `.csolution.yml` is created. - The option [`--update-rte`](build-overview.md#rte-directory-structure) updates the configuration files of the application. - With the option `--frozen-packs` the file `*.cbuild-pack.yml` is used as input. An error is issued when a pack version changes. - The option `--toolchain` can be used to explicitly select a compiler. @@ -245,11 +245,11 @@ solution: ## Generator Integration -The diagram below shows how a generator is integrated into the CMSIS build process. The data flow is exemplified on STM32CubeMX (Generator ID for this example is `CubeMX`). The information about the project is delivered to the generator using the [Generator Information](YML-CBuild-Format.md#generator-information-files) files (`.cbuild-gen-idx.yml` and `.cbuild-gen.yml`). This information provides `CubeMX` with the project context, such as selected board or device, and CPU mode such as TrustZone disabled/enabled. +The diagram below shows how a generator is integrated into the CMSIS build process. The data flow is exemplified on STM32CubeMX (Generator ID for this example is `CubeMX`). The information about the project is delivered to the generator using the [Generator Information](YML-CBuild-Format.md#generator-information-files) files (`.cbuild-gen-idx.yml` and `.cbuild-gen.yml`). This information provides `CubeMX` with the project context, such as selected board or device, and CPU mode such as TrustZone disabled/enabled. ![Generator Integration](./images/Generator-Integration.png "Generator Integration") -The utility [`cbridge`](https://github.com/Open-CMSIS-Pack/generator-bridge) gets as parameter the `.cbuild-gen-idx.yml` and calls the generator. For the `CubeMX` generator example these files are created: +The utility [`cbridge`](https://github.com/Open-CMSIS-Pack/generator-bridge) gets as parameter the `.cbuild-gen-idx.yml` and calls the generator. For the `CubeMX` generator example these files are created: - `*.ioc` CubeMX project file with current project settings - `*.c/.h` source files, i.e. for interfacing with drivers diff --git a/docs/build-overview.md b/docs/build-overview.md index 7802ac0..054ae7c 100644 --- a/docs/build-overview.md +++ b/docs/build-overview.md @@ -1,48 +1,19 @@ -# Build Overview +# CSolution Project Structure -This chapter describes the overall concept of the CMSIS-Toolbox build process. It outlines the content of *csolution project files* that describes the software application, and contains references to examples and project templates. +This chapter outlines the structure of *csolution project files* that contain the build information of the software application. -- [Project Examples](#project-examples) helps to get started with the tools. +- [Project Examples](#project-examples) and project templates helps to get started with the tools. - [Software Layers](#software-layers) provide reusable configurations and give projects a better structure. -- [Project Structure](#project-structure) describes the overall structure of projects. +- [Directory Structure](#directory-structure) describes the overall directory structure of projects. - [Linker Script Management](#linker-script-management) defines the available memory and controls the linker operation. - [Generator Support](#generator-support) integrates configuration tools such as STM32CubeMX or MCUXpresso Config. ## Overview of Operation -The following tools support the creation of build information for embedded applications: - -Tool | Description -:------------------------|:----------------------- -[cpackget](build-tools.md#cpackget-invocation) | Pack Manager: install and manage software packs in the host development environment. -[cbuild](build-tools.md#cbuild-invocation) | Build Invocation: orchestrate the build steps utilizing CMSIS tools and a CMake compilation process. -[csolution](build-tools.md#csolution-invocation)| Project Manager: create build information for embedded applications that consist of one or more related projects. - -The tools process *csolution project files* (in YAML format) and *software packs* -(in [Open-CMSIS-Pack](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/index.html) format) to generate independent projects which may be a part of a more complex application. - -!!! Notes - - This documentation uses the filename extension `*.yml`, but the extension `*.yaml` is also supported. - - The term *CMSIS solution* refers to an application project that is specified with *csolution project files*. - - *Software packs* describe software components in Open-CMSIS-Pack format that can contain middleware, drivers, board support, or device support. *Software packs* also provide documentation, examples, and reusable software layers. - -The features are: - -- Access the content of software packs in Open-CMSIS-Pack format to: - - Setup the tool chain based on a *Device* or *Board* that is defined in software packs. - - Add software components that are provided in the various software packs to the application. -- Organize applications (with a `*.csolution.yml` file) into projects that are independently managed - (using `*.cproject.yml` files). -- Organize software layers (with a `*.clayer.yml` file) with pre-configured software components that enable code reuse across similar applications. -- Manage multiple hardware targets to allow application deployment to different hardware - (test board, production hardware, etc.). -- Manage multiple build types to support software verification (debug build, test build, release build, etc.) -- Support multiple compiler toolchains (GCC, Arm Compiler 6, IAR, LLVM) for project deployment. - -The diagram below outlines the operation of the `csolution` command `convert` that processes one or more [`context`](YML-Input-Format.md#context) configurations of the application (called *csolution project*). +The diagram below outlines the operation of the `csolution` command `convert` that processes the *csolution project* with one or more [`context`](YML-Input-Format.md#context) configurations for an application. !!! Tip - [Project Examples](#project-examples) show different project types and provides templates for user projects. @@ -55,41 +26,35 @@ Input Files | Description [Generic Software Packs](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/cp_PackTutorial.html#cp_SWComponents) | Provide re-usable software components that are typically configurable towards a user application. [DFP Software Packs](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/cp_PackTutorial.html#createPack_DFP) | Device related information (including memory sizes) for the tool configuration. [BSP Software Packs](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/cp_PackTutorial.html#createPackBoard) | Board specific configuration (i.e. additional memory resources). -[cdefault.yml](YML-Input-Format.md#cdefault) | When enabled with [`cdefault:`](YML-Input-Format.md#solution), setup of toolchain specific controls and pre-defined toolchains. -[*.csolution.yml](YML-Input-Format.md#solution) | Complete scope of the application with build order of sub-projects. Defines [target](YML-Input-Format.md#target-types) and [build](YML-Input-Format.md#build-types) types. -[*.cproject.yml](YML-Input-Format.md#project) | Content of an independent build (linker or archiver run) - directly relates to a `*.cprj` file. +[cdefault.yml](YML-Input-Format.md#cdefault) | When enabled with [`cdefault:`](YML-Input-Format.md#solution), setup of toolchain specific controls and pre-defined toolchains. +[*.csolution.yml](YML-Input-Format.md#solution) | Complete scope of the application with sub-projects. Defines [target](YML-Input-Format.md#target-types) and [build](YML-Input-Format.md#build-types) types. +[*.cproject.yml](YML-Input-Format.md#project) | Content of an independent build step (linker or library archiver run). [*.clayer.yml](YML-Input-Format.md#layer) | Set of source files along with pre-configured components for reuse in different applications. Input/Output Files | Description :------------------------|:--------------------------------- -[*.cbuild-pack.yml](YML-CBuild-Format.md#file-structure-of-cbuild-packyml) | Exact list of the packs that are used by the application; enables [reproducible builds](#reproducible-builds) as it locks the pack versions. -[*.cbuild-set.yml](YML-CBuild-Format.md#file-structure-of-cbuild-setyml) | Specifies the [context set](#working-with-context-set) of projects, target-types, and build-types that are used to generate the application image. +[*.cbuild-pack.yml](YML-CBuild-Format.md#cbuild-packyml) | Exact list of the packs that are used by the application; enables [reproducible builds](#reproducible-builds) as it locks the pack versions. +[*.cbuild-set.yml](YML-CBuild-Format.md#cbuild-setyml) | Specifies the [context set](#working-with-context-set) of projects, target-types, and build-types that are used to generate the application image. Output Files | Description :------------------------|:--------------------------------- -[*.cbuild-idx.yml](YML-CBuild-Format.md#file-structure-of-cbuild-idxyml) | Index file of all `*.cbuild.yml` build descriptions; contains also overall information for the application. -[*.cbuild.yml](YML-CBuild-Format.md#file-structure-of-cbuild-idxyml) | Build description of a single [`*.cproject.yml`](YML-Input-Format.md#project-file-structure) input file for each context. -[Project Build Files *.cprj](https://arm-software.github.io/CMSIS_5/Build/html/cprjFormat_pg.html) | Project build information in legacy format. +[*.cbuild-idx.yml](YML-CBuild-Format.md#cbuild-idxyml) | Index file of all `*.cbuild.yml` build descriptions; contains also overall information for the application. +[*.cbuild.yml](YML-CBuild-Format.md#cbuild-idxyml) | Build description of a single [`*.cproject.yml`](YML-Input-Format.md#project-file-structure) input file for each context. [Run-Time Environment (RTE)](#rte-directory-structure) | Contains the user configured files of a project along with `RTE_Components.h` inventory file. [Linker Script Files](#automatic-linker-script-generation) | Header file that describes the memory resources. -To build an application project, the `csolution` command `convert` executes the following steps: +To generate the build information of an application project, the `csolution` command `convert` executes the following steps: -1. Read Input Files: - - Read *.YML input files and check files against schema (disable schema check with option: `--no-check-schema`) - - Parse *.YML input nodes. - - Load software packs for selected contexts (control packs with option: `--load [latest|all|required]`). +1. Read Input Files (*csolution project* and *Software Packs*) -2. Process each project context (select a specific context with option: `--context`): +2. Process each project context (selected by a [context-set](#working-with-context-set) or option: `--context`): - Apply [`pack:`](YML-Input-Format.md#pack), [`device:`](YML-Input-Format.md#device), [`board:`](YML-Input-Format.md#board), and [`compiler:`](YML-Input-Format.md#compiler) to filter the content of software packs. - From [`groups:`](YML-Input-Format.md#groups) add the list of user source files. - From [`components:`](YML-Input-Format.md#components) add the list of component source files. - - From [*.GPDSC files](build-tools.md#use-generators) add the list of generated source files. -3. Generate output files: +3. Generate *Output Files*: - Update [configuration files](#plm-of-configuration-files) in RTE directory (disable with option: `--no-update-rte`). - Print results of software component dependency validation. - - Create `cbuild-idx.yml`, `cbuild.yml` and `*.CPRJ` files. ### Source Code of Software Packs @@ -110,7 +75,6 @@ The following repositories provide several working examples: Repository | Description :---------------------|:------------------------------------- [csolution-examples](https://github.com/Open-CMSIS-Pack/csolution-examples) | Contains several getting started examples that show single-core, multi-core, and TrustZone setup as well as how to use a generator (CubeMX). -[vscode-get-started](https://github.com/Open-CMSIS-Pack/vscode-get-started) | Contains the setup for a VS Code development environment including an example project. [github.com/Arm-Examples](https://github.com/Arm-Examples) | Contains many examples that include CMSIS-Toolbox setup. The section below explains the overall concepts considered by the **`csolution` Project Manager** based on examples. @@ -288,26 +252,27 @@ cbuild Hello.csolution.yml --toolchain GCC ``` !!! Tip - [Toolchain agnostic example projects](pack-tools.md#project-examples) do not contain a [`compiler:`](YML-Input-Format.md#compiler) selection in the `*.csolution.yml` project file. Instead the [`select-compiler:`](YML-Input-Format.md#select-compiler) node list the compilers that this *csolution project* is tested with. + - [Toolchain agnostic example projects](pack-tools.md#project-examples) do not contain a [`compiler:`](YML-Input-Format.md#compiler) selection in the [`*.csolution.yml`](YML-Input-Format.md#solution) project file. + - Instead the [`select-compiler:`](YML-Input-Format.md#select-compiler) node list the compilers that this *csolution project* is tested with. The [VS Code extension Arm CMSIS Solution](https://marketplace.visualstudio.com/items?itemName=Arm.cmsis-csolution) adds the [`compiler:`](YML-Input-Format.md#compiler) node based on the installed compiler in your environment. ### Reproducible builds -Reproducible builds are supported by the [*.cbuild-pack.yml](YML-CBuild-Format.md#file-structure-of-cbuild-packyml) file that is created and read by the **csolution** project manager. This file: +Reproducible builds are supported by the [*.cbuild-pack.yml](YML-CBuild-Format.md#cbuild-packyml) file that is created and read by the **csolution** project manager. This file: - Records the exact list of the pack versions used during creation of an application. - Ensures that pack versions do not change during development even when new packs are installed on the host computer, for example to develop other applications. !!! Note - - The [*.cbuild-pack.yml](YML-CBuild-Format.md#file-structure-of-cbuild-packyml) file should be committed to a repository to ensure reproducible builds. - - The `cbuild` option `--frozen-packs` checks that the [*.cbuild-pack.yml](YML-CBuild-Format.md#file-structure-of-cbuild-packyml) file exists and reports an error if any pack is changed or not available. - - To update a pack to a new version, delete the file [*.cbuild-pack.yml](YML-CBuild-Format.md#file-structure-of-cbuild-packyml) or remove the information about a specific pack in this file. + - The [*.cbuild-pack.yml](YML-CBuild-Format.md#cbuild-packyml) file should be committed to a repository to ensure reproducible builds. + - The `cbuild` option `--frozen-packs` checks that the [*.cbuild-pack.yml](YML-CBuild-Format.md#cbuild-packyml) file exists and reports an error if any pack is changed or not available. + - To update a pack to a new version, delete the file [*.cbuild-pack.yml](YML-CBuild-Format.md#cbuild-packyml) or remove the information about a specific pack in this file. #### Repository Contents To support reproducible builds the following files should be committed to a repository of a version control system. - All user source code files. -- All csolution project files (`cdefault.yml`, `*.csolution.yml`, `*.cproject.yml`, etc.). +- All *csolution project files* (`cdefault.yml`, `*.csolution.yml`, `*.cproject.yml`, etc.). - All files in the RTE directory - Ensure that there are no files with the extension *.update@* as this indicates that configuration files are not up-to-date due to updated software packs. - The file `*.cbuild-pack.yml` to allow [reproducible builds](#reproducible-builds). @@ -319,8 +284,7 @@ To support reproducible builds the following files should be committed to a repo ### Project Setup for Related Projects A solution is the software view of the complete system. It combines projects that can be generated independently and -therefore manages related projects. It may be also deployed to different targets during development as described in the -previous section under [Software Layers](#software-layers). +therefore manages related projects. It may be also deployed to different targets during development as described in section [Software Layers](#software-layers). The picture below shows a system that is composed of: @@ -368,16 +332,18 @@ solution: debug: on projects: - - project: ./security/TFM.cproject.yml # Only generated for build type: Release + - project: ./security/TFM.cproject.yml # Project D: Only generated for build type: Release for-context: .Release - - project: ./application/MQTT_AWS.cproject.yml + - project: ./application/MQTT_AWS.cproject.yml # Project B + - project: ./mldata/Model.cproject.yml # Project C - project: ./bootloader/Bootloader.cproject.yml # Not generated for target type: Board not-for-context: +Board + - project: ./processor2/Control.cproject.yml # Project A ``` ### Working with context-set -Frequently, it is required to build applications with different [context](#context) types. The following command line example generates the `iot-product.csolution.yml` with build type `Debug` for the project `MQTT_AWS.cproject.yml`, while the other projects use the build type `Release`. When using the option `-S` or `--context-set`, this selection is saved to the file `iot-product.cbuild-set.yml` located in the same directory as the `*.csolution.yml` file. Refer to [File Structure of `*.cbuild-set.yml`](YML-CBuild-Format.md#file-structure-of-cbuild-setyml) for details. +Frequently, it is required to build applications with different [context](#context) types. The following command line example generates the `iot-product.csolution.yml` with build type `Debug` for the project `MQTT_AWS.cproject.yml`, while the other projects use the build type `Release`. When using the option `-S` or `--context-set`, this selection is saved to the file `iot-product.cbuild-set.yml` located in the same directory as the `*.csolution.yml` file. Refer to [File Structure of `*.cbuild-set.yml`](YML-CBuild-Format.md#cbuild-setyml) for details. ```txt cbuild iot-product.csolution.yml -c TFM.Release+Board -c MQTT_AWS.Debug+Board -c Bootloader.Release+Board -S @@ -395,6 +361,9 @@ cbuild iot-product.csolution.yml -S - Only one [build-type](#context) can be selected for a project. - Projects that are not required can be excluded. +!!! Note + The [VS Code extension Arm CMSIS Solution](https://marketplace.visualstudio.com/items?itemName=Arm.cmsis-csolution) always uses a `context-set` that is selected in the Manage Solution view. + ### External Tools and Build Order The [`executes:`](YML-Input-Format.md#executes) node integrates [CMake](build-operation.md#cmake-integration) scripts, projects, and external tools. The `input:` and `output:` list typically refers to files and therefore defines the build order of projects: @@ -569,7 +538,7 @@ can share a `layer` with common configuration settings. Software layers for [*reference applications*](ReferenceApplications.md) may be published in software packs. Refer to [Pack Creation » Layers](pack-tools.md#layers) for more information. -## Project Structure +## Directory Structure This section describes how the `csolution` based project files should be organized to allow the scenarios described above. This section gives also guidelines for a directory structure. @@ -583,7 +552,7 @@ Working Area | Access | Des :-----------------------------------------------------------------|:------:|:------------------ [Project Area](#project-area) | RW | Contains user source code files managed by the user along with the project files (see next item). [Project files](./YML-Input-Format.md#project-file-structure) | RW | Created by a user or an IDE to describe the application project. -Component source code | RO | Content of software packs; the location is specified by the environment variable [`CMSIS_PACK_ROOT`](https://github.com/Open-CMSIS-Pack/cmsis-toolbox/blob/main/docs/installation.md#environment-variables) or the node [`pack: path`](./YML-Input-Format.md#pack) in project files. +Component source code | RO | Content of software packs; the location is specified by the environment variable [`CMSIS_PACK_ROOT`](installation.md#environment-variables) or the node [`pack: path`](./YML-Input-Format.md#pack) in project files. [Component Configuration​](#rte-directory-structure) | RW | User editable config files of software components that are copied to the RTE directory. Generator artifacts​ | RO (see note) | Managed by domain specific configuration tools such as STM32CubeMX or MCUXpresso. [Build artifacts](./YML-Input-Format.md#directory-control) | RW | Created during the build process for example by a compiler. @@ -871,7 +840,7 @@ csolution CubeMX.csolution.yml run --generator CubeMX ### Configure Generator Output -The *Generator* output directory and the name of the [*Generator* import file (`*.cgen.yml`)](YML-CBuild-Format.md#generator-import-file) can be configured using the node [`generators:`](https://github.com/Open-CMSIS-Pack/cmsis-toolbox/blob/main/docs/YML-Input-Format.md#generators) as shown below. +The *Generator* output directory and the name of the [*Generator* import file (`*.cgen.yml`)](YML-CBuild-Format.md#generator-import-file) can be configured using the node [`generators:`](YML-Input-Format.md#generators) as shown below. ```yml generators: diff --git a/docs/build-tools.md b/docs/build-tools.md index 956eb3d..20b804d 100644 --- a/docs/build-tools.md +++ b/docs/build-tools.md @@ -207,7 +207,7 @@ cbuild example.csolution.yml --toolchain GCC --output outGCC ### Update RTE Configuration Files -The [Component Configuration​](build-overview.md#project-structure) is stored in the [RTE directory](build-overview.md#rte-directory-structure). When files are missing or new software pack versions are installed, it might be required to update the RTE configuration files: +The [Component Configuration​](build-overview.md#directory-structure) is stored in the [RTE directory](build-overview.md#rte-directory-structure). When files are missing or new software pack versions are installed, it might be required to update the RTE configuration files: ```shell csolution example.csolution.yml --update-rte @@ -306,7 +306,7 @@ csolution run -g CubeMX mysolution.csolution.yml -c Blinky.Debug+STM32L4 When working with [multiple related projects](build-overview.md#project-setup-for-related-projects), it might be necessary to combine different build types for debug and download in the target hardware. With the option `--context-set` the selected `--context` options can be saved and re-used. -Write the selected `--context` options to the file `SimpleTZ.cbuild-set.yml`. Refer to [file structure of `*.cbuild-set.yml`](YML-CBuild-Format.md#file-structure-of-cbuild-setyml) for details. +Write the selected `--context` options to the file `SimpleTZ.cbuild-set.yml`. Refer to [file structure of `*.cbuild-set.yml`](YML-CBuild-Format.md#cbuild-setyml) for details. ```shell cbuild SimpleTZ.csolution.yml -S -c CM33_s.Release -c CM33_ns.Debug @@ -343,7 +343,7 @@ cbuild setup example.csolution.yml --context-set --packs variants. There are two ways to specify the CMSIS-PACK root directory: 1. With the `CMSIS_PACK_ROOT` environment variable. - Refer to [Installation - Environment Variables](https://github.com/Open-CMSIS-Pack/cmsis-toolbox/blob/main/docs/installation.md#environment-variables). + Refer to [Installation - Environment Variables](installation.md#environment-variables). 2. With the option `--pack-root `, for example: @@ -626,8 +626,8 @@ Example | Description [AVH_CI_Template](https://github.com/Arm-Examples/AVH_CI_Template) | CI Template for unit test automation that uses GitHub Actions. [CMSIS Version 6](https://github.com/ARM-software/CMSIS_6/actions) | Runs a CMSIS-Core validation test across the supported processors using multiple compilers. [RTOS2 Validation](https://github.com/ARM-software/CMSIS-RTX/actions) | Runs the CMSIS-RTOS2 validation across Keil RTX using source and library variants. -[STM32H743I-EVAL_BSP](https://github.com/Open-CMSIS-Pack/STM32H743I-EVAL_BSP) | Build test of a Board Support Pack (BSP) with MDK-Middleware [Reference Applications](https://github.com/Open-CMSIS-Pack/cmsis-toolbox/blob/main/docs/ReferenceApplications.md) using Arm Compiler or GCC. The artifacts store the various example projects for testing on the hardware board. -[TFL Micro Speech](https://github.com/arm-software/AVH-TFLmicrospeech) | This example project shows the Virtual Streaming Interface with Audio input and uses [software layers](https://github.com/Open-CMSIS-Pack/cmsis-toolbox/blob/main/docs/build-overview.md#software-layers) for retargeting. +[STM32H743I-EVAL_BSP](https://github.com/Open-CMSIS-Pack/STM32H743I-EVAL_BSP) | Build test of a Board Support Pack (BSP) with MDK-Middleware [Reference Applications](ReferenceApplications.md) using Arm Compiler or GCC. The artifacts store the various example projects for testing on the hardware board. +[TFL Micro Speech](https://github.com/arm-software/AVH-TFLmicrospeech) | This example project shows the Virtual Streaming Interface with Audio input and uses [software layers](build-overview.md#software-layers) for retargeting. ## IDE Usage diff --git a/docs/css/extra.css b/docs/css/extra.css index 1c01d07..96121e6 100644 --- a/docs/css/extra.css +++ b/docs/css/extra.css @@ -5,3 +5,11 @@ .wy-table-responsive { overflow : visible !important; } + +.wy-nav-content { + max-width: 900px; +} + +.rst-content .section ul li p:last-child { + padding: 0px 0px 8px 0px; +} \ No newline at end of file diff --git a/docs/index.html b/docs/index.html deleted file mode 100644 index 501bfb6..0000000 --- a/docs/index.html +++ /dev/null @@ -1,14 +0,0 @@ - - - -Redirect to the Open-CMSIS-Pack toolbox documentation page after 0 seconds - - - - - - -If the automatic redirection is failing, click open CMSIS-Toolbox documentation. - - - diff --git a/docs/index.md b/docs/index.md index 90abf1f..e3a60cb 100644 --- a/docs/index.md +++ b/docs/index.md @@ -3,6 +3,7 @@ Thank you for using the **CMSIS-Toolbox** that provides command-line tools for: - Project creation and build of embedded applications that utilize [*software packs*](https://www.keil.arm.com/packs/). Various compilation tools are supported. + - Pack creation, maintenance, and distribution of *software packs* in [Open-CMSIS-Pack format](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/index.html). ## Manual Chapters @@ -11,11 +12,11 @@ Thank you for using the **CMSIS-Toolbox** that provides command-line tools for: - [**Installation**](installation.md) explains the setup of the CMSIS-Toolbox along with a build environment for embedded applications that are based on Arm Cortex-M processors. -- [**Build Overview**](build-overview.md) describes the overall concept, outlines the *csolution project files* that describes the software application, and contains references to examples and project templates. - - [**Build Tools**](build-tools.md) contains command line descriptions for `cbuild` (build projects), `csolution` (transform *csolution project files*), and `cpackget` (manage software packs). -- [**CMSIS Solution Project File Format**](YML-Input-Format.md) is a detailed description of the *csolution project files* that define the software application in YAML format. +- [**CSolution Project Structure**](build-overview.md) describes the overall concept, outlines the *csolution project files* that describes the software application, and contains references to examples and project templates. + +- [**CSolution Project Format**](YML-Input-Format.md) is a detailed description of the *csolution project files* that define the software application in YAML format. - [**Create Applications**](CreateApplications.md) explains how to start projects using software packs. It covers also linker script creation, software pack structure, and project maintenance with pack upgrades. @@ -42,5 +43,5 @@ Version | Description 2.5.0 | CMSIS-Toolbox [2.5.0](https://github.com/Open-CMSIS-Pack/cmsis-toolbox/releases/tag/2.5.0); direct CMake interface is now default, [`tmpdir:`](YML-Input-Format.md#output-dirs) controls location of interim files, adds [`add-path-asm:`](YML-Input-Format.md#add-path-asm), adds [`define-asm`](YML-Input-Format.md#define-asm), adds [regular expression](YML-Input-Format.md#regular-expressions) search to `for-context:`/`not-for-context`, and contains several corrections. 2.4.0 | CMSIS-Toolbox [2.4.0](https://github.com/Open-CMSIS-Pack/cmsis-toolbox/releases/tag/2.4.0); adds [CubeMX integration](CubeMX.md), [pre/post-build steps](YML-Input-Format.md#prepost-build-steps), simplifies the [generator integration](build-operation.md#generator-integration), and contains several corrections. 2.3.0 | CMSIS-Toolbox [2.3.0](https://github.com/Open-CMSIS-Pack/cmsis-toolbox/releases/tag/2.3.0) adds in the csolution project files [component instances](YML-Input-Format.md#instances) and [optimize: debug](YML-Input-Format.md#optimize). Tools are extended with [cbuild setup command](build-operation.md#details-of-the-setup-mode), [--frozen-pack option](build-overview.md#reproducible-builds). Refer to [release information](https://github.com/Open-CMSIS-Pack/cmsis-toolbox/releases/tag/2.3.0) for more details. -2.2.0 | CMSIS-Toolbox [2.2.0](https://github.com/Open-CMSIS-Pack/cmsis-toolbox/releases/tag/2.2.0) adds [generator integration](build-operation.md#generator-integration), extends [translation controls](YML-Input-Format.md#translation-control), adds [context set](build-overview.md#working-with-context-set), adds [pack locking](YML-CBuild-Format.md#pack-locking), and improves [linker script management](build-overview.md#linker-script-management). Refer to [release information](https://github.com/Open-CMSIS-Pack/cmsis-toolbox/releases/tag/2.2.0) for more details. +2.2.0 | CMSIS-Toolbox [2.2.0](https://github.com/Open-CMSIS-Pack/cmsis-toolbox/releases/tag/2.2.0) adds [generator integration](build-operation.md#generator-integration), extends [translation controls](YML-Input-Format.md#translation-control), adds [context set](build-overview.md#working-with-context-set), adds [pack locking](YML-CBuild-Format.md#lock-pack-versions), and improves [linker script management](build-overview.md#linker-script-management). Refer to [release information](https://github.com/Open-CMSIS-Pack/cmsis-toolbox/releases/tag/2.2.0) for more details. 2.0.0 | Initial release for CMSIS-Toolbox [2.0.0](https://github.com/Open-CMSIS-Pack/cmsis-toolbox/releases/tag/2.0.0) diff --git a/docs/installation.md b/docs/installation.md index 973064f..ec5757e 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -75,7 +75,7 @@ The environment variable **CMSIS_PACK_ROOT** and **CMSIS_COMPILER_ROOT** are opt - Toolchain cmake files `....cmake` for the selected [compiler](YML-Input-Format.md#compiler). - Default [linker script files](build-overview.md#linker-script-management) (to be preprocessed): `_linker_script..src` - - The `cdefault.yml` that is used when no other [`cdefault.yml`](YML-Input-Format.md#cdefault) file is found. + - The `cdefault.yml` that is used when no [`cdefault.yml`](YML-Input-Format.md#cdefault) file is found in the same directory as the `.csolution.yml` file. #### Compiler Registration diff --git a/docs/migration.md b/docs/migration.md deleted file mode 100644 index 0a15430..0000000 --- a/docs/migration.md +++ /dev/null @@ -1,80 +0,0 @@ -# Migrating examples created for `cmsis-toolbox` `1.x.y` to `2.0.0` - -This document clarifies breaking changes introduced in the CMSIS-Toolbox 2.0.0 and describes most common issues faced when migrating examples created for older versions. -Please [extend this document](https://github.com/Open-CMSIS-Pack/cmsis-toolbox/edit/main/docs/migration.md) if you encounter further issues. - -For highlighting changes in yml nodes it's recommended to update the YAML Language Support extension settings to use the tagged schemas [`schemas/projmgr/2.0.0`]( -https://github.com/Open-CMSIS-Pack/devtools/releases/tag/schemas/projmgr/2.0.0). - -For example the following `# yaml-language-server` comment can be used: - -- in *.csolution.yml: - - ``` yml - # yaml-language-server: $schema=https://github.com/Open-CMSIS-Pack/devtools/blob/schemas/projmgr/2.0.0/tools/projmgr/schemas/csolution.schema.json - ``` - -- in *.cproject.yml: - - ``` yml - # yaml-language-server: $schema=https://github.com/Open-CMSIS-Pack/devtools/blob/schemas/projmgr/2.0.0/tools/projmgr/schemas/cproject.schema.json - ``` - -- in *.clayer.yml: - - ``` yml - # yaml-language-server: $schema=https://github.com/Open-CMSIS-Pack/devtools/blob/schemas/projmgr/2.0.0/tools/projmgr/schemas/clayer.schema.json - ``` - -**The following deprecated yml nodes and related handling were removed:** - -all occurrences: - -- `add-paths` (replaced by [`add-path`](https://github.com/Open-CMSIS-Pack/cmsis-toolbox/blob/main/docs/YML-Input-Format.md#add-path)) -- `del-paths` (replaced by [`del-path`](https://github.com/Open-CMSIS-Pack/cmsis-toolbox/blob/main/docs/YML-Input-Format.md#del-path)) -- `defines` (replaced by [`define`](https://github.com/Open-CMSIS-Pack/cmsis-toolbox/blob/main/docs/YML-Input-Format.md#define)) -- `undefines` (replaced by [`undefine`](https://github.com/Open-CMSIS-Pack/cmsis-toolbox/blob/main/docs/YML-Input-Format.md#undefine)) -- `for-type` (replaced by [`for-context`](https://github.com/Open-CMSIS-Pack/cmsis-toolbox/blob/main/docs/YML-Input-Format.md#for-context)) -- `not-for-type` (replaced by [`not-for-context`](https://github.com/Open-CMSIS-Pack/cmsis-toolbox/blob/main/docs/YML-Input-Format.md#not-for-context)) -- `output-type` (replaced by [`output`](https://github.com/Open-CMSIS-Pack/cmsis-toolbox/blob/main/docs/YML-Input-Format.md#output) node) - -in [`misc`](https://github.com/Open-CMSIS-Pack/cmsis-toolbox/blob/main/docs/YML-Input-Format.md#misc): - -- `compiler` (replaced by [`for-compiler`) -- `C*` (replaced by `C-CPP`) - -in `output-dirs`: - -- `gendir` (replaced by `generators` node) -- `rtedir` (replaced by `rte` node in `*.cproject.yml`) - -!!! Note - RTE files belonging to components specified in `*.clayer.yml` files remain next to such `*.clayer.yml.` - -in [`processor`](https://github.com/Open-CMSIS-Pack/cmsis-toolbox/blob/main/docs/YML-Input-Format.md#processor): - -- `fpu` and `endian` (but accepted with disabled schema check) - -in [`cdefault:`](https://github.com/Open-CMSIS-Pack/cmsis-toolbox/blob/main/docs/YML-Input-Format.md#default): - -- `packs` -- `build-types` -- `output-dirs` - -**The cdefault enablement has changed:** - -The [`cdefault:`](https://github.com/Open-CMSIS-Pack/cmsis-toolbox/blob/main/docs/YML-Input-Format.md#default) empty node must be added to *.csolution.yml to activate its use. - -!!! Note - The file must be named `cdefault.yml` or `cdefault.yaml` without leading dot. - -**The following [Access Sequences](https://github.com/Open-CMSIS-Pack/cmsis-toolbox/blob/main/docs/YML-Input-Format.md#access-sequences) were removed:** - -- `$Source(context)` (replaced by `$ProjectDir(context)$`) -- `$Out(context)` (replaced by `$elf(context)$`, `$bin(context)$`, `$hex(context)$`, `$lib(context)$` and `$cmse-lib(context)$`) - -**The following environment variable must be unset or removed:** - -- `CMSIS_BUILD_ROOT` - -Note: This is needed because `cbuild` calls binaries pointed by `CMSIS_BUILD_ROOT` which are potentially outdated. diff --git a/docs/overview.md b/docs/overview.md index 29180e2..0f75f07 100644 --- a/docs/overview.md +++ b/docs/overview.md @@ -5,7 +5,9 @@ ## Target Audience -This user's guide assumes basic knowledge about Cortex-M software development. It is written for embedded software developers that work with C/C++ compiler toolchains and utilize microcontroller devices with Cortex-M processors and Ethos-U NPUs. The CMSIS-Toolbox supports currently: +This user's guide assumes basic knowledge about Cortex-M software development. It is written for embedded software developers that work with C/C++ compiler toolchains and utilize microcontroller devices with Cortex-M processors and Ethos-U NPUs. + +The CMSIS-Toolbox contains stand-alone tools [for all host platforms](https://artifacts.keil.arm.com/cmsis-toolbox/) (Windows, Mac, Linux) that support: - [Arm Compiler for Embedded](https://developer.arm.com/Tools%20and%20Software/Arm%20Compiler%20for%20Embedded) version 6.18 or higher - Arm FuSa Compiler for Embedded version 6.16.2 or higher is also supported @@ -13,19 +15,32 @@ This user's guide assumes basic knowledge about Cortex-M software development. I - [IAR Compiler](https://www.iar.com/products/architectures/arm/) version 9.32.1 or higher - [CLANG Compiler version 17.0.1](https://github.com/ARM-software/LLVM-embedded-toolchain-for-Arm/releases) or higher based on LLVM technology +!!! Notes + - This documentation uses the filename extension `*.yml`, but the extension `*.yaml` is also supported. + - The term *CMSIS solution* refers to an application project that is specified with *csolution project files* (`*.csolution.yml`, `*cproject.yml`, and `*.clayer.yml`). + - *Software packs* describe software components in Open-CMSIS-Pack format that can contain middleware, drivers, board support, or device support. *Software packs* also provide documentation, examples, and reusable software layers. + ## Overall Workflow -The CMSIS-Toolbox uses *software packs* for device/board support and access reusable software components. The operation is controlled via intuitive [*csolution project files* in YAML format](YML-Input-Format.md). The overall application is defined in the `*.csolution.yml` file and contains one or more projects that can utilize pre-configured software layers. The build engine CMake/Ninja calls the C/C++ compiler toolchain that generates the Build Output. +The CMSIS-Toolbox includes following tools for the creation of embedded applications: + +Tool | Description +:------------------------|:----------------------- +[cpackget](build-tools.md#cpackget-invocation) | Pack Manager: install and manage software packs in the host development environment. +[cbuild](build-tools.md#cbuild-invocation) | Build Invocation: orchestrate the build steps utilizing CMSIS tools and a CMake compilation process. +[csolution](build-tools.md#csolution-invocation)| Project Manager: create build information for embedded applications that consist of one or more related projects. + +These tools use *software packs* for device/board support and access to reusable software components. The operation is controlled via [*csolution project files* in YAML format](YML-Input-Format.md). The overall application is defined in the `*.csolution.yml` file and contains one or more projects that can utilize pre-configured software layers. The build engine CMake/Ninja calls the C/C++ compiler toolchain that generates the Build Output. -The [**cbuild: Build Invocation**](build-tools.md#cbuild-invocation) command orchestrates the overall build steps. This command calls individual command line tools to generate the application as outlined in the following diagram. +The [**cbuild**](build-tools.md#cbuild-invocation) command orchestrates the overall build steps. This command calls individual tools to generate the application as outlined in the following diagram. ![cbuild workflow](./images/cbuild-workflow.png "cbuild workflow") The build steps are: -1. [**cpackget**](build-tools.md#cpackget-invocation) downloads Software Packs that are required for `*.csolution.yml` when using the option `--pack`. -2. [**csolution**](build-tools.md#csolution-invocation) processes the User Input and the Software Packs to generate the overall Build Information. Refer to [Overview of Operation](build-overview.md#overview-of-operation) for details. -3. **cbuild2cmake** converts this Build Information into CMake format. +1. [**cpackget**](build-tools.md#cpackget-invocation) downloads *Software Packs* that are required for `*.csolution.yml` when using the option `--pack`. +2. [**csolution**](build-tools.md#csolution-invocation) processes the *csolution project* and the *Software Packs* to generate the overall *Build Information*. Refer to [CSolution Project Structure](build-overview.md#overview-of-operation) for details. +3. **cbuild2cmake** converts this *Build Information* into CMake format. 4. **CMake/Ninja** call the C/C++ compiler toolchain to translate the source files into the application image. !!! Note @@ -34,26 +49,33 @@ The build steps are: ## Command Line and IDE Usage -The CMSIS-Toolbox is a set of command line tools that are designed for stand-alone usage and integration into IDEs or DevOps systems for Continuous Integration (CI) workflows. +The CMSIS-Toolbox is a set of command line tools that are designed for stand-alone usage and integration into [IDEs](build-tools.md#ide-usage) or [DevOps](build-tools.md#devops-usage) systems for Continuous Integration (CI) workflows. ![Operation of `csolution` tool](./images/tool-overview.png "Operation of `csolution` tool") -The [VS Code](https://marketplace.visualstudio.com/items?itemName=Arm.keil-studio-pack) IDE integration available from Arm is a viewer to the [*csolution project files*](YML-Input-Format.md) and provides graphical ways to modify the content. Refer to [DevOps Usage](build-tools.md#devops-usage) for more information on integration into CI workflows. +!!! Tip + - The [VS Code extension Arm CMSIS Solution](https://marketplace.visualstudio.com/items?itemName=Arm.cmsis-csolution) is a graphical user interface for [*csolution projects*](YML-Input-Format.md). + + - The [AVH-FVP examples](https://github.com/Arm-Examples) and many projects on [github.com/Open-CMSIS-Pack](https://github.com/Open-CMSIS-Pack) exemplify CI workflows. ## Benefits The overall benefits of the CMSIS-Toolbox are: -- Flexible command line tools that can be used stand-alone or integrated into [VS Code](https://marketplace.visualstudio.com/items?itemName=Arm.keil-studio-pack) or [DevOps systems for Continuous Integration (CI)](build-tools.md#devops-usage). -- Stand-alone tools are available [for all host platforms](https://artifacts.keil.arm.com/cmsis-toolbox/) (Windows, Mac, Linux) for flexible deployment. -- [*Software packs*](https://www.keil.arm.com/packs/) simplify tool setup with `device:` or `board:` selection and project creation with access to reusable software components. -- Organize solutions with projects that are independently managed simplifies a wide range of use cases including multi-processor applications or unit testing. -- Integrates with domain specific [generators](build-overview.md#use-a-generator) (i.e. CubeMX) that support configuration of devices/boards and complex software stacks such as motor control. -- Provisions for product lifecycle management (PLM) with versioned *software packs* that ease update and management for configuration files. -- Software layers enable code reuse across similar applications with a pre-configured set of source files and software components. +- [*Software packs*](https://www.keil.arm.com/packs/) simplify tool setup with `device:` or `board:` selection and provide access to reusable software components. + +- Organize solutions with independent projects support a wide range of use cases including multi-processor applications or unit testing. + +- Integrates with domain specific [generators](build-overview.md#use-a-generator) (i.e. CubeMX or MCUXpresso Config Tools) for configuration of devices/boards and complex software stacks such as motor control. + - Target types allow application deployment to different hardware (test board, production hardware, virtual simulation models, etc.). + - Build types support software testing and verification (debug build, test build, release build, ect.). -- Support for multiple toolchains, even within the same set of *project files* and command line options to select different toolchains during verification. + +- Software layers enable code reuse across similar applications with a pre-configured set of source files and software components. + - [Linker Script Management](build-overview.md#linker-script-management) utilizes device and board information of *software packs* to define available memory and allows flexible control of linker operation. -- Uses a CMake backend for the build process that integrates with other tools such as VS Code intellisense. -- Provides a [list of software licenses](YML-CBuild-Format.md#licenses) used by the various software packs and software components. + +- [Product lifecycle management (PLM)](build-overview.md#plm-of-configuration-files) with versioned *software packs* that ease update and management for configuration files. + +- Provides a [list of software licenses](YML-CBuild-Format.md#nodes-for-license-information) used by the various software packs and software components. diff --git a/docs/pack-tools.md b/docs/pack-tools.md index 21b8a7b..542f508 100644 --- a/docs/pack-tools.md +++ b/docs/pack-tools.md @@ -33,7 +33,7 @@ Hands-on Tutorial | Description - Example: A component `Device:HAL:ENET` should not have description `ENET HAL Driver`, use `Ethernet HAL driver` instead. - Consider adding [project templates](https://github.com/Open-CMSIS-Pack/STM32U5xx_DFP/tree/main/Templates) to help get started with more complex projects. - This is useful when devices are are configured using generators or provide multiple linker scripts (i.e. RAM/ROM execution). -- To distribute [toolchain agnostic examples](https://github.com/Open-CMSIS-Pack/cmsis-toolbox/blob/main/docs/build-overview.md#toolchain-agnostic-project) as part of packs: +- To distribute [toolchain agnostic examples](build-overview.md#toolchain-agnostic-project) as part of packs: - Consider to use [`select-compiler`](YML-Input-Format.md#select-compiler) to make projects toolchain independent. - To avoid that examples need updates with every pack release, specify the [minium pack version required](https://github.com/Open-CMSIS-Pack/csolution-examples/blob/main/DualCore/HelloWorld.csolution.yml#L9). - Use [CI workflows](https://github.com/Open-CMSIS-Pack/STM32H743I-EVAL_BSP/tree/main/.github/workflows) to validate that projects compile correctly. diff --git a/docs/progress.md b/docs/progress.md deleted file mode 100644 index 544459c..0000000 --- a/docs/progress.md +++ /dev/null @@ -1,93 +0,0 @@ -# Implementation Progress - -Feature | Status | Version -:----------------------------------------------------------------------------------------|:-------------------------|:---------------- -`csolution.yml`, `cproject.yml` and `clayer.yml` handling | :heavy_check_mark: | csolution 0.9.0 -`cdefault.yml` handling | :heavy_check_mark: | csolution 0.9.3 -`build-types` and `target-types` at csolution level | :heavy_check_mark: | csolution 0.9.0 -`for-type`/`not-for-type` context handling | :heavy_check_mark: | csolution 0.9.0 -list `packs`, `devices`, `components`, `dependencies` at cproject level | :heavy_check_mark: | csolution 0.9.0 -`defines`/`undefines`/`add-paths`/`del-paths` at solution/project/target level | :heavy_check_mark: | csolution 0.9.0 -`defines`/`undefines`/`add-paths`/`del-paths` at component/group/file level in csolution | :heavy_check_mark: | csolution 0.9.3 -`defines`/`undefines`/`includes`/`excludes` at component/group/file level in cbuild | :heavy_check_mark: | cbuild 0.10.6 -compiler `misc` options | :heavy_check_mark: | csolution 0.9.0 -`device` discovering from `board` setting | :heavy_check_mark: | csolution 0.9.1 -`optimize`, `debug`, `warnings` in csolution | :heavy_check_mark: | csolution 1.2.0 -`optimize`, `debug`, `warnings` in cbuild | :heavy_check_mark: | cbuild 1.3.0 -access sequences handling in csolution | :heavy_check_mark: | csolution 0.9.1 -access sequences handling in cbuild | :heavy_check_mark: | cbuild 0.11.0 -list commands at csolution and context level | :heavy_check_mark: | csolution 0.9.1 -csolution `context` input parameter | :heavy_check_mark: | csolution 0.9.1 -generator commands: `list generators` and `run --generator ` | :heavy_check_mark: | csolution 0.9.1 -automatic schema checking | :heavy_check_mark: | csolution 0.9.1 -config files PLM | :heavy_check_mark: | csolution 0.9.2 -pack selection: `pack` keyword in csolution | :heavy_check_mark: | csolution 0.9.2 -pack selection: context filtering | :heavy_check_mark: | csolution 0.9.3 -pack selection: `path` keyword in csolution | :heavy_check_mark: | csolution 0.9.2 -pack selection: `path` attribute in cbuild | :heavy_check_mark: | cbuild 0.10.6 -`device` variant handling | :heavy_check_mark: | csolution 0.9.2 -schema for flexible vendor specific additions | :heavy_check_mark: | csolution 0.9.2 -user provided linker script selection | :heavy_check_mark: | csolution 0.9.2 -support for IAR compiler | :heavy_check_mark: | cbuild 0.10.5 -minimum/range component version handling | :heavy_check_mark: | csolution 1.1.0 -replacement of cbuild bash scripts | :heavy_check_mark: | cbuild 0.11.0 -multi-project solution handling in cbuild | :heavy_check_mark: | cbuild 1.5.0 -layered solutions in-source conversion | :heavy_check_mark: | csolution 0.9.4 -support for output directories customization at csolution level | :heavy_check_mark: | csolution 1.0.0 -support for board attributes in conditions | :heavy_check_mark: | csolution 1.0.0 -`for-compiler` and `setup` handling | :heavy_check_mark: | csolution 1.0.0 -multiple contexts selection via wildcards | :heavy_check_mark: | csolution 1.0.0 -layer `interfaces` definitions | :heavy_check_mark: | csolution 1.1.0 -separation of config files belonging to layers | :heavy_check_mark: | csolution 1.2.0 -generation of cbuild-idx.yml and cbuild.yml files | :heavy_check_mark: | csolution 1.2.0 -support for linux-arm64 host platform | :heavy_check_mark: | csolution 1.3.0 -support for win-arm64 and mac-arm64 host platforms | :heavy_check_mark: | csolution 1.7.0 -disable update of RTE folder by default in cbuild | :heavy_check_mark: | cbuild 1.4.0 -`--update-rte` flag to enable the update of RTE folder contents in cbuild | :heavy_check_mark: | cbuild 1.4.0 -`--no-update-rte` flag to skip the update of RTE folder contents in csolution | :heavy_check_mark: | csolution 1.4.0 -`connections` handling replacing `interfaces` | :heavy_check_mark: | csolution 1.4.0 -`variables` handling for setting layer paths | :heavy_check_mark: | csolution 1.4.0 -`list layers` command for finding layers with compatible connections | :heavy_check_mark: | csolution 1.4.0 -`list toolchains` command for finding configured toolchains | :heavy_check_mark: | csolution 1.4.0 -support csolution.yml and context as input data in cbuild | :heavy_check_mark: | cbuild 1.5.0 -add `output` filenames customization handling in cbuild | :heavy_check_mark: | cbuild 1.5.0 -add `output` filenames customization handling in csolution | :heavy_check_mark: | csolution 1.5.0 -rework toolchains registration in cbuild | :heavy_check_mark: | cbuild 1.5.0 -rework toolchains registration in csolution | :heavy_check_mark: | csolution 1.5.0 -`--toolchains` command line option for selecting the compiler | :heavy_check_mark: | csolution 1.5.0 -linker script file pre-processing in csolution | :heavy_check_mark: | csolution 1.7.0 -linker script file pre-processing in cbuild | :heavy_check_mark: | cbuild 1.7.0 -generate regions_*.h file from memory tags | :heavy_check_mark: | csolution 1.7.0 -`context-map` handling | :heavy_check_mark: | csolution 2.0.0-dev0 -reworked `output` nodes | :heavy_check_mark: | csolution 2.0.0-dev0 -reworked output file types | :heavy_check_mark: | cbuild 2.0.0-dev0 -updated access sequences | :heavy_check_mark: | csolution 2.0.0-dev0 -removed deprecated nodes | :heavy_check_mark: | csolution 2.0.0-dev0 -`update-rte` command for creating/updating and listing config files | :heavy_check_mark: | csolution 2.0.0-dev1 -`rte` `base-dir` at cproject level for RTE folder customization | :heavy_check_mark: | csolution 2.0.0-dev1 -reworked `cdefault` handling | :heavy_check_mark: | csolution 2.0.0-dev1 -support multiple `--context` inputs | :heavy_check_mark: | csolution 2.0.0-dev2 -support multiple `setup` for each context | :heavy_check_mark: | csolution 2.0.0-dev2 -support for standard language options in cbuild | :heavy_check_mark: | cbuild 2.0.0-dev3 -support for standard language options in csolution | :heavy_check_mark: | csolution 2.0.0-dev3 -support for `language` and `scope` component file attributes in csolution | :heavy_check_mark: | csolution 2.0.0-dev3 -alpha support for LLVM/Clang in cbuild | :heavy_check_mark: | cbuild 2.0.0 -alpha support for LLVM/Clang in csolution | :heavy_check_mark: | csolution 2.0.0 -add `list configs` command to list configuration files | :heavy_check_mark: | csolution 2.1.0 -add license information to `cbuild.yml` | :heavy_check_mark: | csolution 2.1.0 -support dry-running generators | :heavy_check_mark: | csolution 2.1.0 -support for simplified global generators | :heavy_check_mark: | csolution 2.2.0 -support for `*.cbuild-pack.yml` lock file mechanism | :heavy_check_mark: | csolution 2.2.0 -support for branch protection (PACBTI) | :heavy_check_mark: | csolution 2.2.0 -add option `--context-set` to handle selected contexts `*.cbuild-set.yml` | :heavy_check_mark: | csolution 2.2.0 -add `auto` node for automatic linker script generation | :heavy_check_mark: | csolution 2.2.0 -processor attributes `trustzone`, `fpu`, `dsp`, `mve`, `endian` and `branch-protection` | :heavy_check_mark: | csolution 2.2.0 -alpha support for LLVM/Clang updated to 17.0.1 | :heavy_check_mark: | cbuild 2.2.0 -add `*.src` file extension as linker script source for pre-processing | :heavy_check_mark: | cbuild 2.2.0 -support multiple component instances | :heavy_check_mark: | csolution 2.3.0-dev0 -add cbuild `setup` command | :heavy_check_mark: | cbuild 2.3.0-dev0 -add alpha build manager backend | :heavy_check_mark: | cbuild2cmake 0.9.0-dev0 -`executes` nodes in csolution | :heavy_check_mark: | csolution 2.4.0 -`executes` nodes in cbuild2cmake | :heavy_check_mark: | cbuild2cmake 0.9.1 -extended cbuild `setup` with layers discovery | :heavy_check_mark: | cbuild 2.4.0 -set `cbuild2cmake` as default backend | :heavy_check_mark: | cbuild 2.5.0 diff --git a/mkdocs.yml b/mkdocs.yml index 8181703..9029e0b 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -5,9 +5,9 @@ nav: - Home: index.md - Overview: overview.md - Installation: installation.md - - Build Overview: build-overview.md - Build Tools: build-tools.md - - CMSIS Solution Project File Format: YML-Input-Format.md + - CSolution Project Structure: build-overview.md + - CSolution Project Format: YML-Input-Format.md - Create Applications: CreateApplications.md - Reference Applications: ReferenceApplications.md - Configure STM32 Devices with STM32CubeMX: CubeMX.md