Compiler: Using Command-line Interface

Help Command

coco help [command]

Prints global help or command-specific help.

Version Command

coco version

Prints the current Coco version.

Optional Flags

flag	description	supported values
-s, --suppress-banner	suppress the cocolang figlet banner	n/a

Nut Command

coco nut init <module_name>
coco nut run <script-name>

The nut command manages coco.nut, the manifest file for a module of .coco source file(s). It supports two subcommands:

• init - Creates a coco.nut manifest in the current folder.
• run - Executes a named script defined in coco.nut.

Nut Init Subcommand

coco nut init <module_name>

creates a file with the following contents:

[coco]
version = "0.9.2"

[module]
name = "Module"
version = "0.0.1"
license = []
repository = ""
authors = []

[target]
os = "MOI"
arch = "PISA"

[target.moi]
format = "YAML"
output = "module"

[target.pisa]
format = "ASM"
version = "0.8.0"

[lab.render]
big_int_as_hex = true
bytes_as_hex = false

[lab.config.default]
env = "main"

[lab.scripts]
test-toggle = ["engines", "users", "logics"]

[scripts]
test-script = "coco compile .; pwd; uname -a"

While all fields in the coco.nut file are mandatory, the only currently supported target is MOI Manifests (os = “MOI”) for the PISA runtime (arch = “PISA”), so only [target.moi] and [target.pisa] parameter values affect compilation. Allowed values for these parameters are:

[target.moi]
// output format, the output file extension will be
// .yaml, .json or .polo, respectively
format = "YAML", "JSON" or "POLO"
// output file name (with extension) - by default, it's lowercase module name
output = "module.yaml"

[target.pisa]
// format of executable code in PISA manifest
// "ASM" and "HEX" supported from Coco compiler release v0.3.1
format = "BIN", "ASM" or "HEX"
// PISA runtime the manifest is generated for
version = "0.3.2", "0.4.0", "0.5.0", "0.5.1", "0.6.0", "0.6.1", "0.7.0", "0.7.1" or "0.8.0"

The PISA version determines which language constructs are available. Native assets require 0.5.0 or later. The payer clause, Environment.StorageResult() and the Actor(id) query methods require 0.8.0, while Environment.VolumeCapacity() and Environment.VolumeAvailable() are only available up to 0.7.1.

Optional Flags

flag	description	supported values
-f, --force	allow overwriting coco.nut file in the current folder, if it exists	n/a

Nut Run Subcommand

coco nut run <script-name>

run command runs the script script-name that’s defined in the coco.nut file. The definition contains shell/terminal commands that can run on Windows/Linux/Mac. The default contains an example of compile script that rust coco compile command.

[scripts]
compile = "coco compile ."

Script name can be any string and inside it can be bash script joined with cmd1 && cmd2.

Compile Command

coco compile [path_to_coco.nut]

The compile command compiles a .coco source(s) of a module into a target artifact as defined in the coco.nut file. When called without specified path to a coco.nut file, the file in the current folder is used and the target artifact is created in the current folder. When path is specified, the artifact is created in the same folder, as coco.nut file.

Source .coco files can have any file names, but only the ones with coco <module_name> that matches module.name in the coco.nut file are used for compilation. Multiple source files for a single module are supported.

Optional Flags

flag	description	supported values
--debug	print the opcodes of compiled functions	n/a
--ast	print the AST as JSON	n/a
-O, --optimize	optimization level [default: 2]	any valid positive number
-f, --fileform <MANIFEST_FORMAT_OVERRIDE>	override manifest format	yaml, json, polo
-c, --codeform <BINARY_FORMAT_OVERRIDE>	override binary format	bin, asm, hex
--pkg <PKG>	location of the package library	any valid folder path

The -f and -c flags override [target.moi] format and [target.pisa] format for a single compilation. To change the format of a manifest you have already compiled, use coco manifest convert.

Test Command

coco test --debug_pisa <module_name>

The test command compiles and runs the module without the Cocolab utility. It reads the target settings from the coco.nut file in the current folder; without one it falls back to built-in defaults that target PISA 0.3.2, so run it next to your coco.nut. When <module_name> is omitted, every module found in the folder's .coco files is tested. The test invokes // < comments and expects the results from // > comment. These comments can be placed anywhere and will be executed in order as they are written, they just have to come in pairs // < followed by // >. For invoke commands, module name is always TEST, regardless of the actual module name.

--debug_pisa is required

Without --debug_pisa, the command only reports "Test functionality is not yet implemented." and exits with status 1. With the flag, failed test cases are reported in the log (1 / 2 tests passed, 1 failed), but the command still exits with status 0. A CI step has to check that summary line rather than rely on the exit status.

// < invoke TEST.TstMax(a: 5, b:3)
// > max: 5
// < invoke TEST.TstMax(a: 5, b:7)
// > max: 7
// < invoke TEST.TstMax(a: 3, b:3)
// > max: 3
// TstMax is defined just to test the local "max" function as one can't invoke local functions
endpoint TstMax(a, b U64) -> (max U64):
    max = (max) <- max(a:a, b:b)

function max(a, b U64) -> (max U64):
    if a >= b:
        return (max: a)
    max = b

Optional Flags

flag	description	supported values
--fuel	fuel set [default: 100000]	any valid positive number
--volume	storage volume set [default: 10000]	any valid positive number
--debug	print the opcodes of compiled functions	n/a
--sender	sender address (you can set the sender address yourself else a new one is generated each time the command is run)	any valid address
--debug_pisa	enable pisa debug mode; required to run the tests	n/a
-O, --optimize	optimization level [default: 2]	any valid positive number
--pkg <PKG>	location of the package library	any valid folder path

Manifest Command

coco manifest <manifest_file>
coco manifest convert <manifest_file> [-f <format>] [-c <codeform>] [-o <output_file>]
coco manifest <manifest_file> artifact

The manifest command converts compiled manifests between file formats (YAML, JSON, POLO) and executable code formats (BIN, HEX, ASM), and encodes them for deployment. See Manifest for details.