Code Generation Options¶

package setting generator.cpp.clangFormatFile¶

Type:	String

Specifies a path to a .clang-format file that specifies how the generated C++ code should be formatted using Clang Format. This path is interpreted relative to the Coco.toml file.

See also

generator.cpp.clangFormatFile to provide a path to be given to a .clang-format file.

package setting generator.cpp.cocoRuntimeHeaderPrefix¶

Type:	String
Default value:	“coco/”

Specifies the prefix that should be used to include the Coco C++ runtime header. For example, if this is changed to coco_, then the generated code would contain includes of coco_runtime.h instead of coco/runtime.h.

package setting generator.cpp.cocoRuntimeIncludeStyle¶

Type:	String
Values:	"Angles" – the generated code will include the Coco runtime via `#include <coco/runtime.h>`. "Quotes" – the generated code will include the Coco runtime via `#include "coco/runtime.h"`.
Default value:	“Quotes”

Configures whether the Coco C++ runtime headers should be included using quotes, or angles.

package setting generator.cpp.includeGuardStyle¶

Type:	String
Values:	"IncludeGuard" – the generated code will generate include guards for each file using the generated file’s name, converted to capitals. "PragmaOnce" – the generated code will use `#pragma once` at the top of each header file.
Default value:	“PragmaOnce”

Configures what sort of include guards should be used to ensure that header files are not double-included in the generated C++ code.

package setting generator.cpp.alwaysEnableLogging¶

:type:Bool :default: true

If false, then Coco’s logging will be disabled unless the generated code is compiled defining COCO_LOGGING_ENABLE. If set to false and COCO_LOGGING_ENABLE is not defined, then the generated code will not incur any overhead from logging.

package setting generator.cpp.componentStyle¶

Influences the way in which code is generated for Coco components.

Type:	String
Values:	"Regular" – "HideImplementation" – The generated code for components will use a pointer-to-implementation (pImpl) method to hide internal implementation details about each component. This can help reduce compilation times on projects that include large encapsulating components, at the cost of moving each component’s data to the heap (in the `Regular` component style the heap is not used).
Default value:	“Regular”

package setting generator.cpp.illegalBehaviour¶

Determines what Coco does when it is sent an event (i.e. a function call or signal) that is illegal.

Type:	String
Values:	"Abort" – The `abort` function will be called. "Exception" – For single-threaded components, `coco::IllegalException` will be thrown. Note that after this exception is thrown, no further method calls may be made on Coco as the state machines will potentially be in unspecified states: instead the system should be terminated and then restarted. In other words, the verification results cannot be relied upon after :cpp:class:`coco::IllegalException` is thrown. For multi-threaded components, this is ignored and the behaviour will be as per `Abort`. This is an advanced option and is recommended only for experienced users.
Default value:	“Abort”

package setting generator.cpp.fileHeader¶

Type:	String
Default value:	””

A string to prefix to all files. For example, this could be used to stamp a standard company-wide copyright header on all files. Within this string, ${var} can be used to insert the value of several pre-defined variables:

Variable	Substituted value
`COCO_VERSION`	The full version of Coco that is currently running (e.g. 1.0.0-beta.45).

