/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
/**
\page CmdLineBuild Command Line Build 

The following \b Bash scripts and command line tools can be used for managing the build of CMSIS Projects from the command line.
These scripts can be easily adopted to specific environments and are intended as a minimal reference.
CMSIS-Build tools are available for download as an asset of the respective 
<a href="https://github.com/ARM-software/CMSIS_5/releases/" target="_blank"><b>CMSIS Release Version</b></a> 
(starting with 5.7.0).

For command line build with software packs, the following tools and utilities are provided.

| Tool/Script                                 | Description                                                               |
|:--------------------------------------------|:--------------------------------------------------------------------------|
| \subpage cbuild_install "cbuild_install.sh" | Setup of the CMSIS command line build environment                         |
| \subpage cp_init "cp_init.sh"               | Create an empty directory for storing software packs in CMSIS-Pack format |
| \subpage cbuild "cbuild.sh"                 | Start the overall command line build process                              |
| \subpage cbuildgen "cbuildgen"              | Create Make or CMakeLists.txt file and manage software layers             |
| \subpage cmake "CMake"                      | CMake utility to generate binary images                                   |
| \subpage cp_install "cp_install.sh"         | Download and install software packs                                       |

\note
- For the above command line build tools and scripts  a
  <a href="https://en.wikipedia.org/wiki/Bash_(Unix_shell)" target="_blank"><b>Bash</b></a> environment is required.  For
  Windows, install for example <a href="https://gitforwindows.org/" target="_blank"><b>git for Windows</b></a> which includes
  <b>Git Bash</b>. 
- All Bash scripts show a reference implementation and can be easily adopted to the user's needs. They can also be replaced
  by other scripts written in Python for example. The only tool you still require is \ref cbuildgen "cbuildgen".
*/


/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
/**
\page cbuild_install Setup Script for the Build Environment

The command line build environment for projects that are based on the CMSIS-Pack standard requires:
  - Required: <a href="https://en.wikipedia.org/wiki/Bash_(Unix_shell)" target="_blank"><b>Bash</b></a> for script execution.
  - Optional: \ref libxml "xmllint" for XML schema verification.

With most Linux distributions these tools are already available.  The installation for Windows is explained below.

<b>Required for Windows: Bash</b>
  - <a href="https://gitforwindows.org/" target="_blank"><b>git for Windows</b></a> includes <b>Git Bash</b> which is easy
    to download and install.
  

\section cbuild_install2 Invocation

CMSIS-Build tools are available for download as an asset of the respective 
<a href="https://github.com/ARM-software/CMSIS_5/releases/" target="_blank"><b>CMSIS Release Version</b></a> 
(starting with 5.7.0).

To install the command line build environment start from the Bash prompt:
\code
 $ ./cbuild_install.sh
\endcode

This install script queries for:
  - Directory for the installation of the CMSIS command line build tools (default ./cbuild).
  - When Keil MDK is installed, enter the base directory of the MDK installation (default /c/Keil_v5).
  - Directory to store the content of the software packs in CMSIS-Pack format.

\section cbuild_envsetup Environment Variables

The file <b>./cbuild/etc/setup</b> configures the CMSIS command line build environment.
It contains the following section that should reflect the actual installation.

<b>File: ./cbuild/etc/setup</b>
\code
############### EDIT BELOW ###############

export CMSIS_PACK_ROOT=/C/Users/myname/AppData/Local/Arm/Packs
export CMSIS_COMPILER_ROOT=/C/myname/cbuild
export MDK_ROOT=/C/Keil_v5
\endcode

The file <b>./cbuild/etc/setup</b> is used to setup environment variables in Bash using the <b>source</b> command:
\code
$ source ./cbuild/etc/setup
\endcode

\n

| Variable                | Description                                                      |
|:------------------------|:-----------------------------------------------------------------|
|\c $CMSIS_PACK_ROOT      | Directory that contains the software packs in CMSIS-Pack format. |
|\c $CMSIS_COMPILER_ROOT  | Directory that contains the \ref cbuild_compiler_config.         |
|\c $CMSIS_BUILD_ROOT     | Base directory of the CMSIS command line build tools.            |
|\c $MDK_ROOT             | Base directory of the MDK installation (optional).               |


\section cbuild_compiler_config Compiler Configuration

\ref cbuildgen "cbuildgen" uses toolchain specific <b>.cmake files</b> that map the CMSIS project
settings to the toolchain. For each supported toolchain a <b>.cmake file</b> is provided in
the directory <b>./cbuild/etc</b> and specifies the base directory of the toolchain installation(\c TOOLCHAIN_ROOT).
In addition other toolchain specific environment variables may be setup here (e.g. license file and
product variant). The user is required to update the these settings after installation to reflect the actual installation.

<b>Example file: ./cbuild/etc/ARMCC.6.16.0.cmake</b>

\code
# Version: 0.10.0
# Date: 2020-09-30
# This file maps the CMSIS project options to toolchain settings.
#
#   - Applies to toolchain: ARMCC 6.16.0
#
############### EDIT BELOW ###############
# Set base directory of toolchain
TOOLCHAIN_ROOT:=C:/Keil_v5/ARM/ARMCLANG

############ DO NOT EDIT BELOW ###########
\endcode

The toolchain for compilation is defined in project file <b>*.cprj</b> and used by \ref cbuildgen "cbuildgen". 
\ref cbuildgen "cbuildgen" first searches for the toolchain specific <b>.cmake file</b> in the project directory.
If the toolchain specific <b>.cmake file</b> is not present there, it uses the directory that is specified
by the \b $CMSIS_BUILD_ROOT environment variable.

\section libxml libxml (optional for Windows)

For Windows the <a href="https://www.zlatkovic.com/pub/libxml/" target="_blank"><b>libxml</b></a> provides an XML processor that provides 
the functionality of <b>xmllint</b>.  

\note The installation is optional and not required to run the command line build tools.

Download the following ZIP files:
  - <b>iconv-1.9.2.win32.zip</b>
  - <b>libxml2-2.7.8.win32.zip</b>
  - <b>libxmlsec-1.2.18.win32.zip</b>
  - <b>zlib-1.2.5.win32.zip</b>

Extract the \b /bin directory of each ZIP file to a directory, for example \b C:\\xmllint and add this directory to the Windows
<a href="https://answers.microsoft.com/en-us/windows/forum/windows_10-other_settings/adding-path-variable/97300613-20cb-4d85-8d0e-cc9d3549ba23" target="_blank"><b>PATH</b></a> environment variable.

\note Restart the <b>Git Bash</b> after changing the <b>PATH</b> environment variable.
\note When <b>xmllint</b> is not installed, the XML schema verification is skipped by the \ref cbuild "cbuild.sh" script.

xmllint is also provided by the xsltproc package that can be installed via <a href="https://chocolatey.org/packages/xsltproc" target="_blank"><b>Chocolatey</b></a>: 
\code
> choco install xsltproc
\endcode
*/

