Note

You are not reading the most recent version of this documentation.

Packages¶

A package is a means of organising Coco files into projects and is indicated by a configuration file called “Coco.toml”, which specifies the directory where the Coco source files belonging to the package are located, together with preference settings that influence the behaviour of the subcommand being executed.

A large project can be divided into a number of smaller sub-projects, each with their own package file. These may specify dependencies on other packages. Further, packages can be configured to export their settings, which provides a way for all packages in a project to share the same Coco settings.

TOML format¶

Coco.toml files are written in TOML, which is a format for specifying configuration files. It is intended to be easy to write and understand, and its syntax primarily consists of key/value pairs, tables, and comments. TOML files are organised by grouping together common configuration settings in tables, where a table is a collection of key/value pairs.

Key/value pairs are written as:

key = value

where value is the configuration value assigned to the key.

Coco uses the following types: Int, Bool, String, and an Array of String elements. Coco also supports multi-line basic strings, where strings run over multiple lines.

A table is a collection of key/value pairs, written as:

[table]

Comments are written as:

# This is a comment.

For example:

[package]
name = "bridge_system"  # Package name.
sources = "src"         # Location of Coco source files belonging
                        # to this package.

[generator.cpp]
standard = "C++17"      # C++ standard generated by the code generator.

[verification]
allowRemote = false     # Remote verification cannot be used for files
                        # belonging to this package

Configuration settings¶

This section summarises the tables and key/value pairs supported by Coco. Further configuration settings relating to code generation can be found in Code Generation Options.

Package¶

package setting package¶

Type:	Table

This table contains the configuration settings for the package itself, such as the package name, and the location of the Coco source files that belong to it.

package setting package.name¶

Type:	String

Identifier representing the package name.

For example:

[package]
name = "bridge_system"

package setting package.sources¶

Type:	Array(String)

Comma-separated list of directories relative to the Coco.toml file that contain the Coco source files belonging to the package.

For example:

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

This means that the package called bridge_system applies to the Coco source files in the directory src.

package setting package.testSources¶

Type:	Array(String)

Comma-separated list of directories relative to the Coco.toml file that contain .coco files that should be considered as test sources.

Test sources are treated like regular sources (i.e. like package.sources), but have some special features:

When generating code, they are output into a separate directory (e.g. generator.cpp.testOutputDirectory) alongside other Coco-generated source files that are relevant to testing, such as mocks;
They can depend on files in package.sources, but not the other way around.

This permits .coco files related to testing to be kept as part of the main package, but ensures they are kept separate when generating code.

package setting package.exportConfig¶

Type:	Boolean

Exports configuration settings from a base package to its child packages.

If a key is specified in both the base and child package, then the key/value pair in child package takes precedence. Not all of the configuration settings are exported. For example, the package name and its dependencies are not exported, whereas the the option settings for the code generation are.

Dependencies¶

package setting dependencies¶

Type:	Table

A Coco package can have dependencies on other Coco packages, which are specified in this table. For example, a project may be divided into smaller sub-projects, each with its own package file. The top-level project may also have a package file specifying preferences that apply by default to all of its sub-projects. In this case, the package files of each of the sub-projects will specify a dependency on the top-level project package.

Short form dependencies are specified as key-value pairs of the form:

[dependencies]
base-package = "*"

where the string refers to a version constraint.

Dependencies can also be specified in a longer form, for example, the short form dependency above is equivalent to:

[dependency.base-package]
version = "*"

Language¶

package setting language¶

Type:	Table

This table consists of all of the configuration settings related to the Coco language.

package setting language.disabledWarnings¶

Type:	Array(String)
Value:	The string name of any enum case from `Warning` (e.g. `"IncompleteMatch"`).

package setting language.profiles¶

Type:	Array(String)
Values:	"C" – Restricts Coco to features that are supported by the C generator. "C++" – Restricts Coco to features that are supported by the C++ generator.
Default value:	“[]”

Coco is a language from which multiple target languages can be generated, and not all Coco features are supported by all code generators or target languages. To avoid unsupported features being diagnosed late during code generation, Coco uses profiles to define additional rules that Coco source files must adhere to. This means that diagnostics can be provided to users as early as possible during type checking of their Coco source files.

For example, the following setting:

[language]
profiles = ["C++"]

means that the profile for C++ applies to the Coco source files belonging to the package. As an example of an additional rule this introduces, when this profile is applied to the following valid Coco port declaration:

port Conflict {
  struct Conflict {}
}

a static error will be raised during type checking stating that types cannot have the same name as their parent port when the C++ profile is enabled. C++ does not support a class and nested class having the same identifier, and would therefore lead to a compilation error of the generated C++. Rather than discovering this problem during compilation, the Coco profiles help users catch these errors earlier in Coco, which is much more efficient.

package setting language.standard¶

Type:	String
Values:	"1" –

Sets the language standard to be used by the Coco source files belonging to this package.

For example, the following setting:

[language]
standard = "1"

will set the Coco language to version 1.

Format¶

package setting format¶

Type:	Table

This table consists of all of the configuration settings related to the formatting of the Coco source files.

package setting format.allowShortBlocksOnASingleLine¶

Type:	Boolean
Default value:	false

package setting format.allowShortCaseLabelsOnASingleLine¶

Type:	Boolean
Default value:	false

package setting format.allowShortFunctionsOnASingleLine¶

Type:	String
Values:	"all" – All functions that are short can be placed onto a single line. "empty" – Only empty functions can be placed onto a single line. "none" – No functions can be placed onto a single line.
Default value:	“all”

package setting format.allowShortIfStatementsOnASingleLine¶

Type:	Boolean
Default value:	true

If true, then all short if statements can be placed onto a single line.

package setting format.allowShortLoopsOnASingleLine¶

Type:	Boolean
Default value:	false

If true, then all short loops can be placed onto a single line.

package setting format.columnLimit¶

Type:	Int
Default value:	120

Sets the column width limit to the specified length.

package setting format.sortImports¶

Type:	Int
Default value:	true

package setting format.indentWidth¶

Type:	Int
Default value:	2

Sets the indent width to the specified length.

package setting format.tabWidth¶

Type:	Int
Default value:	8

Sets the tab width to the specified length.

package setting format.useTabs¶

Type:	Int
Default value:	never

Generator¶

package setting generator¶

Type:	Table

This table consists of all of the configuration settings related to the generation of code from Coco.

package setting generator.defaultLanguage¶

Sets the language that will be generated by default when pressing Generate Code in one of the Coco GUI tools (e.g. Eclipse).

Type:	String
Values:	"C" – "C++" –
Default value:	“C++”

package setting generator.cpp¶

Sets the settings used when generating C++. See Code Generation Options for further information.

Type:	Table:

Verification¶

package setting verification¶

Type:	Table

This table consists of all of the configuration settings related to the verification.

package setting verification.allowRemote¶

Type:	Boolean
Default value:	true

Sets the access rights to the remote verification service.

For example, the following setting:

[verification]
allowRemote = false

will prohibit the Coco source files that belong to this package from using the remote verification service.