From 717c56bd6b1ba1f692f6ec2f1c61dbe6889e6184 Mon Sep 17 00:00:00 2001 From: Reinhard Keil Date: Mon, 16 Dec 2024 13:33:40 +0100 Subject: [PATCH] MKDocs: corrections (#237) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Fixes formatting issue ## Checklist - [x] 🤖 This change is covered by unit tests as required. - [x] 🤹 All required manual testing has been performed. - [x] 🛡️ Security impacts have been considered. - [x] 📖 All documentation updates are complete. - [x] 🧠 This change does not change third-party dependencies --------- Co-authored-by: Joachim Krech <8290187+jkrech@users.noreply.github.com> --- docs/CreateApplications.md | 62 ++++++++++------- docs/CubeMX.md | 6 +- docs/MCUXpressoConfig.md | 6 +- docs/README.md | 3 + docs/ReferenceApplications.md | 12 ++-- docs/YML-Input-Format - Preinclude.md | 58 ++++++++-------- docs/YML-Input-Format.md | 95 ++++++++++++++------------- docs/build-operation.md | 16 ++--- docs/build-overview.md | 52 ++++++++------- docs/build-tools.md | 11 ++-- docs/index.html | 28 ++++---- docs/installation.md | 91 +++++++++++++------------ docs/overview.md | 2 +- docs/pack-tools.md | 10 +-- mkdocs.yml | 2 +- test/data/build-asm/project/.clangd | 6 ++ 16 files changed, 250 insertions(+), 210 deletions(-) create mode 100644 docs/README.md diff --git a/docs/CreateApplications.md b/docs/CreateApplications.md index c0b9bca..bfcf437 100644 --- a/docs/CreateApplications.md +++ b/docs/CreateApplications.md @@ -11,13 +11,17 @@ The following chapter explains the structure of a software pack and how it can b An application is based on a *device* and/or *board* supported by a Device Family Pack (DFP) or Board Support Pack (BSP). The steps to start a project are: -1. Step: **Install the DFP and BSP** - - Use [Device search](https://www.keil.arm.com/devices/) or [Board search](https://www.keil.arm.com/boards/) available on web portals to identify the software packs required for your target. - - Download the Device Family Pack (DFP) and optionally the Board Support Pack (BSP) with [`cpackget`](build-tools.md#install-public-packs). Note that a BSP is only required if you want to work with a specific board. For custom hardware, typically the DFP is sufficient. +### Step 1: Install the DFP and BSP + +- Use [Device search](https://www.keil.arm.com/devices/) or [Board search](https://www.keil.arm.com/boards/) available on web portals to identify the software packs required for your target. + +- Download the Device Family Pack (DFP) and optionally the Board Support Pack (BSP) with [`cpackget`](build-tools.md#install-public-packs). Note that a BSP is only required if you want to work with a specific board. For custom hardware, typically the DFP is sufficient. -2. Step: **Use a Template Project and add DFP and BSP** - - Select a suitable generic [Template Project](https://github.com/Open-CMSIS-Pack/csolution-examples/tree/main/Templates) or refer to the DFP documentation as some devices have specific template projects. - - Copy the template project and open the `*.csolution.yml` file. Add under [`packs:`](YML-Input-Format.md#packs) the packs identified in step (1). You may omit the version number during initial project development. +### Step 2: Use a Template Project and add DFP and BSP + +- Select a suitable generic [Template Project](https://github.com/Open-CMSIS-Pack/csolution-examples/tree/main/Templates) or refer to the DFP documentation as some devices have specific template projects. + +- Copy the template project and open the `*.csolution.yml` file. Add under [`packs:`](YML-Input-Format.md#packs) the packs identified in step (1). You may omit the version number during initial project development. ```yml : @@ -28,9 +32,11 @@ An application is based on a *device* and/or *board* supported by a Device Famil : ``` -3. Step: **Use `csolution list` to identify the device or board** - - Use `csolution list devices .csolution.yml` or `csolution list boards .csolution.yml` to get the device or board name. - - Enter the device or board name under [`target-types:`](YML-Input-Format.md#target-types). A device is typically used for custom hardware. +### Step 3: Use `csolution list` to identify the device or board + +- Use `csolution list devices .csolution.yml` or `csolution list boards .csolution.yml` to get the device or board name. + +- Enter the device or board name under [`target-types:`](YML-Input-Format.md#target-types). A device is typically used for custom hardware. ```yml : @@ -41,9 +47,11 @@ An application is based on a *device* and/or *board* supported by a Device Famil : ``` -4. Step: **Add required software components** - - Most projects at least require the `CMSIS:CORE` and `Device:Startup` (or a variant) [software components](#software-components) to be present. Use `csolution list components .csolution.yml` to identify the name of the startup component and add it to the file `*.cproject.yml` of your project. - - Use `csolution list components .csolution.yml` to identify additional software components from the selected packs. Use the [`components:`](YML-Input-Format.md#components) in the `.cproject.yml` file to add new components and refer to related documentation for usage instructions. Note that you may omit vendor and version information for components as this is defined already by the packs that are selected. +### Step 4: Add required software components + +- Most projects at least require the `CMSIS:CORE` and `Device:Startup` (or a variant) [software components](#software-components) to be present. Use `csolution list components .csolution.yml` to identify the name of the startup component and add it to the file `*.cproject.yml` of your project. + +- Use `csolution list components .csolution.yml` to identify additional software components from the selected packs. Use the [`components:`](YML-Input-Format.md#components) in the `.cproject.yml` file to add new components and refer to related documentation for usage instructions. Note that you may omit vendor and version information for components as this is defined already by the packs that are selected. ```yml : @@ -54,17 +62,23 @@ An application is based on a *device* and/or *board* supported by a Device Famil : ``` - - Refer to [Using Components](#using-components) for more information. - - Now, the project should already compile with the command `cbuild .csolution.yml --update-rte --packs --context .Debug`. Note that this step downloads missing packs and copies configuration files to the [RTE directory](build-overview.md#rte-directory-structure). +- Refer to [Using Components](#using-components) for more information. + +- Now, the project should already compile with the command `cbuild .csolution.yml --update-rte --packs --context .Debug`. Note that this step downloads missing packs and copies configuration files to the [RTE directory](build-overview.md#rte-directory-structure). + +### Step 5: Review and configure RTE files + +- Review the configuration files in the [RTE directory](build-overview.md#rte-directory-structure) and refer to the documentation of the software components for instructions. -5. Step: **Review and configure RTE files** - - Review the configuration files in the [RTE directory](build-overview.md#rte-directory-structure) and refer to the documentation of the software components for instructions. - - [Configure Linker Scripts](#configure-linker-scripts) below explains how to setup physical memory. - - 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. +- [Configure Linker Scripts](#configure-linker-scripts) below explains how to setup physical memory. + +- 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. -6. Step: **Add application functionality** - - Implement the application code in C/C++ source files. Use the [`groups:`](YML-Input-Format.md#groups) section in `.cproject.yml` to add new source files. +### Step 6: Add application functionality + +- Implement the application code in C/C++ source files. Use the [`groups:`](YML-Input-Format.md#groups) section in `.cproject.yml` to add new source files. ```yml : @@ -76,7 +90,7 @@ An application is based on a *device* and/or *board* supported by a Device Famil : ``` - - Again, the project should compile with the command `cbuild .csolution.yml --update-rte --packs --context .Debug`. Repeat step (4) when you added new components that require configuration. +- Again, the project should compile with the command `cbuild .csolution.yml --update-rte --packs --context .Debug`. Repeat step (4) when you added new components that require configuration. !!! Note The [Arm CMSIS Solution extension for VS Code](https://marketplace.visualstudio.com/items?itemName=Arm.cmsis-csolution) guides you through these steps with the [`Create New Solution` workflow](https://marketplace.visualstudio.com/items?itemName=Arm.cmsis-csolution#create-new-solution-view). @@ -100,8 +114,8 @@ For memory with the [*default* attribute set](https://open-cmsis-pack.github.io/ - The region \_\_ROM0 is the startup region and contains memory with the [*startup* attribute set](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/pdsc_family_pg.html#element_memory). - The region \_\_RAM0 contains uninitialized memory, STACK and HEAP. - - STACK default is 0x200. - - HEAP default is 0xC00 for devices with more than 6KB RAM (otherwise HEAP is set to 0). + - STACK default is 0x200. + - HEAP default is 0xC00 for devices with more than 6KB RAM (otherwise HEAP is set to 0). - Contiguous memory with same access (rw, rwx, rx) is combined into one region. For memory with the [*default* attribute no set](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/pdsc_family_pg.html#element_memory) in DFP or BSP, the memory is listed under **resources that are not allocated to linker regions**. diff --git a/docs/CubeMX.md b/docs/CubeMX.md index e280255..4c3f959 100644 --- a/docs/CubeMX.md +++ b/docs/CubeMX.md @@ -71,7 +71,7 @@ project: Such a project cannot be directly built, as initially the `*.cgen.yml` file is missing. It requires to run the CubeMX generator. Before you start, you may need to [`install missing packs`](build-tools.md#install-missing-packs). -1. Identify the required generator and the directory where the generated files are stored with: +- Identify the required generator and the directory where the generated files are stored with: ```bash csolution CubeMX.csolution.yml list generators --verbose @@ -81,7 +81,7 @@ CubeMX (Global Registered Generator) # generator name context: CubeMX.Release+MyBoard ``` -2. Use the information above to run the generator: +- Use the information above to run the generator: ```bash csolution CubeMX.csolution.yml run --generator CubeMX --context CubeMX.Debug+MyBoard @@ -89,7 +89,7 @@ csolution CubeMX.csolution.yml run --generator CubeMX --context CubeMX.Debug+MyB This starts CubeMX and passes the information about the selected board, device, and select toolchain. For a project that selects a board, CubeMX imports the default configuration for it. In CubeMX, review and adjust configuration options as required for your application, then just click the button `GENERATE CODE`. The generated files will be stored in the directory `STM32CubeMX/MyBoard`. -3. Build the project using this command: +- Build the project using this command: ```bash cbuild CubeMX.csolution.yml --update-rte diff --git a/docs/MCUXpressoConfig.md b/docs/MCUXpressoConfig.md index 6e48b7b..f6eb370 100644 --- a/docs/MCUXpressoConfig.md +++ b/docs/MCUXpressoConfig.md @@ -102,7 +102,7 @@ project: Such a project cannot be built directly as initially the `*.cgen.yml` file is missing. It requires to run the MCUXpresso generator. Before you start, you may need to [`install missing packs`](build-tools.md#install-missing-packs). -1. Identify the required generator and the directory where the generated files are stored with: +- Identify the required generator and the directory where the generated files are stored with: ```bash csolution Simple.csolution.yml list generators --verbose @@ -113,7 +113,7 @@ MCUXpressoConfig (Global Registered Generator MCUXpresso Config tools) context: Simple.Release+MCXN947VDF ``` -2. Using the above information to run the generator using this command: +- Using the above information to run the generator using this command: ```bash csolution Simple.csolution.yml run --generator MCUXpressoConfig --context Simple.Debug+MCXN947VDF @@ -121,7 +121,7 @@ csolution Simple.csolution.yml run --generator MCUXpressoConfig --context Simple It starts MCUXpresso and passes the information about the selected board, device, and selected toolchain. For a project that selects a board, MCUXpresso imports the default configuration for the evaluation kit. In MCUXpresso, review and adjust configuration options as required for your application, then just click the button `Update Code`. The generated files will be stored in the directory `./MCUXpressoConfig`. -3. Build the project using this command: +- Build the project using this command: ```bash cbuild Simple.csolution.yml --update-rte diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..b4e7e1f --- /dev/null +++ b/docs/README.md @@ -0,0 +1,3 @@ +# CMSIS-Toolbox Documentation + +Open the [CMSIS-Toolbox documentation](https://open-cmsis-pack.github.io/cmsis-toolbox). diff --git a/docs/ReferenceApplications.md b/docs/ReferenceApplications.md index 93d1b03..c59ffb8 100644 --- a/docs/ReferenceApplications.md +++ b/docs/ReferenceApplications.md @@ -119,7 +119,9 @@ A *Reference Application* is an incomplete `*.csolution.yml` project file that r The following steps explain how to to compile the project: -1. In the `*.csolution.yml` file under the `packs:` node, add the DFP (for the device) and the BSP (for the board). Under `target-types:`, add your board. +### Step 1: Add DFP and BSP + +In the `*.csolution.yml` file under the `packs:` node, add the DFP (for the device) and the BSP (for the board). Under `target-types:`, add your board. ```yml solution: @@ -132,8 +134,10 @@ solution: - type: MyBoard board: B-U585I-IOT02A # name of a target board ``` - -2. Run `cbuild setup` with the `*.csolution.yml` file. This identifies compatible layers with an output similar to: + +### Step 2: Run `cbuild setup` + +Run `cbuild setup` with the `*.csolution.yml` file. This identifies compatible layers with an output similar to: ```txt >cbuild setup xxx.csolution.yml @@ -142,7 +146,7 @@ error csolution: undefined variables in xxx.csolution.yml: To resolve undefined variables, copy the settings from cbuild-idx.yml to csolution.yml ``` - The related `*.cbuild-idx.yml` should contain information similar to this: +The related `*.cbuild-idx.yml` should contain information similar to this: ```yml build-idx: diff --git a/docs/YML-Input-Format - Preinclude.md b/docs/YML-Input-Format - Preinclude.md index 9fd7d1c..749fe84 100644 --- a/docs/YML-Input-Format - Preinclude.md +++ b/docs/YML-Input-Format - Preinclude.md @@ -77,12 +77,12 @@ Element | | Description 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. + - (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. + - 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. @@ -580,9 +580,8 @@ The following nodes control the directory structure for the application. Allows to control the directory structure for build output files. ->**Note:** - -This control is only possible at `csolution.yml` level. +!!! 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. @@ -622,10 +621,9 @@ The `generators:` node can be added at various levels of the `*.yml` input files 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. +!!! 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 :------------------------------|------------|:------------------------------------ @@ -662,11 +660,10 @@ generators: 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. +!!! 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 :------------------------------|------------|:------------------------------------ @@ -721,12 +718,11 @@ Refer to [Linker Script Management](build-overview.md#linker-script-management)    [`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. +!!! 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:** @@ -1122,11 +1118,9 @@ The `packs:` node can be specified in the `*.csolution.yml` file allows you to: 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. +!!! 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:` @@ -1677,9 +1671,9 @@ Add a software layer to a project. Used in `*.cproject.yml` files. - +AVH ``` -#### `layer:` - `type:` +#### `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`. +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:** @@ -1915,8 +1909,8 @@ The **`csolution` Project Manager** combines all the *key*/*value* pairs that li - 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. + - 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:` diff --git a/docs/YML-Input-Format.md b/docs/YML-Input-Format.md index 7e189cd..919efee 100644 --- a/docs/YML-Input-Format.md +++ b/docs/YML-Input-Format.md @@ -44,10 +44,9 @@ Element | | Description `@^version` | Optional | Automatically update minor/patch version, i.e. `@^1.2.3` uses releases from `1.2.3` to `< 2.0.0`. `@~version` | Optional | Automatically update patch version, i.e. `@^1.2.3` uses releases from `1.2.3` to `< 1.3.0`. -**Notes:** - -- When no version is specified, the **`csolution` Project Manager** only loads the latests installed version of a software pack. This also applies when wildcards are used in the `pack-name`. -- Use [**`cpackget`**](build-tools.md#cpackget-invocation) to download and install new pack versions. +!!!Notes + - When no version is specified, the **`csolution` Project Manager** only loads the latests installed version of a software pack. This also applies when wildcards are used in the `pack-name`. + - Use [**`cpackget`**](build-tools.md#cpackget-invocation) to download and install new pack versions. **Examples:** @@ -86,12 +85,12 @@ Element | | Description 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. + - (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. + - 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. @@ -616,10 +615,9 @@ The `generators:` node can be added at various levels of the `*.yml` input files 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. +!!! 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 :------------------------------|------------|:------------------------------------ @@ -629,7 +627,7 @@ The `generators:` node can be added at various levels of the `*.yml` input files !!! 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:` +#### `generators:` `options:` `options:` | | Content :------------------------------|------------|:------------------------------------ @@ -655,11 +653,10 @@ generators: 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. +!!! 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 :------------------------------|------------|:------------------------------------ @@ -681,10 +678,9 @@ Toolchain options may be used at various places such as: Lists the compilers that this *csolution project* is tested with. This information is used by the [`cbuild setup` command](build-operation.md#details-of-the-setup-mode) to determine possible compiler choices. The actual compiler to be used is selected with the [`compiler:`](#compiler) node. -**Notes:** - -- [`select-compiler:`](#select-compiler) is only supported in the [`*.csolution.yml`](#solution) project file. -- This control is new in CMSIS-Toolbox 2.5.0 +!!! Notes + - [`select-compiler:`](#select-compiler) is only supported in the [`*.csolution.yml`](#solution) project file. + - This control is new in CMSIS-Toolbox 2.5.0 `select-compiler:` | | Content :-----------------------------------------------------------|:-----------|:------------------------------------------- @@ -737,12 +733,11 @@ Refer to [Linker Script Management](build-overview.md#linker-script-management)    [`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. +!!! 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:** @@ -1155,11 +1150,9 @@ The `packs:` node can be specified in the `*.csolution.yml` file allows you to: 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. +!!! 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:` @@ -1763,7 +1756,7 @@ Add a software layer to a project. Used in `*.cproject.yml` files. - +AVH ``` -#### `layer:` - `type:` +#### `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`. @@ -1890,7 +1883,7 @@ The `run:` command string uses these sequences to access input files and output The `run:` command string also accepts these [access sequences](#access-sequences): $Bname$, $Dname$, $Pname$, $BuildType$, $TargetType$, $Compiler$, $Solution$, $Project$. It does not accept [access sequences](#access-sequences) that reference directories or files as this bypasses the [project dependency check](build-overview.md#project-dependency). Instead use the `input:` list to pass files or directories. -**Notes:** +Consider the following: - The `execute:` node is processed by the CMake build system. The order of execution depends on `$input$` and `$output` files and is evaluated by CMake. @@ -1953,16 +1946,26 @@ project: # executed as part of a project build Refer to [Build Operation - CMake Integration](build-operation.md) for examples that integrate CMake scripts. -## `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. +## Auto-select Layers -This enables [reference applications](ReferenceApplications.md) that work across a range of different hardware targets where: +To find compatible layers in software packs, projects and layers can be annotated. The command `csolution list layers` lists compatible layers. 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:`. + +Example projects that use `connections:` for layer selection: + +- [MDK-Middleware examples](https://arm-software.github.io/MDK-Middleware/latest/General/working_with_examples.html) use board layers to run on different hardware boards. + +- [Sensor SDK Example](https://github.com/Open-CMSIS-Pack/Sensor-SDK-Example) shows how board layers and shield layers may be used to run different sensor shields on many boards. + +- [AWS_MQTT_Demo}(https://github.com/Arm-Examples/AWS_MQTT_Demo) combines board layer and communication socket layer. Optionally a shield layer can be used to connect WiFi drivers. +### `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 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: @@ -1985,7 +1988,7 @@ The structure of the `connections:` node is: :------------------------------------|--------------|:------------------------------------ [- `connect:`](#connect) | **Required** | Lists specific functionality with a brief verbal description -### `connect:` +#### `connect:` The `connect:` node describes one or more functionalities that belong together. @@ -2029,7 +2032,7 @@ layer: - CMSIS-RTOS2 ``` -### `set:` +#### `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: @@ -2039,7 +2042,7 @@ Some hardware boards have configuration settings (DIP switch or jumper) that con Refer to [Example: Sensor Shield](#example-sensor-shield) for a usage example. -### `provides:` +#### `provides:` A user-defined *key*/*value* pair list of functionality that is implemented or provided by a `project:` or `layer:`. @@ -2047,10 +2050,10 @@ The **`csolution` Project Manager** combines all the *key*/*value* pairs that li - 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. + - 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:` +#### `consumes:` A user-defined *key*/*value* pair list of functionality that is requried or consumed by a `project:` or `layer:`. diff --git a/docs/build-operation.md b/docs/build-operation.md index d3f2353..665674e 100644 --- a/docs/build-operation.md +++ b/docs/build-operation.md @@ -33,9 +33,9 @@ It generates the application program that is described with the `.csolutio - When option `--packs` is used, it downloads missing *software packs* using [`cpackget`](build-tools.md#cpackget-invocation). - It calls [`csolution`](build-tools.md#csolution-invocation) to process the the `.csolution.yml` project. - - With option `--update-rte` new configuration files from *software packs* are updated and the [`RTE_Components.h`](build-overview.md#rte_componentsh) file is recreated. - - With option `--context-set` the file `*.cbuild-set.yml` specifies the [context](build-overview.md#context) configuration of the application. - - With option `--frozen-packs` the file `*.cbuild-pack.yml` is used as input to issue an error when a pack version changes. + - With option `--update-rte` new configuration files from *software packs* are updated and the [`RTE_Components.h`](build-overview.md#rte_componentsh) file is recreated. + - With option `--context-set` the file `*.cbuild-set.yml` specifies the [context](build-overview.md#context) configuration of the application. + - With option `--frozen-packs` the file `*.cbuild-pack.yml` is used as input to issue an error when a pack version changes. - The output are [build information files](YML-CBuild-Format.md) with all relevant project information for the build process. - The option `--toolchain` can be used to explicitly select a compiler. @@ -74,13 +74,13 @@ The operation is further controlled by options: [`csolution`](build-overview.md) processes the [*csolution project files* (in YAML format)](YML-Input-Format.md) and the `*.pdsc` metadata files of *software packs* and performs the following operations: - In the [**Project Area**](build-overview.md#project-area): - - Generate [build information files](YML-CBuild-Format.md) `*.cbuild-idx.yml` and `*.cbuild.yml` with all relevant project information for the build process. + - Generate [build information files](YML-CBuild-Format.md) `*.cbuild-idx.yml` and `*.cbuild.yml` with all relevant project information for the build process. - In the [**RTE Directory**](build-overview.md#rte-directory-structure): - - Generate for each [context](YML-Input-Format.md#context) the [RTE_components.h](build-overview.md#rte_componentsh) file and pre-include files from the software pack (`*.pdsc`) metadata. - - [Copy the configuration files](build-overview.md#plm-of-configuration-files) from selected software componentsand provide [PLM](build-overview.md#plm-of-configuration-files) information. + - Generate for each [context](YML-Input-Format.md#context) the [RTE_components.h](build-overview.md#rte_componentsh) file and pre-include files from the software pack (`*.pdsc`) metadata. + - [Copy the configuration files](build-overview.md#plm-of-configuration-files) from selected software componentsand provide [PLM](build-overview.md#plm-of-configuration-files) information. - In the [**base directory of the solution**](build-overview.md#project-area): - - Generate the file `*.cbuild-pack.yml` that records all used *software packs*. With the option `--frozen-packs` this file is used as input. - - With the option `--context-set` the file `*.cbuild-set.yml` specifies the [context](build-overview.md#context) configuration of the application. When `--context` names are specified this file is updated with this selection. + - Generate the file `*.cbuild-pack.yml` that records all used *software packs*. With the option `--frozen-packs` this file is used as input. + - With the option `--context-set` the file `*.cbuild-set.yml` specifies the [context](build-overview.md#context) configuration of the application. When `--context` names are specified this file is updated with this selection. The picture below outlines the operation. diff --git a/docs/build-overview.md b/docs/build-overview.md index 21d7a5d..a7e5044 100644 --- a/docs/build-overview.md +++ b/docs/build-overview.md @@ -31,8 +31,8 @@ The tools process *csolution project files* (in YAML format) and *software packs The overall 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. + - 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. @@ -303,7 +303,7 @@ To support reproducible builds the following files should be committed to a repo - All user source code files. - 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. + - 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). - Optionally, the file `*.cbuild-set.yml` which defines the context set of the application that should be generated. @@ -392,13 +392,13 @@ picture below shows a setup during software development that supports: As the software may share a large set of common files, provisions are required to manage such projects. The common is to add: - **target-types** (required) that select a target system. In the example this would be: - - `Virtual`: for simulation models. - - `Board`: for a physical evaluation board. - - `Production-HW`: for system integration test and product delivery on the final hardware. + - `Virtual`: for simulation models. + - `Board`: for a physical evaluation board. + - `Production-HW`: for system integration test and product delivery on the final hardware. - **build-types** (optional) add the flexibility to configure each target build towards a specific test. For example: - - `Debug`: for a full debug build of the software used in an interactive debug session. - - `Test`: for a specific timing test using a test interface with maximum code optimization. - - `Release`: for the final code deployment to the system. + - `Debug`: for a full debug build of the software used in an interactive debug session. + - `Test`: for a specific timing test using a test interface with maximum code optimization. + - `Release`: for the final code deployment to the system. **Flexible Builds for Multi-Target Projects** @@ -690,11 +690,16 @@ configuration file version. Depending on the PLM status of the application, `csolution` performs the following operation for configuration files: -1. **Add** a software component for the first time: the related config file is copied twice into the related `RTE` - project directory. The first copy can be modified by the user with the parameters for the user application. The - second copy is an unmodified backup file with the format `..base@version`. +1. **Add** a software component for the first time. +2. **Upgrade** (or downgrade) a software component. - **Example:** A configuration file `ConfigFile.h` at version `1.2.0` is copied: +#### **Add** + +When adding a software component for the first time the related config file is copied twice into the related `RTE` +project directory. The first copy can be modified by the user with the parameters for the user application. The +second copy is an unmodified backup file with the format `..base@version`. + +**Example:** A configuration file `ConfigFile.h` at version `1.2.0` is copied: ```c ./RTE/component_class/ConfigFile.h // user editable configuration file @@ -702,7 +707,7 @@ Depending on the PLM status of the application, `csolution` performs the followi // information; used as a base for version comparison ``` - `csolution` shows a user notification to indicate that files are added: +`csolution` shows a user notification to indicate that files are added: ```text ./RTE/component_class/ConfigFile.h - info: component 'name' added configuration file version '1.2.0' @@ -711,11 +716,14 @@ Depending on the PLM status of the application, `csolution` performs the followi !!! Note The unmodified files with `@version` information should be committed to the repository of the version control system as these files are used to upgrade configuration information using merge utilities. -2. **Upgrade** (or downgrade) a software component: if the version of the unmodified backup file is identical, no - operation is performed. If the version differs, the new configuration file is copied with the format - `..update@version`. +#### **Upgrade** + +When upgrade (or downgrade) a software component the version information of the configuration file is considered. - **Example:** after updating the configuration file `ConfigFile.h` to version `1.3.0`, the directory contains these files: +- If the version of the unmodified backup file is identical, no operation is performed. +- If the version differs, the new configuration file is copied with the format `..update@version`. + +**Example:** after updating the configuration file `ConfigFile.h` to version `1.3.0`, the directory contains these files: ```c ./RTE/component_class/ConfigFile.h // user editable configuration file (based on current version) @@ -724,16 +732,16 @@ Depending on the PLM status of the application, `csolution` performs the followi // information; used as a base for version comparison ``` - `csolution` displays a user notification to indicate that configuration files have changed: +`csolution` displays a user notification to indicate that configuration files have changed: ```text ./RTE/component_class/ConfigFile.h - warning: component 'name' upgrade for configuration file version '1.3.0' added, but file inactive ``` -3. **User action to complete upgrade**: The user has now several options (outside of `csolution`) to merge the - configuration file information. A potential way could be to use a 3-way merge utility. After merging the - configuration file, the original `base@version` file should be deleted and the unmodified new version should become the new `base@version`. The previous configuration file may be stored as backup as shown below. +**User action to complete upgrade** + +The user has now several options (outside of `csolution`) to merge the configuration file information. A potential way could be to use a 3-way merge utility. After merging the configuration file, the original `base@version` file should be deleted and the unmodified new version should become the new `base@version`. The previous configuration file may be stored as backup as shown below. ```c ./RTE/component_class/ConfigFile.h // new configuration file with merge configuration diff --git a/docs/build-tools.md b/docs/build-tools.md index 16cf991..8cf1341 100644 --- a/docs/build-tools.md +++ b/docs/build-tools.md @@ -189,11 +189,10 @@ It is also possible to overwrite the toolchain selection and use a different too cbuild example.csolution.yml --toolchain GCC ``` -!!! Note - The `--toolchain` option is useful for: - - - Testing a new compiler or a different compiler version on the overall project. - - For unit test applications to allow the usage of different compilers. +The `--toolchain` option is useful for: + +- Testing a new compiler or a different compiler version on the overall project. +- For unit test applications to allow the usage of different compilers. In [DevOps systems](#devops-usage) that run CI test with a matrix build, it is sometimes required to separate the output of various builds. The option `--output` adds a prefix to the [output directory](YML-Input-Format.md#output-dirs) for `outdir:`, `tmpdir:` and build information files. The following commands build the project with the AC6 and GCC compiler and separate the directories for output and temporary files. @@ -203,7 +202,7 @@ cbuild example.csolution.yml --toolchain GCC --output outGCC ``` !!! Note - The `--output` option is not recommended in an IDE environment as it changes the location of mandatory build information files that are [used by the IDE](#ide-usage). + The `--output` option may be used by an IDE environment to location build information files outside of the user space. ### Update RTE Configuration Files diff --git a/docs/index.html b/docs/index.html index d6bb344..501bfb6 100644 --- a/docs/index.html +++ b/docs/index.html @@ -1,14 +1,14 @@ - - - -Redirect to the Open-CMSIS-Pack toolbox documentation page after 0 seconds - - - - - - -If the automatic redirection is failing, click open CMSIS-Toolbox documentation. - - - + + + +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/installation.md b/docs/installation.md index e4db7fc..c3e71cb 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -7,12 +7,12 @@ This chapter explains the setup of the CMSIS-Toolbox along with a build environm There are three different ways to setup the CMSIS-Toolbox: - [Manual setup](#manual-setup) with operating system commands and environment variables. -- [vcpkg - CLI](#vcpkg-setup-using-cli) using the vcpkg tool in command-line mode -- [vcpkg - VS Code](#vcpkg-setup-in-vs-code) using the vcpkg tool with VS Code integration +- [vcpkg in CLI](#vcpkg-command-line-mode) using the vcpkg tool in command-line mode +- [vcpkg in VS Code](#vcpkg-setup-in-vs-code) using the vcpkg tool with VS Code integration ## Manual Setup -Download the CMSIS-Toolbox from the [**Arm tools artifactory**](https://artifacts.keil.arm.com/cmsis-toolbox/). Signed binaries are provided for Windows (amd64), Linux (amd64, arm64), and MacOS/Darwin (amd64, arm64) in an archive file. +Download the CMSIS-Toolbox from the [**Arm Tools Artifactory**](https://artifacts.keil.arm.com/cmsis-toolbox/). Signed binaries are provided for Windows (amd64), Linux (amd64, arm64), and MacOS/Darwin (amd64, arm64) in an archive file. To setup the **CMSIS-Toolbox** on a local computer, copy the content of the archive file to an ``, for example to `~/cmsis-toolbox`. @@ -39,7 +39,7 @@ The CMSIS-Toolbox works with the following compiler toolchains. Install one or m - [**Keil MDK**](https://www.keil.com/mdk5/install) version 5.36 or higher. - [**Arm Compiler for Embedded**](https://developer.arm.com/tools-and-software/embedded/arm-compiler/downloads/version-6) version 6.18.0 or higher - - Arm FuSa Compiler for Embedded version 6.16.2 or higher is also supported + - Arm FuSa Compiler for Embedded version 6.16.2 or higher is also supported - [**IAR EW-Arm**](https://www.iar.com/products/architectures/arm/iar-embedded-workbench-for-arm/) version 9.32.1 or higher. @@ -73,9 +73,9 @@ The environment variable **CMSIS_PACK_ROOT** and **CMSIS_COMPILER_ROOT** are opt - **CMSIS_COMPILER_ROOT** default is `/bin/../etc`, i.e., `etc` folder relative to the toolbox executables. It is used to locate: - - 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. + - 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. #### Compiler Registration @@ -93,16 +93,14 @@ The compiler toolchain is registered with an environment variable that includes set AC6_TOOLCHAIN_6_19_0=C:\Keil_v5\ARM\ARMCLANG\bin ``` +For Windows, use the dialog **System Properties - Advanced** and add the **Environment Variables** listed above. + **Example for Unix:** ```txt export GCC_TOOLCHAIN_10_3_1=/opt/gcc-arm-none-eabi-10.3-2021.10/bin ``` -#### Setup Win64 - -For Windows, use the dialog **System Properties - Advanced** and add the **Environment Variables** listed above. - **Keil MDK version 5** When using Keil MDK version 5, the CMSIS-Toolbox is shipped as part of the installer. The tools are located in the directory `.\ARM\cmsis-toolbox` of the MDK installation. @@ -117,9 +115,8 @@ environment variable is not required. The **CMSIS_COMPILER_ROOT** environment variable is not required if the compiler configuration files provided in cmsis-toolbox/etc are used. -**Notes:** - -At the Windows command prompt, use `set` to list all environment variables. +!!! Note + At the Windows command prompt, use `set` to list all environment variables. Keil µVision may be used to: @@ -162,35 +159,43 @@ cpackget init https://www.keil.com/pack/index.pidx !!! Note Arm is running a public indexing server at the URL provided. You can specify any indexing server URL if you do not wish to use this service. -## vcpkg - Setup using CLI +## vcpkg Setup using CLI -The [vcpkg](https://vcpkg.io/en/) is a management tool for packages and includes features to manage tool artifacts. Arm provides an artifactory system for tools. Refer to [Arm Tools Available in vcpkg](https://www.keil.arm.com/packages/) for more information. +The [vcpkg](https://vcpkg.io/en/) is a management tool for packages and includes features to manage tool artifacts. Arm provides an artifactory system for tools. Refer to [Arm Tools Available in vcpkg](https://artifacts.tools.arm.com) for more information. !!! Note Microsoft changed the name of the shell version from `vcpkg` to `vcpkg-shell`. Depending on the version that you are using, you may need to call `vcpkg-shell` from the command line instead of `vcpkg`. The following describes how to setup the CMSIS-Toolbox with `vcpkg` in a command line (CLI) environment. In many examples there is already the file `vcpkg-configuration.json` which describes the tool environment required for the example. Refer to the last step to create an new `vcpkg-configuration.json` file. -1. Install and enable vcpkg; the command depends on the shell. +### Install and enable vcpkg - - Windows Command Prompt (cmd) +The command to install and enable `vcpkg` depends on the shell. + +**Windows Command Prompt (cmd):** ```bat curl -LO https://aka.ms/vcpkg-init.cmd && .\vcpkg-init.cmd +``` +```bat %USERPROFILE%\.vcpkg\vcpkg-init.cmd ``` - - Windows PowerShell +**Windows PowerShell:** ```ps1 iex (iwr -useb https://aka.ms/vcpkg-init.ps1) +``` +```ps1 . ~/.vcpkg/vcpkg-init.ps1 ``` - - Linux (x64)/macOS +**Linux (x64)/macOS:** ```sh . <(curl https://aka.ms/vcpkg-init.sh -L) +``` +```sh . ~/.vcpkg/vcpkg-init ``` @@ -199,50 +204,54 @@ iex (iwr -useb https://aka.ms/vcpkg-init.ps1) - MSYS Bash (such as Git Bash) on Windows. - Linux (aarch64) -2. Activate required tools using one of the following methods: - - Prerequisite: a `vcpkg-configuration.json` file is present in the current directory or any parent directory. +### Activate tools + +The required tools are specified in the `vcpkg-configuration.json` file that is present in the current directory or any parent directory. ```txt -vcpkg activate +vcpkg-shell activate ``` !!! Note In case that activate fails, update registries to access latest versions of the tools artifacts: - `vcpkg x-update-registry --all` + `vcpkg-shell x-update-registry --all` -3. Deactivate previous configuration +### Deactivate tools + +The configuration is deactivated with: ```txt -vcpkg deactivate +vcpkg-shell deactivate ``` -4. Create a new `vcpkg-configuration.json` file with these commands: +### Create `vcpkg-configuration.json` + +To create a new `vcpkg-configuration.json` file including the artifacts cmsis-toolbox, cmake, ninja and arm-none-eabi-gcc use this sequence of commands: ```txt -vcpkg new --application -vcpkg add artifact arm:cmsis-toolbox [--version major.minor.patch] -vcpkg add artifact arm:cmake -vcpkg add artifact arm:ninja -vcpkg add artifact arm:arm-none-eabi-gcc -vcpkg activate +vcpkg-shell new --application +vcpkg-shell add artifact arm:cmsis-toolbox [--version major.minor.patch] +vcpkg-shell add artifact arm:cmake +vcpkg-shell add artifact arm:ninja +vcpkg-shell add artifact arm:arm-none-eabi-gcc +vcpkg-shell activate ``` Alternatively, you may use an existing repository, for example [github.com/Open-CMSIS-Pack/vscode-get-started]( https://github.com/Open-CMSIS-Pack/vscode-get-started) with a `vcpkg-configuration.json` file. -## vcpkg - Setup in CI +## vcpkg Command Line Mode Using vcpkg in Continuous Integration (CI) environments is basically like [using it in a CLI environment](#vcpkg-setup-using-cli). The way how `vcpkg artifacts` updates the current shell environment needs to be taken into account when creating CI -pipelines. The command `vcpkg activate` updates the current environment variables by extending `PATH` and adding +pipelines. The command `vcpkg-shell activate` updates the current environment variables by extending `PATH` and adding additional variables required by installed artifacts. These modifications are only visible in the current running shell and spawned subprocesses. This enables also manual usage on a local prompt, given a typical user runs subsequent commands from the same parent shell process. In contrast, typical CI systems such as GitHub Actions or Jenkins spawn a new sub-shell for each -step of a pipeline. Hence, modifications made to the environment in one sub-shell by running the `vcpkg activate` +step of a pipeline. Hence, modifications made to the environment in one sub-shell by running the `vcpkg-shell activate` command are not persisted into the subsequent steps. Another aspect to consider is about handling the local vcpkg cache (e.g., `~/.vcpkg`). Common practice on CI systems is @@ -255,7 +264,7 @@ GitHub Actions allow you to preserve environment settings via the files exposed in `$GITHUB_PATH` and `$GITHUB_ENV`. Refer to the custom action provided in [github.com/ARM-software/cmsis-actions - Action: vcpkg](https://github.com/ARM-software/cmsis-actions) for more information. Preserving the runners, between runs `vcpkg cache` is achieved with an `actions/cache` step preceding the -first `vcpkg activate` command. The above custom action uses this `actions/cache` step. +first `vcpkg-shell activate` command. The above custom action uses this `actions/cache` step. ### Other CI Systems @@ -266,12 +275,12 @@ In CI Systems without a vcpkg integration: ```sh . ~/.vcpkg/vcpkg-init -vcpkg activate +vcpkg-shell activate ``` -## vcpkg - Setup in VS Code +## vcpkg Setup in VS Code -1. Download & Install [Microsoft Visual Studio Code](https://code.visualstudio.com/download) for your operating system. +1. Download and install [Microsoft Visual Studio Code](https://code.visualstudio.com/download) for your operating system. 2. Launch Visual Studio Code. Using the menu `View` and open `Extensions` and install the `Keil Studio Pack` extensions. 3. Use the menu `View` and open `Source Control`. Select 'Clone Repository' and enter as url [`https://github.com/Open-CMSIS-Pack/vscode-get-started`](https://github.com/Open-CMSIS-Pack/vscode-get-started). 4. Specify the destination folder to clone to and select 'Open' when asked 'Would you like to open the cloned directory?' diff --git a/docs/overview.md b/docs/overview.md index 1957132..29180e2 100644 --- a/docs/overview.md +++ b/docs/overview.md @@ -8,7 +8,7 @@ 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: - [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 + - Arm FuSa Compiler for Embedded version 6.16.2 or higher is also supported - [Arm GNU Toolchain (GCC)](https://developer.arm.com/Tools%20and%20Software/GNU%20Toolchain) version 10.3.1 or higher - [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 diff --git a/docs/pack-tools.md b/docs/pack-tools.md index f5a4d58..f48e71a 100644 --- a/docs/pack-tools.md +++ b/docs/pack-tools.md @@ -30,13 +30,13 @@ Hands-on Tutorial | Description - Use [C startup files](https://arm-software.github.io/CMSIS_6/latest/Core/cmsis_core_files.html) that allows to use a DFP with any toolchain. - For elements use a brief description text with less than 128 characters to explain the purpose. When possible link to documentation with detailed information. - - Example: A component `Device:HAL:ENET` should not have description `ENET HAL Driver`, use `Ethernet HAL driver` instead. + - 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). + - 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: - - 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. + - 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. - Add an [overview.md file](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/element_package_description.html) that describes the overall usage of the software pack. These files are displayed on [www.keil.arm.com/packs](https://www.keil.arm.com/packs) and index by Web search engines. ## Project Examples diff --git a/mkdocs.yml b/mkdocs.yml index 389579d..e229a0c 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,4 +1,4 @@ -site_name: CMSIS-Toolbox Help +site_name: CMSIS-Toolbox repo_url: https://github.com/Open-CMSIS-Pack/cmsis-toolbox nav: - Home: index.md diff --git a/test/data/build-asm/project/.clangd b/test/data/build-asm/project/.clangd index e8a5c1f..d1852f7 100644 --- a/test/data/build-asm/project/.clangd +++ b/test/data/build-asm/project/.clangd @@ -1,2 +1,8 @@ CompileFlags: CompilationDatabase: c:\w\cmsis-toolbox\test\data\build-asm\out\project\ARMCM0\AC6 + Add: + - '-IC:/w/cmsis-toolbox/test/data/build-asm/project/RTE/_AC6_ARMCM0' + - >- + -IC:/Users/reikei01/AppData/Local/Arm/Packs/ARM/CMSIS/6.1.0/CMSIS/Core/Include + - >- + -IC:/Users/reikei01/AppData/Local/Arm/Packs/ARM/Cortex_DFP/1.1.0/Device/ARMCM0/Include