/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
/**
\page cp_init cp_init.sh: Setup Pack Directory

The \b cp_init.sh script is used to setup a build environment from scratch. It downloads the public
<a href="https://www.keil.com/pack/index.pidx" target="_blank">CMSIS-Pack index file</a> and stores this catalog file in
the pack directory under ./Web. This file is used by \ref cbuildgen "cbuildgen" to find the latest version of the public
software packs.


\section cp_init_invocation Invocation

It is called from the \b Bash command line with the following syntax:

\code
cp_init.sh [<pack-directory>]
\endcode

\b Where:

\c cp_init.sh is the name of the script.

<\c pack-directory> specifies the directory where software packs should be stored. If not specified, the \c $CMSIS_PACK_ROOT
directory is used.

\section cp_init_example Usage Example

\verbatim
$ cp_init.sh ./packrepo
(cp_init.sh): Setup Pack Directory 0.10.0 (C) 2020 ARM
info: reading directory: ./packrepo
downloading package index file from
######################################################################## 100.0%
pack repository created successfully
Please setup environment variable CMSIS_PACK_ROOT to:
/c/cbuild/packrepo
\endverbatim

\section cp_init_errors Error Messages
<table class="cmtable" summary="cp_init messages">
  <tr>
    <th>Type</th>
    <th>Message</th>
    <th>Action</th>
  </tr>
  <tr>
    <td>ERROR</td>
    <td>error: no argument passed and CMSIS_PACK_ROOT environment variable not set</td>
    <td>See usage and correct the argument.</td>
  </tr>
  <tr>
    <td>ERROR</td>
    <td>error: more than one command line argument passed</td>
    <td>See usage and correct the argument.</td>
  </tr>
  <tr>
    <td>ERROR</td>
    <td>error: directory already exists. Cannot create new pack repository</td>
    <td>See usage and correct the argument.</td>
  </tr>
  <tr>
    <td>ERROR</td>
    <td>error: index.pidx download failed</td>
    <td>Check internet connection and server availability.</td>
  </tr>
  <tr>
    <td>ERROR</td>
    <td>error: downloaded file is not an xml file</td>
    <td>Check downloaded file.</td>
  </tr>
  <tr>
    <td>INFO</td>
    <td>info: no argument passed - using CMSIS_PACK_ROOT environment variable</td>
    <td>For information only.</td>
  </tr>
  <tr>
    <td>INFO</td>
    <td>pack repository created successfully</td>
    <td>For information only.</td>
  </tr>
</table>
*/

