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 $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 <name>.<version>.cmake file, if not present in the project file directory, the $CMSIS_COMPILER_ROOT is used.

Invocation

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

cbuildgen <ProjectFile>.cprj <command> [<args>]

Where:

cbuildgen is the name of tool.

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

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

[<args>] are additional arguments that control the operation of a command.

Operation

<command>	<arguments>	Description	Details
packlist		List missing packs.	Check the current list of installed packs in the directory `$CMSIS_PACK_ROOT`. The URLs of missing packs are written to `<ProjectFile>.cpinstall` file.
	--toolchain=<Toolchain>	Select the toolchain.	For projects that can be built with multiple toolchains, it defines the toolchain for the build.
	--intdir=<IntDir>	Intermediate files output directory.	Output directory for the list of missing packs (cpinstall).
	--quiet	Suppress messages.	Suppresses all tool messages except build progress and result information.
	--toolchain=<Toolchain>	Select the toolchain.	For projects that can be built with multiple toolchains, it defines the toolchain for the build.
	--update=<CprjFile>	Create fixed version CPRJ file.	Generate `<CprjFile>` with fixed versions for reproducing the current build.
	--outdir=<OutDir>	Build output directory.	Set output directory for binary executables, as well as log and map files.
	--intdir=<IntDir>	Intermediate files output directory.	Output directory for generated CMakeLists, list of missing packs (cpinstall), command files, object files, and dependency files.
	--quiet	Suppress messages.	Suppresses all tool messages except build progress and result information.
	cmake	Generate CMakeLists.txt file.	Generates `CMakeLists.txt` file for CMake required to build the project. This command also generates a ASCII log file `<ProjectFile>.clog` recording location and version of the selected toolchain, packs, components and config files.
	--toolchain=<Toolchain>	Select the toolchain.	For projects that can be built with multiple toolchains, it defines the toolchain for the build.
	--update=<CprjFile>	Create fixed version CPRJ file.	Generate `<CprjFile>` with fixed versions for reproducing the current build.
	--outdir=<OutDir>	Build output directory.	Set output directory for binary executables, as well as log and map files.
	--intdir=<IntDir>	Intermediate files output directory.	Output directory for generated CMakeLists, list of missing packs (cpinstall), command files, object files, and dependency files.
	--quiet	Suppress messages.	Suppresses all tool messages except build progress and result information.
extract		Extract layer from project	Creates a sub directory named `./Layer/<layername>/` for each layer described in `<ProjectFile>.cprj`. These folders contain a layer description file `<layername>.clayer` and the project and configuration files belonging to the layer.
	--layer=<Layer1..N>	Optional layer ID.	Specifies the layer name (ID) to be extracted. This option can be specified multiple times to select multiple layers.
	--outdir=<OutDir>	Output directory.	Set the output directory for the extracted layers.
	--quiet	Suppress messages.	Suppresses all tool messages except build progress and result information.
remove		Remove layer from project	Updates the `<ProjectFile>.cprj` 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.
	--layer=<Layer1..N>	Optional layer ID.	Specifies the layer name (ID) to be removed. This option can be specified multiple times to remove multiple layers.
	--quiet	Suppress messages.	Suppresses all tool messages except build progress and result information.
compose		Create new project	Create new `<ProjectFile>.cprj` from layer files (`[...]/<layername>.clayer`) as well as copying associated files. One or more clayer files are required.
	<1.clayer> .. <N.clayer>	Layer description file(s).	Specifies the layer description file(s) that are used to create the project. Please specify with full path.
	--name=<ProjectName>	Set project name.	Set `<ProjectName>` as the info name element in the new `<ProjectFile>.cprj` file.
	--description=<ProjectDescription>	Set project description.	Set `<ProjectDescription>` as the info description element in the new `<ProjectFile>.cprj` file.
	--quiet	Suppress messages.	Suppresses all tool messages except build progress and result information.
add		Add layer to project	Updates the `<ProjectFile>.cprj` 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.
	<1.clayer> .. <N.clayer>	Layer description file(s).	Specifies the layer description file(s) that are added to the project. Please specify with full path.
	--quiet	Suppress messages.	Suppresses all tool messages except build progress and result information.

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

Usage Examples

Create a list of missing packs

$ cbuildgen Simulation.cprj packlist
(cbuildgen): Build Process Manager 1.0.0 (C) 2022 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.

Extract a specific layer from the CPRJ file

$ cbuildgen Simulation.cprj extract --layer=Board --outdir=Layer
(cbuildgen): Build Process Manager 1.0.0 (C) 2022 ARM
M650: Command completed successfully.

Note

The layer information is stored in ./Layer/Board/Board.clayer.

Create a new CPRJ file from a specific list of layers

$ cbuildgen NewProject.cprj compose Layer/App/App.clayer Layer/Board/Board.clayer
(cbuildgen): Build Process Manager 1.0.0 (C) 2022 ARM
M650: Command completed successfully.

Error Messages

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