Open-CMSIS-Pack · jkrech · Aug 14, 2024 · Aug 13, 2024 · Aug 14, 2024 · Aug 14, 2024
diff --git a/docs/README.md b/docs/README.md
@@ -72,15 +72,17 @@ The build steps are:
 
 ## Command Line and IDE Usage
 
-The CMSIS-Toolbox is a set of command line tools that is designed for stand-alone usage and integration into IDEs or DevOps (for CI workflows).
+The CMSIS-Toolbox is a set of command line tools that are designed for stand-alone usage and integration into IDEs or DevOps systems for Continuous Integration (CI) workflows.
 
 ![Operation of `csolution` tool](./images/tool-overview.png "Operation of `csolution` tool")
 
+The [VS Code](https://marketplace.visualstudio.com/items?itemName=Arm.keil-studio-pack) IDE integration available from Arm is a viewer to the [*csolution project files*](YML-Input-Format.md) and provides graphical ways to modify the content. Refer to [DevOps Usage](build-tools.md#devops-usage) for more information on integration into CI workflows.
+
 ## Benefits
 
 The overall benefits of the CMSIS-Toolbox are:
 
-- Flexible CLI tools that can be used stand-alone or integrated into [VS Code](https://marketplace.visualstudio.com/items?itemName=Arm.keil-studio-pack) or DevOps systems for Continuous Integration (CI).
+- Flexible command line tools that can be used stand-alone or integrated into [VS Code](https://marketplace.visualstudio.com/items?itemName=Arm.keil-studio-pack) or [DevOps systems for Continuous Integration (CI)](build-tools.md#devops-usage).
 - Stand-alone tools are available [for all host platforms](https://artifacts.keil.arm.com/cmsis-toolbox/) (Windows, Mac, Linux) for flexible deployment.
 - [Software Packs](https://www.keil.arm.com/packs/) simplify tool setup with `device:` or `board:` selection and project creation with access to reusable software components.
 - Organize solutions with projects that are independently managed simplifies a wide range of use cases including  multi-processor applications or unit testing.

diff --git a/docs/YML-Input-Format.md b/docs/YML-Input-Format.md
@@ -470,62 +470,19 @@ Keyword                          | Description
 
 ### `cdefault:`
 
-When [`cdefault:`](#solution) is specified in the `*.csolution.yml` file, the **`csolution` Project Manager** uses a file with the name `cdefault.yml` or `cdefault.yaml` to setup 
-the compiler along with some specific default controls. The search order for this file is:
+When [`cdefault:`](#solution) is specified in the `*.csolution.yml` file, the **`csolution` Project Manager** uses a file with the name [`cdefault.yml`](build-overview.md#cdefaultyml) to setup 
+the compiler with specific default controls. The search order for this file is:
 
-- A `cdefault.yml` or `cdefault.yaml` file in the same directory as the `<solution-name>.csolution.yml` file. 
-- A `cdefault.yml` or `cdefault.yaml` file in the directory specified by the environment variable [`CMSIS_COMPILER_ROOT`](https://github.com/Open-CMSIS-Pack/cmsis-toolbox/blob/main/docs/installation.md#environment-variables).
-- A `cdefault.yml` or `cdefault.yaml` file in the directory [`<cmsis-toolbox-installation-dir>/etc`](https://github.com/Open-CMSIS-Pack/cmsis-toolbox/blob/main/docs/installation.md##etccmake).
+- A [`cdefault.yml`](build-overview.md#cdefaultyml) file in the same directory as the `<solution-name>.csolution.yml` file. 
+- A [`cdefault.yml`](build-overview.md#cdefaultyml) file in the directory specified by the environment variable [`CMSIS_COMPILER_ROOT`](https://github.com/Open-CMSIS-Pack/cmsis-toolbox/blob/main/docs/installation.md#environment-variables).
+- A [`cdefault.yml`](build-overview.md#cdefaultyml) file in the directory [`<cmsis-toolbox-installation-dir>/etc`](https://github.com/Open-CMSIS-Pack/cmsis-toolbox/blob/main/docs/installation.md##etccmake).
 
-The `default:` node is the start of a `cdefault.yml` or `cdefault.yaml` file and contains the following.
+The `default:` node is the start of a [`cdefault.yml`](build-overview.md#cdefaultyml) file and contains the following.
 
-`default:`                                                | Content
+`default:`                                                |            | Content
 :---------------------------------------------------------|:-----------|:------------------------------------
-&nbsp;&nbsp;&nbsp; [`select-compiler:`](#select-compiler) |  Optional  | Lists the possible compiler selection that this project is tested with. 
-&nbsp;&nbsp; [`compiler:`](#compiler)                     |  Optional  | Toolchain selection.
-&nbsp;&nbsp; [`misc:`](#misc)                             |  Optional  | Literal tool-specific controls.
-
-**Example:**
-
-```yml
-default:
-
-  compiler: AC6
-
-  misc:
-    - for-compiler: AC6
-      C-CPP:
-        - -Wno-macro-redefined
-        - -Wno-pragma-pack
-        - -Wno-parentheses-equality
-        - -Wno-license-management
-      C:
-        - -std=gnu11
-      ASM:
-        - -masm=auto
-      Link:
-        - --entry=Reset_Handler
-        - --map
-        - --info summarysizes
-        - --summary_stderr
-        - --diag_suppress=L6314W
-
-    - for-compiler: GCC
-      ASM:
-        - -gdwarf-4
-      C-CPP:
-        - -masm-syntax-unified
-        - -fomit-frame-pointer
-        - -ffunction-sections
-        - -fdata-sections
-        - -gdwarf-4
-      C:
-        - -std=gnu11
-      Link:
-        - --specs=nano.specs
-        - -Wl,-Map=$elf()$.map
-        - -Wl,--gc-sections
-```
+&nbsp;&nbsp; [`compiler:`](#compiler)                     |  Optional  | Toolchain selection (usage will be deprecated in CMSIS-Toolbox 3.0; specify in [`*.csolution.yml`](#solution) instead).
+&nbsp;&nbsp; [`misc:`](#misc)                             |  Optional  | Literal tool-specific controls. Refer to [Build Overview - `cdefault.yml`](build-overview.md#cdefaultyml) for an example.
 
 ### `solution:`
 
@@ -535,11 +492,10 @@ The `solution:` node is the start of a `*.csolution.yml` file that collects rela
 `solution:`                                          |            | Content
 :----------------------------------------------------|:-----------|:------------------------------------
 &nbsp;&nbsp;&nbsp; `created-by:`                     |  Optional  | Identifies the tool that created this solution.
-&nbsp;&nbsp;&nbsp; `created-for:`                    |  Optional  | Specifies the tool for building this solution, i.e. **CMSIS-Toolbox@2.2.0**
+&nbsp;&nbsp;&nbsp; `created-for:`                    |  Optional  | Specifies the tool for building this solution, i.e. **CMSIS-Toolbox@2.5.0**
 &nbsp;&nbsp;&nbsp; `description:`                    |  Optional  | Brief description text of this solution.
 &nbsp;&nbsp;&nbsp; [`select-compiler:`](#select-compiler) |  Optional  | Lists the possible compiler selection that this project is tested with. 
-&nbsp;&nbsp;&nbsp; `cdefault:`                       |  Optional  | When specified, the [`cdefault.yml`](#cdefault) file is used to setup compiler specific controls. 
-&nbsp;&nbsp;&nbsp; [`compiler:`](#compiler)          |  Optional  | Overall toolchain selection for this solution.
+&nbsp;&nbsp;&nbsp; [`cdefault:`](#cdefault)          |  Optional  | When specified, the [`cdefault.yml`](build-overview.md#cdefaultyml) file is used to setup compiler specific controls. 
 &nbsp;&nbsp;&nbsp; [`compiler:`](#compiler)          |  Optional  | Overall toolchain selection for this solution.
 &nbsp;&nbsp;&nbsp; [`language-C:`](#language-c)      |  Optional  | Set the language standard for C source file compilation.
 &nbsp;&nbsp;&nbsp; [`language-CPP:`](#language-cpp)  |  Optional  | Set the language standard for C++ source file compilation.
@@ -797,18 +753,21 @@ rte:
 
 Toolchain options may be used at various places such as:
 
-- [`solution:`](#solution) level to specify options for a collection of related projects
-- [`project:`](#projects) level to specify options for a project
+- [`solution:`](#solution) level to specify options for a collection of related projects.
+- [`project:`](#projects) level to specify options for a project.
 
 ### `select-compiler:`
 
 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. 
 
-> **Note:** 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
 :-----------------------------------------------------------|:-----------|:-------------------------------------------
-`- compiler:`                                               |**Required**| Path and file name of `<regions_file>.h`, used to 
+`- compiler:`                                               |**Required**| Specifies a supported compiler.
 
 **Example:**
 
@@ -839,7 +798,7 @@ compiler: GCC              # Select GCC Compiler
 ```
 
 ```yml
-compiler: [email protected]       # Select Arm Compiler version 6
+compiler: [email protected]       # Select Arm Compiler version 6.18.0
 ```
 
 ### `linker:`
@@ -1965,6 +1924,8 @@ The CMSIS-Toolbox supports pre-build and post-build steps that utilize external
 
 Execute and external command for pre or post build steps used in `*.csolution.yml` and `*.cproject.yml` files. The `input:` and `output:` files are used for dependency checking and schedule the execution (as pre-build or post-build step) during the build process.
 
+Other CMake Build scripts may be integrated into the overall build process using the `executes:` node. Refer to [Build Operation - CMake Integration](build-operation.md#cmake-integration) for an example that utilizes a file converter for web site images.
+
 The structure of the `executes:` node is:
 
 `executes:`                                 |              | Content

diff --git a/docs/build-operation.md b/docs/build-operation.md
@@ -22,6 +22,8 @@ This chapter explains the overall build process that of the CMSIS-Toolbox and ho
     - [Steps](#steps)
     - [CMake Variables](#cmake-variables)
       - [`BRANCHPROT` Values](#branchprot-values)
+  - [CMake Integration](#cmake-integration)
+    - [Example](#example)
   - [Generator Integration](#generator-integration)
     - [Generator Start via `component`](#generator-start-via-component)
     - [Global Generator Registry File](#global-generator-registry-file)
@@ -74,6 +76,7 @@ cbuild setup <name>.csolution.yml [--packs] [--context-set] [--update-rte] [--fr
 
 Typical IDE environments use a `--context-set` that specifies the [context](build-overview.md#context) configuration of the application. For the application program that is described with the `<name>.csolution.yml` project these steps are executed:
 
+- Schema check for YML file syntax of all project files specified by `<name>.csolution.yml`.
 - Check correctness of all project files specified by `<name>.csolution.yml`.
 - Evaluate the potential [software layers](YML-CBuild-Format.md#configurations) for [Reference Applications](ReferenceApplications.md) that use `variables:` to refer to layers, but the value is undefined. All projects are considered in this step.
 - Evaluate the [selectable compiler toolchains](YML-CBuild-Format.md#select-compiler) when the *csolution project* does not contain a `compiler:` selection or the `--toolchain` option is not applied. The available toolchains are based on the [compiler registration](installation.md#compiler-registration) and the `select-compiler:` node in the file [`<name>.csolution.yml`](YML-Input-Format.md#solution) or [`cdefault.yml`](YML-Input-Format.md#cdefault).
@@ -198,6 +201,73 @@ CMake Variable                                   | Description
 `CMAKE_C_COMPILER_ID`                            | CMake compiler identifier
 `CMAKE_C_COMPILER_VERSION`                       | CMake compiler version
 
+## CMake Integration
+
+The [`executes:`](YML-Input-Format.md#executes) node in the *csolution project* files allows to integrate other CMake projects or scripts.
+
+### Example
+
+The following `CMakeLists.txt` file integrates the [FCARM file converter](https://arm-software.github.io/MDK-Middleware/latest/Network/group__nw__sw__util__fcarm.html) that is part of the MDK Middleware. The FCARM file converter reformats all web files into a single C-file which is then included and compiled into the project. 
+
+```cmake
+# CMakeLists.txt for calling FCARM
+# Find input files in the input base directory and in its subfolders using recursive scanning
+# Format arguments and generate a steering command file, overcoming any command line length limitation
+# Call FCARM using the steering command file, generating the source file in the expected output  
+#
+# Configuration Step: ${CMAKE_COMMAND} -G <generator> -S <source directory> -B <build directory> -DINPUT_DIRECTORY=<input base directory> -DOUTPUT=<output source file>
+# Build Step: ${CMAKE_COMMAND} --build <build directory>
+#
+# <generator>: underlying generator build system, e.g. Ninja
+# <source directory>: directory where this CMakeLists.txt resides
+# <build directory>: directory for temp files
+# <input base directory>: directory where input data is located
+# <output source file>: path and filename of source file to be generated
+
+cmake_minimum_required(VERSION 3.22)
+include(ExternalProject)
+
+project("FCARM" NONE)
+
+file(GLOB_RECURSE INPUT ${INPUT_DIRECTORY}/*)
+
+foreach(ITEM ${INPUT})
+  cmake_path(RELATIVE_PATH ITEM BASE_DIRECTORY ${INPUT_DIRECTORY} OUTPUT_VARIABLE FILE)
+  list(APPEND FILES ${FILE})
+endforeach()
+string(REPLACE ";" ",\n" FILES "${FILES}")
+
+cmake_path(RELATIVE_PATH OUTPUT BASE_DIRECTORY ${INPUT_DIRECTORY} OUTPUT_VARIABLE RELATIVE_OUTPUT)
+cmake_path(GET INPUT_DIRECTORY FILENAME INPUT_DIRECTORY_NAME)
+cmake_path(GET INPUT_DIRECTORY PARENT_PATH WORKING_DIRECTORY)
+
+set(COMMAND_FILE "${CMAKE_CURRENT_BINARY_DIR}/Auto_FcArm_Cmd.inp")
+file(WRITE ${COMMAND_FILE} "${FILES}\nTO ${RELATIVE_OUTPUT} RTE NOPRINT ROOT(${INPUT_DIRECTORY_NAME})\n")
+
+add_custom_target(FCARM ALL DEPENDS ${OUTPUT})
+add_custom_command(OUTPUT ${OUTPUT} DEPENDS ${INPUT}
+  COMMAND fcarm @${COMMAND_FILE} 
+  WORKING_DIRECTORY ${WORKING_DIRECTORY}
+)
+```
+
+Integration in a *csolution project*. In this case it is part of the `*.csolution.yml`, but it may be also part of `*.cproject.yml` file that uses the source file `Web.c` as input. The CMake build system checks for project dependencies and schedules the overall build process.
+
+```yml
+solution:
+  :
+
+  executes:
+    - execute: Run FCARM
+      run: ${CMAKE_COMMAND} -G Ninja -S ${INPUT_0} -B ${CMAKE_CURRENT_BINARY_DIR}/fcarm-cmake -DINPUT_DIRECTORY=${INPUT_1} -DOUTPUT=${OUTPUT} && ${CMAKE_COMMAND} --build ${CMAKE_CURRENT_BINARY_DIR}/fcarm-cmake -- --quiet
+      always:
+      input:
+        - fcarm-cmake    # CMake script directory
+        - Web            # Input directory with "web files" for FCARM
+      output:
+        - project/Web.c  # Output file for FCARM
+```
+
 ## Generator Integration
 
 The diagram below shows how a generator is integrated into the CMSIS build process. The data flow is exemplified on STM32CubeMX (Generator ID for this example is `CubeMX`). The information about the project is delivered to the generator using the [Generator Information](YML-CBuild-Format.md#generator-information-files) files (`<csolution-name>.cbuild-gen-idx.yml` and `<context>.cbuild-gen.yml`). This information provides `CubeMX` with the project context, such as selected board or device, and CPU mode such as TrustZone disabled/enabled.