/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
/**
\page cbuild cbuild.sh: Build Invocation

\b cbuild.sh implements the build flow by chaining the utilities \ref cbuildgen "cbuildgen" and
<b>CMake</b>. It replicates the build steps of CMSIS-Pack aware IDEs and also copies configuration files from packs if necessary. The
script can be adopted to project specific requirements or replaced by a custom implementation (for example a Python script).

The build flow of the \b cbuild.sh script is:
 - Call \ref cbuildgen "cbuildgen" with command \c packlist to list the URLs of missing software packs.
 - Call \ref cp_install "cp_install.sh" to download and install missing software packs.
 - Call \ref cbuildgen "cbuildgen" with command \c cmake to generate a CMakeLists.txt file (if \c \--cmake is specified).
 - Call \ref cmake "cmake" to compile the project source code into the binary image using the specified \c \<BuildSystem>.
 

\section cbuild_invocation Invocation

It is called from the \b Bash command line with the following syntax:

\code
$ cbuild.sh <ProjectFile>.cprj [--toolchain=<Toolchain> --outdir=<OutDir> --intdir=<IntDir> --update=<CprjFile> --jobs=<N> --log=<LogFile> --quiet <CMakeTarget>]
\endcode

\b Where:

\c cbuild.sh is the name of the script.

<\c ProjectFile> specifies the project file in CMSIS project format.

\b Operation

<table class="cmtable" summary="cbuild Arguments">
  <tr>
    <th style="min-width:210px">Option</th>
    <th>Description</th>
  </tr>
  <tr>
    <td>\--toolchain=\<Toolchain></td>
    <td>Specifies the selected toolchain for projects that support multiple compilers.</td>    
  </tr>
  <tr>
    <td>\--outdir=\<OutDir></td>
    <td>Specifies the output directory (for log files, binaries, and map files).</td>    
  </tr>
  <tr>
    <td>\--intdir=\<IntDir></td>
    <td>Specifies the directory for intermediate files (such as generated make files, list of missing packs
  (\c cpinstall), command files, object files, and dependency files).</td>
  </tr>
  <tr>
    <td>\<CMakeTarget></td>
    <td>Specifies the <\c target> option for \ref cmake "CMake".</td>
  </tr>
  <tr>
    <td>\--quiet</td>
    <td>Suppresses output messages except build invocations.</td>
  </tr>
  <tr>
    <td>\--clean</td>
    <td>Removes intermediate and output directories.</td>
  </tr>
  <tr>
    <td>\--update=\<CprjFile></td>
    <td>Generates <tt>\<CprjFile></tt> with fixed versions for reproducing the current build.</td>
  </tr>
  <tr>
    <td>\--help</td>
    <td>Opens this documentation.</td>
  </tr>
  <tr>
    <td>\--log=\<LogFile></td>
    <td>Saves output messages in a log file.</td>
  </tr>
  <tr>
    <td>\--jobs=\<N></td>
    <td>Specifies the number of job slots for the underlying build system parallel execution. Minimum 1.</td>
  </tr>
  <tr>
    <td>\[--cmake=\<BuildSystem>]</td>
    <td>Selects the build system, default <b>Ninja</b>.</td>
  </tr>
</table>


\section cbuild_example Usage Example

<b>CMake based build</b>

\verbatim
$ cbuild.sh Blinky.B-L475E-IOT01A.cprj --cmake
(cbuild.sh): Build Invocation 0.10.0 (C) 2020 ARM
Blinky.B-L475E-IOT01A.cprj validates
(cbuildgen): Build Process Manager 0.10.1-nightly+343 (C) 2020 ARM
M650: Command completed successfully.
(cbuildgen): Build Process Manager 0.10.1-nightly+343 (C) 2020 ARM
M652: Generated makefile for project build: 'C:/Blinky/B-L475E-IOT01A/Objects/CMakeLists.txt'
-- The C compiler identification is ARMClang 6.15.2
-- Configuring done
-- Generating done
-- Build files have been written to: C:/Blinky/B-L475E-IOT01A/Objects
[1/49] Building C object CMakeFiles\image.dir\C_\Users\user\AppData\Local\Arm\Packs\Keil\B-L475E-IOT01A_BSP\1.0.0\Drivers\B-L475E-IOT01\stm32l475e_iot01.o
[2/49] Building C object CMakeFiles\image.dir\C_\Users\user\AppData\Local\Arm\Packs\Keil\B-L475E-IOT01A_BSP\1.0.0\Drivers\Components\lsm6dsl\lsm6dsl.o
[3/49] Building C object CMakeFiles\image.dir\C_\Users\user\AppData\Local\Arm\Packs\Keil\B-L475E-IOT01A_BSP\1.0.0\Drivers\B-L475E-IOT01\stm32l475e_iot01_gyro.o
...
[47/49] Building C object CMakeFiles\image.dir\C_\Blinky\B-L475E-IOT01A\RTE\Device\STM32L475VGTx\system_stm32l4xx.o
[48/49] Building C object CMakeFiles\image.dir\C_\Blinky\B-L475E-IOT01A\RTE\Device\STM32L475VGTx\STCubeGenerated\Src\stm32l4xx_it.o
[49/49] Linking C executable image.axf
Program Size: Code=20968 RO-data=784 RW-data=328 ZI-data=37412
cbuild.sh finished successfully!
\endverbatim

\section cbuild_errors Error Messages

<table class="cmtable" summary="cbuild messages">
  <tr>
    <th>Type</th>
    <th>Message</th>
    <th>Action</th>
  </tr>
  <tr>
    <td>ERROR</td>
    <td>error: missing required argument <\c project>.cprj</td>
    <td>See usage and correct the argument.</td>
  </tr>
  <tr>
    <td>ERROR</td>
    <td>error: project file <\c project>.cprj does not exist</td>
    <td>Check project file.</td>
  </tr>
  <tr>
    <td>ERROR</td>
    <td>error: CMSIS_BUILD_ROOT environment variable not set</td>
     <td>Set \ref cbuild_envsetup.</td>
  </tr>
  <tr>
    <td>ERROR</td>
    <td>cmake ${output}${project}.cprj failed!</td>
    <td>Check CMake error messages.</td>
  </tr>
  <tr>
    <td>INFO</td>
    <td>cbuild.sh finished successfully!</td>
    <td>For information only.</td>
  </tr>
</table>
*/


