Clarified --output option/connections: node. Removed ~ for pack/c…

…omponent version (Open-CMSIS-Pack#151)
soumeh01 · Jul 4, 2024 · fa4cc3d · fa4cc3d
1 parent dfe4074
commit fa4cc3d
Show file tree

Hide file tree

Showing 3 changed files with 57 additions and 11 deletions.
diff --git 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
@@ -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 - `<component>` 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 `<components>` element of the software pack.
 `Csub`     | Optional     | Component sub-group name as defined in `<components>` element of the software pack.
 `Cvariant` | Optional     | Component sub-group name as defined in `<components>` 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
@@ -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