Manual updates and corrections (Open-CMSIS-Pack#441)

* Changes to YML-Format: - define:, undefine:, add-path:, del-path: (plural optional) - output-dirs: added - for-compiler: added (for group, file, and setup) - setups: added (enables compiler specific controls) - misc: C* changed to C-CPP - misc: compiler: changed to for-compiler: (now optional) * Corrected 'output-dirs:' description * Update tools/projmgr/docs/Manual/YML-Format.md Co-authored-by: Daniel Brondani <daniel.brondani@arm.com> * Update tools/projmgr/docs/Manual/YML-Format.md Co-authored-by: Daniel Brondani <daniel.brondani@arm.com> * Manual updates and corrections Co-authored-by: Daniel Brondani <daniel.brondani@arm.com>
brondani · Aug 23, 2022 · 001b850 · 001b850
1 parent 00d5edb
commit 001b850
Show file tree

Hide file tree

Showing 3 changed files with 84 additions and 23 deletions.
diff --git a/tools/cpackget/docs/cpackget.md b/tools/cpackget/docs/cpackget.md
@@ -26,16 +26,18 @@ Usage:
   cpackget [command] [flags]
 
 Available Commands:
-  help        Help about any command
-  index       Update public index
-  init        Initialize a pack root folder
-  add         Add Open-CMSIS-Pack packages
-  rm          Remove Open-CMSIS-Pack packages
-  list        List installed packs
+  add             Add Open-CMSIS-Pack packages
+  checksum-create Generates a .checksum file containing the digests of a pack
+  checksum-verify Verifies the integrity of a pack using its .checksum file
+  help            Help about any command
+  init            Initializes a pack root folder
+  list            List installed packs
+  rm              Remove Open-CMSIS-Pack packages
+  update-index    Update the public index
 
 Flags:
   -h, --help               help for cpackget
-  -R, --pack-root path     Specifies path of the CMSIS-Pack root directory, default: CMSIS_PACK_ROOT environment variable
+  -R, --pack-root string   Specifies pack root folder. Defaults to CMSIS_PACK_ROOT environment variable (default <current setting>)
   -q, --quiet              Run cpackget silently, printing only error messages
   -v, --verbose            Sets verboseness level: None (Errors + Info + Warnings), -v (all + Debugging). Specify "-q" for no messages
   -V, --version            Prints the version number of cpackget and exit

diff --git a/tools/projmgr/docs/Manual/Overview.md b/tools/projmgr/docs/Manual/Overview.md
@@ -102,18 +102,19 @@ The CMSIS-Pack repository must be present in the development environment.
 ### Invocation
 
 ```text
-CMSIS Project Manager 0.0.0+g23b6f99 (C) 2022 ARM 
+CMSIS Project Manager 1.0.0 (C) 2022 ARM
 Usage:
   csolution <command> [<args>] [OPTIONS...]
 
 Commands:
-  list packs            Print list of installed packs
+  list packs            Print list of used packs from the pack repository
+       boards           Print list of available board names
        devices          Print list of available device names
        components       Print list of available components
        dependencies     Print list of unresolved project dependencies
        contexts         Print list of contexts in a csolution.yml
        generators       Print list of code generators of a given context
-  convert               Convert cproject.yml or csolution.yml in cprj files
+  convert               Convert cproject.yml or csolution.yml to cprj files
   run                   Run code generator
   help                  Print usage
 
@@ -123,6 +124,7 @@ Options:
   -c, --context arg     Input context name <cproject>[.<build-type>][+<target-type>]
   -f, --filter arg      Filter words
   -g, --generator arg   Code generator identifier
+  -m, --missing         List only required packs that are missing in the pack repository
   -n, --no-check-schema Skip schema check
   -o, --output arg      Output directory
   -h, --help            Print usage
@@ -136,6 +138,19 @@ Print list of installed packs. The list can be filtered by words provided with t
 csolution list packs [--filter "<filter words>"]
 ```
 
+Print list of packs that are required by the `<example.csolution.yml>`.
+
+```text
+csolution list packs -s <example.csolution.yml>
+```
+
+Print list of missing packs to the file `packs.txt` that are required by the `<example.csolution.yml>` but not available in the pack repository. This missing packs might be installed using the [`cpackget`](../../../cpackget/docs/cpackget.md) tool.
+
+```text
+csolution list packs -s <example.csolution.yml> -m >packs.txt
+cpackget add -f packs.txt
+```
+
 Print list of available device names. The list can be filtered by words provided with the option `--filter`:
 
 ```text

diff --git a/tools/projmgr/docs/Manual/YML-Format.md b/tools/projmgr/docs/Manual/YML-Format.md
@@ -15,11 +15,13 @@ The following chapter explains the YML format that is used to describe the YML i
   - [`solution:`](#solution)
   - [`project:`](#project)
   - [`layer:`](#layer)
+- [List Nodes](#list-nodes)
 - [Directory Control](#directory-control)
   - [`output-dirs:`](#output-dirs)
 - [Toolchain Options](#toolchain-options)
   - [`compiler:`](#compiler)
   - [`output-type:`](#output-type)
+  - [`linker:`](#linker)
   - [`for-compiler:`](#for-compiler)
 - [Translation Control](#translation-control)
   - [`optimize:`](#optimize)
@@ -47,7 +49,7 @@ The following chapter explains the YML format that is used to describe the YML i
   - [`for-type:`](#for-type)
   - [`not-for-type:`](#not-for-type)
     - [*type list*](#type-list)
-    - [*list nodes*](#list-nodes)
+    - [*list nodes*](#list-nodes-1)
 - [Related Projects](#related-projects)
   - [`projects:`](#projects)
 - [Source File Management](#source-file-management)
@@ -92,7 +94,7 @@ vendor [:: pack-name [@[~ | >=] version] ]
 Element      |              | Description
 :------------|--------------|:---------------------
 `vendor`     | **Required** | Vendor name of the software pack.
-`pack-name`  | Optional     | Name of the software pack; wildcards (`*`, `?`, `[abc]`) can be used.<br/>- `*` matches any substring.<br/>- `?` matches any single character.<br/>- `[abc]` matches any character in the set (`a`,`b`,`c`).
+`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 sematic versioning, or `@>=1.2.3` that allows any version higher or equal.
 
 **Examples:**
@@ -357,8 +359,9 @@ The `project:` node is the start of a `*.cproject.yml` file and can contain the
 `project:`                                     |              | Content
 :----------------------------------------------|--------------|:------------------------------------
 &nbsp;&nbsp; [`description:`](#description)    |  Optional    | Project description.
-&nbsp;&nbsp; [`output-type:`](#output-type)    | **Required** | Generate executable (default) or library.
+&nbsp;&nbsp; [`output-type:`](#output-type)    |  Optional    | Generate executable (default) or library.
 &nbsp;&nbsp; [`optimize:`](#optimize)          |  Optional    | Optimize level for code generation.
+&nbsp;&nbsp; [`linker:`](#linker)              | **Required** | Instructions for the linker.
 &nbsp;&nbsp; [`debug:`](#debug)                |  Optional    | Generation of debug information.
 &nbsp;&nbsp; [`define:`](#define)              |  Optional    | Preprocessor (#define) symbols for code generation.
 &nbsp;&nbsp; [`undefine:`](#undefine)          |  Optional    | Remove preprocessor (#define) symbols.
@@ -369,8 +372,8 @@ The `project:` node is the start of a `*.cproject.yml` file and can contain the
 &nbsp;&nbsp; [`device:`](#device)              |  Optional    | Device specification.
 &nbsp;&nbsp; [`processor:`](#processor)        |  Optional    | Processor specific settings.
 &nbsp;&nbsp; [`groups:`](#groups)              | **Required** | List of source file groups along with source files.
-&nbsp;&nbsp; [`components:`](#components)      | **Required** | List of software components used.
-&nbsp;&nbsp; [`layers:`](#layers)              | **Required** | List of software layers that belong to the project.
+&nbsp;&nbsp; [`components:`](#components)      |  Optional    | List of software components used.
+&nbsp;&nbsp; [`layers:`](#layers)              |  Optional    | List of software layers that belong to the project.
 
 **Example:**
 
@@ -403,7 +406,7 @@ The `layer:` node is the start of a `*.clayer.yml` file and can contain the foll
 &nbsp;&nbsp; [`interface:`](#interface)        |  Optional    | List of consumed and provided interfaces.
 &nbsp;&nbsp; [`processor:`](#processor)        |  Optional    | Processor specific settings.
 &nbsp;&nbsp; [`groups:`](#groups)              | **Required** | List of source file groups along with source files.
-&nbsp;&nbsp; [`components:`](#components)      | **Required** | List of software components used.
+&nbsp;&nbsp; [`components:`](#components)      |  Optional    | List of software components used.
 
 **Example:**
 
@@ -426,6 +429,24 @@ layer:
         - file: tz_context.c
 ```
 
+# 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
+```
+
 # Directory Control
 
 The following node allows to control the directories used to generate the output files.  
@@ -498,6 +519,24 @@ Value                                                 | Generated Output
 output-type: lib            # Generate a library
 ```
 
+## `linker:`
+
+The `linker:` list node controls the linker operation.
+
+`linker:`                                             |              |  Content
+:-----------------------------------------------------|:-------------|:--------------------------------
+`- script:`                                           |              | Explicit file name of the linker script
+&nbsp;&nbsp; [`for-type:`](#for-type)                 |   Optional   | Include script for a list of *build* and *target* types.
+&nbsp;&nbsp; [`not-for-type:`](#not-for-type)         |   Optional   | Exclude script for a list of *build* and *target* types.
+
+**Example:**
+
+```yml
+linker:                      # Control linker operation
+  - script: .\MyProject.sct  # Explicit scatter file
+    for-type: .Debug  
+```
+
 ## `for-compiler:`
 Depending on a compiler toolchain it is possible to include *compiler-specific nodes* in the build process.
 
@@ -720,20 +759,25 @@ It is however possible to change that `setup:` settings on a [`group:`](#groups)
 &nbsp;&nbsp;&nbsp; [`undefine:`](#undefine)          |   Optional   | Remove define symbol settings for code generation.
 &nbsp;&nbsp;&nbsp; [`add-path:`](#add-path)          |   Optional   | Additional include file paths.
 &nbsp;&nbsp;&nbsp; [`del-path:`](#del-path)          |   Optional   | Remove specific include file paths.
+&nbsp;&nbsp;&nbsp; [`linker:`](#linker)              |   Optional   | Remove specific include file paths.
 &nbsp;&nbsp;&nbsp; [`misc:`](#misc)                  |   Optional   | Literal tool-specific controls.
 
 ```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
-      define:
-        - test: 11
+   - setup: GCC project setup
+     for-compiler: GCC
+     linker:
+       - script: my-project.inc
+     define:
+       - test: 11
 ```
 
 # Pack Selection
@@ -961,7 +1005,7 @@ List Node                                  | Description
 [`- layer:`](#layers)                      | At `layers:` level it is possible to control inclusion of a software layer.
 [`- 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:`](#groups)                      | At `setups:` level it is define toolchain specific options that apply to the whole project.
+[`- 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* respecting its hierarchy from top to bottom: `project` > `layer` > `component`/`group` > `file`
@@ -999,13 +1043,13 @@ The YML structure of the section `projects:` is:
   projects:
     - project: ./CM0/CM0.cproject.yml      # specify cproject.yml file
       for-type: +CM0                       # specify use case
-      for-compiiler: GCC
+      for-compiler: GCC
       define:
         - test: 12
 
     - project: ./CM0/CM0.cproject.yml      # specify cproject.yml file
       for-type: +CM0                       # specify use case
-      for-compiiler: AC6
+      for-compiler: AC6
       define:
         - test: 9