/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
/**
\page cbuildgen cbuildgen: Build Process Manager

\b cbuildgen is the core tool for the build process. It uses information from the CMSIS project file *.cprj, software packs,
and environment variables.

 - The *.cprj file lists all software packs (optionally with version), configuration files, and user files along with
   toolchain specific options.
 - Software packs are used to get source and include files of software components. The location of software packs is defined
   with the environment variable \c $CMSIS_PACK_ROOT.
 - The version of configuration files is specified in project file *.cprj and related software packs are used to update it.
 - Device information is read from the device family pack (DFP) that defines the device.
 - Command line options for a toolchain is used from the <b>\<name>.\<version>.cmake</b> file, if not present in the project
   file directory, the \c $CMSIS_COMPILER_ROOT is used.


 \section cbuildgen_invocation Invocation

 \b cbuildgen is called from the \b Bash command line with the following syntax:

\code
cbuildgen <ProjectFile>.cprj <command> [<args>]
\endcode

<b>Where:</b>

\c cbuildgen is the name of tool.

<\c ProjectFile> is the name of the project file. The file extension (.cprj) is mandatory.

<\c command> specifies the operation of \c cbuildgen (see table below). Only one command is permitted per invocation.

[\c &lt;args>] are additional arguments that control the operation of a command.

\b Operation

<table class="cmtable" summary="cbuildgen commands">
  <tr>
    <th style="min-width:100px">&lt;command></th>
    <th style="min-width:175px">&lt;arguments></th>
    <th style="min-width:185px">Description</th>
    <th style="min-width:175px">Details</th>
  </tr>
  <tr>
    <td>packlist</td>
    <td></td>
    <td>List missing packs.</td>    
    <td>Check the current list of installed packs in the directory <tt>$CMSIS_PACK_ROOT</tt>. The URLs of missing packs are written to <tt>\<ProjectFile\>.cpinstall</tt> file.</td>
  </tr>
  <tr>
    <td rowspan="3"></td>
    <td>\--toolchain=&lt;Toolchain></td>
    <td>Select the toolchain.</td>    
    <td>For projects that can be built with multiple toolchains, it defines the toolchain for the build.</td>
  </tr>
  <tr>
    <td>\--intdir=&lt;IntDir></td>
    <td>Intermediate files output directory.</td>
    <td>Output directory for the list of missing packs (cpinstall).</td>    
  </tr>
  <tr>
    <td>\--quiet</td>
    <td>Suppress messages.</td>    
    <td>Suppresses all tool messages except build progress and result information.</td>
  </tr>
  <tr>
    <td rowspan="6"></td>
    <td>\--toolchain=&lt;Toolchain></td>
    <td>Select the toolchain.</td>    
    <td>For projects that can be built with multiple toolchains, it defines the toolchain for the build.</td>
  </tr>
  <tr>
    <td>\--update=&lt;CprjFile></td>
    <td>Create fixed version CPRJ file.</td>    
    <td>Generate <tt>\<CprjFile></tt> with fixed versions for reproducing the current build.</td>
  </tr>
  <tr>
    <td>\--outdir=&lt;OutDir></td>
    <td>Build output directory.</td>    
    <td>Set output directory for binary executables, as well as log and map files.</td>
  </tr>
  <tr>
    <td>\--intdir=&lt;IntDir></td>
    <td>Intermediate files output directory.</td>
    <td>Output directory for generated CMakeLists, list of missing packs (cpinstall), command files, object files, and dependency files.</td>    
  </tr>
  <tr>
    <td>\--quiet</td>
    <td>Suppress messages.</td>    
    <td>Suppresses all tool messages except build progress and result information.</td>
  </tr>
  <tr>
    <td>cmake</td>
    <td></td>
    <td>Generate CMakeLists.txt file.</td>    
    <td>Generates <tt>CMakeLists.txt</tt> file for \ref cmake "CMake" required to build the project. 
        This command also generates a ASCII log file <tt>\<ProjectFile\>.clog</tt> recording location and version of the selected toolchain,
        packs, components and config files.
    </td>
  </tr>
  <tr>
    <td rowspan="5"></td>
    <td>\--toolchain=&lt;Toolchain></td>
    <td>Select the toolchain.</td>    
    <td>For projects that can be built with multiple toolchains, it defines the toolchain for the build.</td>
  </tr>
  <tr>
    <td>\--update=&lt;CprjFile></td>
    <td>Create fixed version CPRJ file.</td>    
    <td>Generate <tt>\<CprjFile></tt> with fixed versions for reproducing the current build.</td>
  </tr>
  <tr>
    <td>\--outdir=&lt;OutDir></td>
    <td>Build output directory.</td>    
    <td>Set output directory for binary executables, as well as log and map files.</td>
  </tr>
  <tr>
    <td>\--intdir=&lt;IntDir></td>
    <td>Intermediate files output directory.</td>
    <td>Output directory for generated CMakeLists, list of missing packs (cpinstall), command files, object files, and dependency files.</td>    
  </tr>
  <tr>
    <td>\--quiet</td>
    <td>Suppress messages.</td>    
    <td>Suppresses all tool messages except build progress and result information.</td>
  </tr>
  <tr>
    <td>extract</td>
    <td></td>
    <td>Extract layer from project</td>
    <td>Creates a sub directory named <tt>./Layer/\<layername>/</tt> for each layer described in <tt>\<ProjectFile\>.cprj</tt>. These folders
    contain a layer description file <tt>\<layername>.clayer</tt> and the project and configuration files belonging to the layer.
    </td>
  </tr>
  <tr>
    <td rowspan="3"></td>
    <td>\--layer=&lt;Layer1..N></td>
    <td>Optional layer ID.</td>    
    <td>Specifies the layer name (ID) to be extracted. This option can be specified multiple times to select multiple layers.</td>
  </tr>
  <tr>
    <td>\--outdir=&lt;OutDir></td>
    <td>Output directory.</td>    
    <td>Set the output directory for the extracted layers.</td>
  </tr>
  <tr>
    <td>\--quiet</td>
    <td>Suppress messages.</td>    
    <td>Suppresses all tool messages except build progress and result information.</td>
  </tr>
  <tr>
    <td>remove</td>
    <td></td>
    <td>Remove layer from project</td>
    <td>Updates the <tt>\<ProjectFile\>.cprj</tt> removing the layer description as well as all associated files and components for the 
        layers specified at the command line. The command deletes the associated files from the respective project directory.
    </td>
  </tr>
  <tr>
    <td rowspan="2"></td>
    <td>\--layer=&lt;Layer1..N></td>
    <td>Optional layer ID.</td>    
    <td>Specifies the layer name (ID) to be removed. This option can be specified multiple times to remove multiple layers.</td>
  </tr>
  <tr>
    <td>\--quiet</td>
    <td>Suppress messages.</td>    
    <td>Suppresses all tool messages except build progress and result information.</td>
  </tr>
  <tr>
    <td>compose</td>
    <td></td>
    <td>Create new project</td>
    <td>Create new <tt>\<ProjectFile\>.cprj</tt> from layer files (<tt>[...]/\<layername>.clayer</tt>) as well as copying associated files.
        One or more clayer files are required.
    </td>
  </tr>
  <tr>
    <td rowspan="2"></td>
    <td>&lt;1.clayer> .. &lt;N.clayer></td>
    <td>Layer description file(s).</td>    
    <td>Specifies the layer description file(s) that are used to create the project. Please specify with full path.</td>
  </tr>
  <tr>
    <td>\--quiet</td>
    <td>Suppress messages.</td>    
    <td>Suppresses all tool messages except build progress and result information.</td>
  </tr>
  <tr>
    <td>add</td>
    <td></td>
    <td>Add layer to project</td>
    <td>Updates the <tt>\<ProjectFile\>.cprj</tt> adding the layer description as well as all associated files and components for the 
        clayer files specified at the command line. The command copies the associated files from the layer directory into the project
        directory. One or more clayer files are required.
    </td>
  </tr>
  <tr>
    <td rowspan="2"></td>
    <td>&lt;1.clayer> .. &lt;N.clayer></td>
    <td>Layer description file(s).</td>    
    <td>Specifies the layer description file(s) that are added to the project. Please specify with full path.</td>
  </tr>
  <tr>
    <td>\--quiet</td>
    <td>Suppress messages.</td>    
    <td>Suppresses all tool messages except build progress and result information.</td>
  </tr>
</table>

Note: \b cbuildgen does not update the *.cprj for commands \c packlist, \c cmake and \c extract.


\section cbuildgen_example Usage Examples

<b>Create a list of missing packs</b>

\verbatim
$ cbuildgen Simulation.cprj packlist
(cbuildgen): Build Process Manager 0.9.1 (C) 2020 ARM
M654: URL 'http://www.keil.com/pack/ARM.CMSIS.5.6.0.pack' was added to the list of missing packages.
M654: URL 'http://www.keil.com/pack/Keil.ARM_Compiler.1.6.1.pack' was added to the list of missing packages.
M650: Command completed successfully.
\endverbatim

<b>Extract a specific layer from the CPRJ file</b>

\verbatim
$ cbuildgen Simulation.cprj extract --layer=Board --outdir=Layer
(cbuildgen): Build Process Manager 0.9.1 (C) 2020 ARM
M650: Command completed successfully.
\endverbatim

\note

The layer information is stored in <tt>./Layer/Board/Board.clayer</tt>.

<b>Create a new CPRJ file from a specific list of layers</b>

\verbatim
$ cbuildgen NewProject.cprj compose Layer/App/App.clayer Layer/Board/Board.clayer
(cbuildgen): Build Process Manager 0.9.1 (C) 2020 ARM
M650: Command completed successfully.
\endverbatim


\section cbuildgen_errors Error Messages

<table class="cmtable" summary="cbuildgen invocation messages">
  <tr>
    <th>Message Number</th>
    <th>Type</th>
    <th>Description</th>
    <th>Action</th>
  </tr>
<tr><td>M200</td> <td>ERROR</td> <td>Invalid arguments!</td>
  <td>At least one argument is wrong. See usage and correct the argument.</td>
</tr>
<tr><td>M201</td> <td>ERROR</td> <td>Too many arguments!</td>
  <td>There is more arguments passed than allowed. See usage and correct the command line.</td>
<tr><td>M202</td> <td>ERROR</td> <td>No CPRJ input file was specified</td>
  <td>A *.cprj file is not provided as an argument. </td>
</tr>
<tr><td>M203</td> <td>ERROR</td> <td>Error reading file(s) ...!</td>
  <td>The listed file could not be read. Check file content.</td>
</tr>
<tr><td>M204</td> <td>ERROR</td> <td>File not found: ...!</td>
  <td>The listed file was not found.</td>
</tr>
<tr><td>M205</td> <td>ERROR</td> <td>$CMSIS_PACK_ROOT environment variable is not defined!</td>
  <td>The tool requires the environment variable $CMSIS_PACK_ROOT to locate the CMSIS Packs.</td>
</tr>
<tr><td>M206</td> <td>ERROR</td> <td>No command was specified!</td>
  <td>The tool requires a command. See usage information for available commands (e.g. packlist, cmake)</td>
</tr>
<tr><td>M207</td> <td>ERROR</td> <td>Multiple commands were specified!</td>
  <td>More than one command was provided in arguments. A single command is required.</td>
</tr>
<tr><td>M208</td> <td>ERROR</td> <td>Error copying file ...!</td>
  <td>The specified file could not be copied and will be missing during build.</td>
</tr>
<tr><td>M500</td> <td>ERROR</td> <td>RTE Model reports: <i>MSG</i></td>
  <td>Error while preparing data. See message for more details.</td>
</tr>
<tr><td>M502</td> <td>ERROR</td> <td>RTE Model reports: <i>\#error NUM: NAME : MSG</i></td>
  <td>Additional software components required.</td>
</tr>
<tr><td>M504</td> <td>ERROR</td> <td>RTE Model reports: MISSING: – <i>SPACE NAME</i></td>
  <td>Add the missing component.</td>
</tr>
<tr><td>M600</td> <td>ERROR</td> <td>Package index was not found in 'PATH/.Web</td>
  <td>Check the package repository.</td>
</tr>
<tr><td>M601</td> <td>ERROR</td> <td>Package 'VENDOR.NAME' was not found in package index!</td>
  <td>Check the package repository.</td>
</tr>
<tr><td>M602</td> <td>ERROR</td> <td>Package 'VENDOR.NAME.VER' was not found!</td>
  <td>Check the package repository.</td>
</tr>
<tr><td>M603</td> <td>ERROR</td> <td>No version of package 'VENDOR.NAME' was found!</td>
  <td>Check the package repository.</td>
</tr>
<tr><td>M604</td> <td>ERROR</td> <td>Unresolved package component: 'CMP'</td>
  <td>Check project description file.</td>
</tr>
<tr><td>M605</td> <td>ERROR</td> <td>Wrong CPRJ specification!</td>
  <td>Check project description file.</td>
</tr>
<tr><td>M606</td> <td>ERROR</td> <td>Device 'DEV (VENDOR)' was not found!</td>
  <td>Check project description file.</td>
</tr>
<tr><td>M607</td> <td>ERROR</td> <td>RTE Model construction failed!</td>
  <td>The CMSIS-Pack engine reports an error message.</td>
</tr>
<tr><td>M608</td> <td>ERROR</td> <td>No toolchain configuration file for 'NAME' version 'VER" was found!</td>
  <td>Check CMSIS_COMPILER_ROOT or add the required toolchain configuration file to the project directory.</td>
</tr>
<tr><td>M609</td> <td>ERROR</td> <td>Missing 'NAME' element in CPRJ file!</td>
  <td>Check project description file.</td>
</tr>
<tr><td>M610</td> <td>ERROR</td> <td>Project supports multiple toolchains. Select one with the option --toolchain</td>
  <td>See usage and correct the argument.</td>
</tr>
<tr><td>M611</td> <td>ERROR</td> <td>Selected toolchain is not supported by the project</td>
  <td>Check project description file or command line arguments.</td>
</tr>
<tr><td>M630</td> <td>WARNING</td> <td>Device ... is substituted by device variant ... .</td>
  <td>Instead of the device specified by the project a variant found for this device is used.</td>
</tr>
<tr><td>M650</td> <td>INFO</td> <td>Setup run successfully</td>
  <td>For information only.</td>
</tr>
<tr><td>M652</td> <td>INFO</td> <td>Generated file for project build:'%NAME%'</td>
  <td>For information only.</td>
</tr>
<tr><td>M653</td> <td>INFO</td> <td>Local config file ... was not found. Copying default file from package.</td> 
  <td>Please validate whether the config file is intentionally missing. The default config file may be missing project specific settings.</td> 
</tr>
<tr><td>M654</td> <td>INFO</td> <td>URL ... was added to the list of missing packages.</td>
  <td>For information only.</td>
</tr>
<tr><td>M655</td> <td>INFO</td> <td>CMSIS_COMPILER_ROOT environment variable was not set!</td>
  <td>For information only.</td>
</tr>
<tr><td>M656</td> <td>INFO</td> <td>Package 'VENDOR.NAME.VER' was found in local repository 'PATH'!</td>
  <td>For information only.</td>
</tr>
</table>
*/