For example ${COCO_VERSION} would be substituted for the full Coco version. To escape ${, use \${.

package setting generator.cpp.headerFileHeader¶

Type:	String
Default value:	””

A string to prefix to all generated header files. This is appended after generator.cpp.fileHeader and can also use the template variables, as per generator.cpp.fileHeader.

package setting generator.cpp.implementationFileHeader¶

Type:	String
Default value:	””

A string to prefix to all generated implementation files. This is appended after generator.cpp.fileHeader and can also use the template variables, as per generator.cpp.fileHeader.

package setting generator.cpp.includePrefix¶

Type:	String

Normally all includes in the generated code are generated relative to the project’s source folders, as specified by package.sources. For example, given a folder structure like:

Coco.toml
src/
  FolderA/
    ModuleA.coco
  FolderB/
    ModuleB.coco

If ModuleB uses ModuleA, then the generated code will contain an include like #include "FolderA/ModuleA.h". If generator.cpp.includePrefix is specified as prefix, then the includes will instead be generated as #include "prefix/FolderA/ModuleA.h".

package setting generator.cpp.headerFileExtension¶

Type:	String
Default value:	“.h”

The file extension that should be used for generated header files.

package setting generator.cpp.implementationFileExtension¶

Type:	String
Default value:	“.cc”

The file extension that should be used for generated implementation files.

package setting generator.cpp.runtimeHeaderFileExtension¶

Type:	String
Default value:	The valut of `generator.cpp.headerFileExtension`.

The file extension that should be used for Coco runtime header files, when generator.cpp.outputRuntimeHeader is set.

package setting generator.cpp.fileNameMangler¶

Given the name of a Coco file, specifies how the corresponding name for the generated C++ file should be derived.

The values for this are as follows. In each case, the explanation details what the derived filename for a Coco file called MyModule.coco would be.

Type:	String
Values:	"LowerCamelCase" – `myModule` "UpperCamelCase" – `MyModule` "LowerUnderscore" – `my_module` "UpperUnderscore" – `My_Module` "CapsUpperUnderscore" – `MY_MODULE` "Unaltered" – `MyModule` (i.e. the filename will exactly match the original Coco module filename)
Default value:	“Unaltered”

package setting generator.cpp.flatFileHierarchy¶: Outputs all generated files into a single top-level folder, rather than into separate folders according to each Coco file’s path. For example, if the Coco source folder contains a file called A/B.coco, then normally the generated files would be placed at A/B.h. This option will cause it to be placed at B.h instead.

package setting generator.cpp.namespaces¶

Type:	Array(String)
Default value:	[]

The list of C++ namespaces that the generated code should be placed in. For example, ["a", "b"] would place all of the generated code in the a::b namespace.

package setting generator.cpp.generateMocks¶

Type:	String
Values:	"None" – no mocks will be generated "GMock" – mocks will be generated that are compatible with gMock 1.10.0 or later "GMockNumberMacros" – mocks will be generated that are compatible with earlier versions of gMock
Default value:	“None”

See also

Testing for details on how to use the generated mocks.

Warning

Do not set this when using the Bazel integration and instead use coco_cc_gmock_library.

package setting generator.cpp.mockHeader¶

Type:	String
Default value:	gmock/gmock.h

If generator.cpp.generateMocks is not equal to None, this specifies the include path that will be used to include the header file to the supporting Mock library.

package setting generator.cpp.outputDirectory¶

Type:	String
Default value:	“generated”

The path where output files will be generated, relative to the Coco.toml file. This is only the default path and some tools, such as the command-line tooling, permit this to be overriden.

package setting generator.cpp.outputRuntimeHeader¶

Type:	Bool
Default value:	true

If set to true, the Coco runtime header will be generated alongside all of the generated files. For more advanced integrations where several unrelated Coco projects are being generated, it is recommended to set this to false and instead place the header file in a central location to avoid including several copies being used.

package setting generator.cpp.standard¶

Type:	String
Values:	"G++4.4" – Compatible with g++4.4 (requires `-std=c++0x` to be passed to `g++`). "G++4.8" – Compatible with g++4.8 (requires `-std=c++0x` to be passed to `g++`). "C++11" – Standards-compliant C++11 (requires `-std=c++11` to be passed to the compiler). "C++14" – Standards-compliant C++14 (requires `-std=c++14` to be passed to the compiler). "C++17" – Standards-compliant C++17 (requires `-std=c++17` to be passed to the compiler).
Default value:	“C++11”

This specifies the C++ that the generated code must comply with. Note that whilst the generated code will attempt to also be forwards-compatible this is not always guaranteed.

package setting generator.cpp.testOutputDirectory¶

Type:	String
Default value:	“test_generated”

The path where test output files will be generated, including generateMocks and any C++ files corresponding to generator.cpp.testSources, relative to the Coco.toml file. This is only the default path and some tools, such as the command-line tooling, permit this to be overriden.

package setting generator.cpp.cleanOutputDirectories¶

Type:	Bool
Default value:	true if `generator.cpp.outputDirectory` is not set, otherwise false

If set, then all output directories (i.e. generator.cpp.outputDirectory, and generator.cpp.testOutputDirectory) will be deleted before starting code generation.

package setting generator.cpp.regeneratePackages¶

Type:	Array(String)
Default value:	[]

If a Coco package “ProjectA” depends on another Coco package called “Common”, then by default the generated code for “ProjectA” will not include the generated code for “Common” and will instead generate include statements to the code generated as part of “Common”. Instead, this option allows this behaviour to be overriden for specific packages, and allows them to be regenerated as though they are part of the current package using the code generation settings of the current package. For example, suppose that “Common“‘s package file is:

[package]
name = "Common"
sources = ["src"]

[generator.cpp]
namespaces = ["common"]

Further, suppose “ProjectA“‘s package file is:

[package]
name = "ProjectA"
sources = ["src"]

[dependencies]
"Common" = "*"

[generator.cpp]
namespaces = ["project"]
regeneratePackages = ["Common"]

Then executing code generation for ProjectA will result in the generated code including the generated code for Common, but within the project namespace, rather than the common namespace.

This can be viewed as a method of vendoring a dependency for Coco, as it results in a private copy of a common dependency being generated.

package setting generator.cpp.outputEmptyFiles¶

Type:	Bool
Default value:	false

Coco will generate one header file and one implementation file for every Coco file processed, even if the file would be empty.