diff --git a/docs/README.md b/docs/README.md index c2677b7..0ecbcef 100644 --- a/docs/README.md +++ b/docs/README.md @@ -98,7 +98,7 @@ The overall benefits of the CMSIS-Toolbox are: Version | Description :------------------|:------------------------- -2.5.0 | CMSIS-Toolbox [2.5.0](https://github.com/Open-CMSIS-Pack/cmsis-toolbox/releases/tag/2.4.0); direct CMake interface is now default, [`tmpdir:`](YML-Input-Format.md#output-dirs) controls location of interim files, adds [`add-asm-path:`](YML-Input-Format.md#add-asm-path), adds [regular expression](YML-Input-Format.md#regular-expressions) search to `for-context:`/`not-for-context`, and contains several corrections. +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-asm-path:`](YML-Input-Format.md#add-asm-path), 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) when using the option [`--cbuild2cmake`](build-tools.md#direct-cmake-interface), 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. diff --git a/docs/YML-Input-Format.md b/docs/YML-Input-Format.md index b80b5e0..3d6e92f 100644 --- a/docs/YML-Input-Format.md +++ b/docs/YML-Input-Format.md @@ -112,14 +112,14 @@ File Extension | [Category](https://open-cmsis-pack.github.io/Open-CMS The **`csolution` Project Manager** uses the following syntax to specify the `pack:` names in the `*.yml` files. ```yml -vendor [:: pack-name [@[~ | >=] version] ] +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. +`version` | Optional | Version number of the software pack, with `@1.2.3` that must exactly match, or `@>=1.2.3` that allows any version higher or equal. > **Note:** > @@ -140,7 +140,7 @@ Element | | Description 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] +[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. @@ -153,7 +153,7 @@ Element | | Description `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. +`Cversion` | Optional | Version number of the component, with `@1.2.3` that must exactly match, or `@>=1.2.3` that allows any version higher or equal. **Partly defined components** @@ -2083,6 +2083,39 @@ The `connect:` node describes one or more functionalities that belong together. [`provides:`](#provides) | Optional | List of functionality (*key*/*value* pairs) that are provided [`consumes:`](#consumes) | Optional | List of functionality (*key*/*value* pairs) that are required +The behaviour of the `connect:` node depends on the usage in *csolution project* files. + +- In a `cproject.yml` file the `connect:` node is always active. +- In a `clayer.yml` file the `connect:` node is only active if one or more `key` listed under `provides:` is listed under `consumes:` in other active `connect:` nodes. It is also active by default if the `connect:` node has no `provides:` node. + +**Example:** + +In the example below the `connect` for: + +- `Sensor Communication Interface` is only active when the `SENSOR_I2C` is in the `consumes:` list of other active `connect` nodes. +- `Sensor Interrupt` is only active when the `SENSOR_INT` is in the `consumes:` list of other active `connect` nodes. +- `Core Functionality` is always active as it has not `provides:` list. + +```yml +layer: + type: Shield + + connections: + - connect: Sensor Communication Interface + provides: + - SENSOR_I2C + consumes: + - ARDUINO_UNO_I2C + - connect: Sensor Interrupt + provides: + - SENSOR_INT + consumes: + - ARDUINO_UNO_D2 + - connect: Core Functionality + consumes: + - CMSIS-RTOS2 +``` + ### `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: diff --git a/docs/build-tools.md b/docs/build-tools.md index 97f7596..f6ac7e4 100644 --- a/docs/build-tools.md +++ b/docs/build-tools.md @@ -86,7 +86,7 @@ Options: -j, --jobs int Number of job slots for parallel execution (default 8) -l, --load arg Set policy for packs loading [latest | all | required] (default "required") --log arg Save output messages in a log file - -O, --output arg Set directory for all output files + -O, --output arg Add prefix to 'outdir' and 'tmpdir' -p, --packs Download missing software packs with cpackget -q, --quiet Suppress output messages except build invocations -r, --rebuild Remove intermediate and output directories and rebuild @@ -142,7 +142,7 @@ Options: -m, --missing List only required packs that are missing in the pack repository -n, --no-check-schema Skip schema check -N, --no-update-rte Skip creation of RTE directory and files - -o, --output arg Output directory + -O, --output arg Add prefix to 'outdir' and 'tmpdir' -q, --quiet Run silently, printing only error messages -R, --relative-paths Print paths relative to project or ${CMSIS_PACK_ROOT} -S, --context-set Select the context names from cbuild-set.yml for generating the target application @@ -243,11 +243,11 @@ cbuild example.csolution.yml --toolchain GCC > - Testing a new compiler or new compiler version on the overall project. > - For unit test applications to allow the usage of different compilers. -In CI systems that run a matrix build it is sometimes required to add a top-level prefix to the output directory: +In CI systems that run a matrix build it is sometimes required to add a prefix to the [output directory](YML-Input-Format.md#output-dirs) names for `outdir:` and `tmpdir:`. The following command builds the project with the AC6 and GCC compiler and separates the directories for output and temporary files. ```bash cbuild example.csolution.yml --toolchain AC6 --output outAC6 -cbuild example.csolution.yml --toolchain GCC --output outAC6 +cbuild example.csolution.yml --toolchain GCC --output outGCC ``` ### Direct CMake Interface @@ -443,13 +443,20 @@ There are different ways to install software packs. The commands below install software packs from a public web service. The available packs along with download URL and version information are listed in the **Pack Index File**. -Install the latest published version of a public software pack: +Check if a pack exists. If it does not exist install the latest version of a public software pack: ```bash -~ $ cpackget add Vendor.PackName # or +~ $ cpackget add Vendor.PackName # or ~ $ cpackget add Vendor::PackName ``` +Update an installed pack to the latest version of a public software pack: + +```bash +~ $ cpackget add Vendor.PackName@latest # or +~ $ cpackget add Vendor::PackName@latest +``` + Install a specific version of a public software pack: ```bash @@ -464,6 +471,12 @@ Install a public software pack using version modifiers: ~ $ cpackget add Vendor::PackName@~x.y.z` # check if there is any version greater than or equal to x.y.z ``` +Install latest version of a public software pack with the same major version. Within the rules of semantic versioning only compatible packs are used. + +```bash +~ $ cpackget add "Vendor::PackName@^x.y.z"` # check if there is any version greater than or equal to x.y.z, install latest +``` + #### Install a list of software packs Frequently a list of software packs should be installed that are used by a project. An ASCII file can specify a list of