/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
/**
\page cp_install cp_install.sh: Install Packs

The \c cp_install "cp_install.sh" script gets a list of URLs that refer to software packs in CMSIS-Pack format that should 
be downloaded and installed.


\section cp_install_invocation Invocation

\b cp_install is called from the \b Bash command line with the following syntax:

\code
cp_install.sh <pack-list-file> 
\endcode

<b>Where:</b>

\c cp_install is the name of the script.

<\c pack-list-file> is a text file that contains a URL list.

The \c cp_install script reads a text file that contains a URL list of software packs in CMSIS-Pack format. The URL list has
the following format: \c \<url>/\<vendor>.\<packname>.\<version>.pack. Below is an example:
\code
  https://www.keil.com/pack/ARM.CMSIS.5.6.0.pack
  https://www.keil.com/pack/ARM.CMSIS-Driver.2.5.0.pack
\endcode

For each URL in this list the following operations are performed:
  1. Download the related software pack from the URL.
  2. Extract the content of the software pack.
  
The following directories are used to store software pack.  The naming conventions for directories is based on the CMSIS-Pack specification.

| Directory                                                         | Description                                                                        |
|:------------------------------------------------------------------|:-----------------------------------------------------------------------------------|
| <b>${CMSIS_PACK_ROOT}/.Download</b>                               | Stores the downloaded software pack                                                |
| <b>${CMSIS_PACK_ROOT}/&lt;vendor>/&lt;packname>/&lt;version></b>  | Extracted content of the software pack (naming according CMSIS-Pack specification) | 

\note  The environment variable \c $CMSIS_PACK_ROOT must reference an existing directory with at least the file ./Web/index.pidx. The directory structure can be created with \ref cp_init


\section cp_install_example Usage Example

\verbatim$
cp_install.sh Simulation.cpinstall
(cp_install.sh): Install Packs 0.10.0 (C) 2020 ARM
info: reading file: Simulation.cpinstall
dos2unix: converting file Simulation.cpinstall to Unix format...
http://www.keil.com/pack/ARM.CMSIS.5.6.0.pack
######################################################################## 100.0%#=#=#
######################################################################## 100.0%
info: ARM.CMSIS.5.6.0.pack installing into /c/arm/cbuild/packs/ARM/CMSIS/5.6.0
http://www.keil.com/pack/Keil.ARM_Compiler.1.6.1.pack
######################################################################## 100.0%#=#=#
######################################################################## 100.0%
info: Keil.ARM_Compiler.1.6.1.pack installing into /c/arm/cbuild/packs/Keil/ARM_Compiler/1.6.1
pack installation completed successfully
\endverbatim

\section cp_install_errors Error Messages

<table class="cmtable" summary="cp_install messages">
  <tr>
    <th>Type</th>
    <th>Message</th>
    <th>Action</th>
  </tr>
  <tr>
    <td>ERROR</td>
    <td>error: missing command line argument</td>
    <td>See usage and correct argument.</td>
  </tr>
  <tr>
    <td>ERROR</td>
    <td>error: too many command line arguments</td>
    <td>See usage and correct argument.</td>
  </tr>
  <tr>
    <td>ERROR</td>
    <td>error: $filename does not exist</td>
    <td>See usage and correct argument.</td>
  </tr>
  <tr>
    <td>ERROR</td>
    <td>error: CMSIS_PACK_ROOT environment variable not set</td>
    <td>Set \ref cbuild_envsetup.</td>
  </tr>
  <tr>
    <td>ERROR</td>
    <td>error: CMSIS_PACK_ROOT: folder does not contain package index file .Web/index.pidx</td>
    <td>Check pack repository.</td>
  </tr>
  <tr>
    <td>ERROR</td>
    <td>error: pack download failed for $pack_url</td>
    <td>Check internet connection and server availability.</td>
  </tr>
  <tr>
    <td>ERROR</td>
    <td>error: downloaded file $packfile is not a zip/pack file</td>
    <td>Check list of missing packages in cpinstall file.</td>
  </tr>
  <tr>
    <td>ERROR</td>
    <td>error: unzip failed for $packfile</td>
    <td>Check downloaded package.</td>
  </tr>
  <tr>
    <td>INFO</td>
    <td>info: pack $packfile is already downloaded</td>
    <td>For information only.</td>
  </tr>
  <tr>
    <td>INFO</td>
    <td>info: $packfile is already installed</td>
    <td>For information only.</td>
  </tr>
  <tr>
    <td>INFO</td>
    <td>pack installation completed successfully</td>
    <td>For information only.</td>
  </tr>
</table>
*/


/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
/**
\page cmake CMake

\b CMake is an open-source, cross-platform family of tools designed to build, test and package software. As it is not
automatically installed by \ref cp_install "cp_install.sh" script, you need to
<a href="https://cmake.org/download/" target="_blank"><b>get the software</b></a> and install it on your machine separately.

\note CMSIS-Build requires CMake 3.15 or above.


\section cmake_invocation Invocation

\b CMake is called from the \b Bash command line with the following syntax:

\code
cmake [options] <path-to-source>
\endcode 

The \ref cbuild "cbuild.sh" script calls \ref cmake "CMake" twice with these options:

<b>1. Step: Configuration</b>

<table class="cmtable" summary="cmake config options">
  <tr>
    <th>\[options]</th>
    <th>Short Name</th>
  </tr>
  <tr>
    <td>-G \<generator-name></td>
    <td>Specify a build system generator.</td>    
  </tr>
  <tr>
    <td>-S \<path-to-source></td>
    <td>Explicitly specify a source directory.</td>    
  </tr>
  <tr>
    <td>-B \<path-to-build></td>
    <td>Explicitly specify a build directory.</td>    
  </tr>
</table>

<b>2. Step: Build</b>

<table class="cmtable" summary="cmake build options">
  <tr>
    <th>\[options]</th>
    <th>Short Name</th>
  </tr>
  <tr>
    <td>\--build</td>
    <td>Build a CMake-generated project binary tree.</td>    
  </tr>
  <tr>
    <td>-j</td>
    <td>Number of parallel build jobs.</td>
  </tr>
  <tr>
    <td>\<target></td>
    <td>Target to be built.</td>
  </tr>
</table>

\note
- \b CMake supports different build systems. By default,
  <a href="https://github.com/ninja-build/ninja" target="_blank">Ninja</a> is used. As a Windows user, copy the Ninja binary
  available from <a href="https://github.com/ninja-build/ninja/releases" target="_blank">Releases</a> to the installation
  directory of CMSIS-Build: <tt>./cbuild/bin</tt> where it is invoked automatically.
*/
