Version: v1

Compact command-line tool usage page

This is the usage page of the Compact command-line tool. This tool allows the user to run any of Compact toolchain's tools: the compiler, the formatter, and the fix up tool.

NAME

Compact command-line tool

OVERVIEW

The Compact command-line tool provides a set of utilities for Compact smart contract development.

SYNOPSIS

compact options ...

compact command options ..

DESCRIPTION

The options flag are optional and is described under OPTIONS later in this document.

The Compact command-line tool takes a command. This command is the program that the tool runs. Supported commands are listed below and the more complicated ones are explained in detail under the command name:

check

Checks for updates with the remote server [aliases: ch] and exits.

update

Updates to the latest or a specific version of the Compact toolchain [aliases: u, up] and exits .

format

Formats Compact files [aliases: f, fmt] and exits.

fixup

Applies fixup transformations to Compact files [aliases: fx, fix] and exits.

list

Lists available Compact versions [aliases: l] and exits.

clean

Removes all Compact versions [aliases: cl] and exits.

self

Commands for managing the Compact tool itself [aliases: s].

compile

Calls the compiler [aliases: c] and exits.

help

Prints the help of the command-line tool and exits.

OPTIONS

The following options are available for all commands, and if present, they affect the tool's behavior as follows:

--directory directorypath

Sets the Compact artifact directory and exits.

By default this will be $HOME/.compact. The directory will be created if it does not exist. This can also be configured via an environment variable.

[env: COMPACT_DIRECTORY=] [default: /Users/username/.compact]

--help

Prints help for this tool or of command provided by the tool and exits.

--version

Prints the version of this tool or of command and exits.

CHECK

Synopsis: compact check options

This command checks for updates of the Compact toolchain on the remote server.

Assuming there are not versions of the Compact toolchain installed, running:

compact check

results in:

compact: no version installed.
compact: Latest version available: 0.28.0.

where 0.28.0 is the latest available Compact toolchain version on the remote server.

However, assuming that the previous version of the Compact toolchain is installed, running:

compact check

results in:

compact: aarch64-darwin -- Update Available -- 0.26.0
compact: Latest version available: 0.28.0.

where 0.26.0 is the installed version and 0.28.0 is the latest available version of the Compact toolchain. The command update can be used to update to this version. aarch64-darwin displays the chosen binary of the Compact toolchain for your machine's architecture.

UPDATE

Synopsis: compact update options compactversion

This command updates to the latest version of the Compact toolchain if no version is specified, otherwise, it updates to the specified version of the Compact toolchain compactversion.

compactversion can be specified as a full version such as 0.30.1, as a major.minor prefix such as 0.30 which resolves to the latest patch release for that minor version, or as a major prefix only such as 0 which resolves to the latest minor and patch release for that major version.

Upon switching from one version to another, by default this command switches the default compiler version to the installed one. This can be overwritten by --no-set-default option.

If the compiler has already been downloaded, then it will not be downloaded again.

The following options are specific to this command:

--no-set-default

Doesn't set the newly installed compiler as the default one.

We now present some simple examples of using this command. Assuming the latest Compact toolchain on the remote server is 0.28.0 and the last time you updated your Compact toolchain was to 0.26.0, running:

compact update

results in:

compact: aarch64-darwin -- 0.28.0 -- installed
compact: aarch64-darwin -- 0.28.0 -- default.

Now after updating to the latest version, running:

compact update

results in:

compact: aarch64-darwin -- 0.28.0 -- already installed
compact: aarch64-darwin -- 0.28.0 -- default.

However, running:

compact update --no-set-default

results in:

compact: aarch64-darwin -- 0.28.0 -- already installed

To switch to an older version, run:

compact update 0.26.0

which results in:

compact: aarch64-darwin -- 0.26.0 -- already installed
compact: aarch64-darwin -- 0.26.0 -- default.

To keep the default unchanged, run:

compact update --no-set-default 0.26.0

which results in:

compact: aarch64-darwin -- 0.26.0 -- already installed

COMPILE

Synopsis: compact compile +version options sourcepath targetpath

This command compiles the Compact source program in sourcepath using the specified Compact toolchain version version if it exists. If no version is specified, then the default version of the Compact toolchain installed is picked. The options are optional. If version does not exist, then both the compiler and the command-line tool options can be used. Otherwise, only the compiler options can be used. The targetpath specifies the target directory for the outputs of the compiler. Visit the compiler usage page for a more detailed explanation of how to use it.

If +version is specified such as +0.30.0, compact compile uses that exact version of the toolchain to compile the program. If no version is specified, the default toolchain version (as set by compact update) is used. Partial version specifiers are not supported here; the version must be fully qualified, that is, +0.30.0 is supported but +0.30 is not. If the requested toolchain version is not installed, compact compile will fail with an error. Run compact update _version_ first to install it.

Assuming that Compact toolchain 0.26.0 and 0.30.0 are installed and 0.26.0 is the default, running:

compact compile +0.27.0 --language-version

results in:

Error: Failed to run compactc

Caused by:
    0: Couldn't find compiler for aarch64-darwin (0.27.0)
    1: Directory does not exist

whereas running:

compact compile --language-version

results in 0.18.0 (which is the corresponding language version for the toolchain 0.26.0) and running:

compact compile +0.30.0 --language-version

results in 0.22.0 (which is the corresponding language version for the toolchain 0.30.0).

Running:

compact compile +version --help

returns the help text of the compiler for a specific version +version, whereas running:

compact compile --help

returns the help text specified in the Compact command-line tool for the compiler.

FORMAT

Synopsis: compact format options files

This command formats one or more Compact source files using the installed format-compact tool. files can be individual .compact files or directories; when a directory is given, all .compact files within it are discovered recursively, respecting .gitignore rules. If no files are specified, then the current directory (.) is used.

The following options are specific to this command:

--check

Checks whether files are already formatted without modifying them. Exits with a non-zero status and prints a diff for any file that would be changed. This is useful in CI pipelines to enforce formatting without altering source files.

--verbose

Prints each file processed along with its outcome (formatted, unchanged, or an error). Without this flag only failures are reported.

Additionally, the formatter tool itself provides extra flags. Visit the format usage page for a more detailed explanation of this tool.

We now present some simple examples of using this command. Assuming src/ contains a well-formed Compact source files, format all of them in place:

compact format src/

Check formatting without modifying files (suitable for CI):

compact format --check src/

Format a single file verbosely:

compact format --verbose src/counter.compact

Assuming src/test.compact contains an ill-formed Compact program, running:

compact format src/test.compact

exits with an error message describing the problem that prevents the Compact program in src/test.compact from compiling.

FIXUP

Synopsis: compact fixup options files

This command applies fixup transformations to one or more Compact source files using the installed fixup-compact tool. Unlike format, which only reformats whitespace and style, fixup also updates source programs to reflect recent language changes. files can be individual .compact files or directories; when a directory is given, all .compact files within it are discovered recursively, respecting .gitignore rules. If no files are specified, the current directory (.) is used.

The following options are specific to this command:

--check

Checks whether files need fixup without modifying them. Exits with a non-zero status and prints a diff for any file that would be changed. Useful in CI pipelines to verify that source files are up to date.

Additionally, the fixup tool itself provides extra flags. Visit the fixup usage page for a more detailed explanation of this tool.

We now present some simple examples of using this command. Assuming src/ contains a well-formed Compact source files, apply fixup to all files in src/ in place:

compact fixup src/

Check whether any files need fixup without modifying them (suitable for CI):

compact fixup --check src/

Apply fixup including Uint range endpoint adjustment:

compact fixup --update-Uint-ranges src/

Assuming src/test.compact contains an ill-formed Compact program, running

compact fixup src/test.compact

exits with an error message describing the problem that prevents the Compact program in src/test.compact from compiling.

LIST

Synopsis: compact list options

This command lists available Compact toolchain versions on the remote server if no option is set. When the --installed option is set, it lists the locally installed versions of the Compact toolchain.

The following options are specific to this command:

--installed

Shows installed versions and exits.

We now present some simple examples of using this command. Assuming that the latest available Compact toolchain version is 0.28.0 on the remote server, running:

compact list

results in:

compact: available versions

→ 0.28.0 - x86_macos, aarch64_macos, x86_linux
26.0 - x86_macos, aarch64_macos, x86_linux
25.0 - x86_macos, aarch64_macos, x86_linux
24.0 - x86_macos, aarch64_macos, x86_linux
23.0 - aarch64_macos, x86_linux
22.0 - x86_macos, x86_linux

Assuming that locally versions 0.26.0 and 0.28.0 have been installed, running:

compact list --installed

results in:

compact: installed versions

→ 0.28.0
  0.26.0

The right arrow indicates the version to be used by the Compact command-line tool when no version is specified.

CLEAN

Synopsis: compact clean options

This command removes all local versions of the Compact toolchain if no option is set. When --cache is set, it also removes the cache directory. When --keep-current is set, the version currently set as the default is kept.

In addition to removing version directories, compact clean removes the compactc, format-compact, and fixup-compact symlinks from the bin directory. After running compact clean without --keep-current, the toolchain is unusable until `compact update`` is run again to reinstall a version. With --keep-current, the symlinks are preserved alongside the kept version.

The following options are specific to this command:

--cache

removes the cache directory as well.

--keep-current

keeps the version currently in use.

We now present some simple examples of using this command. Assuming that versions 0.26.0 and 0.28.00 of the Compact toolchain are locally installed, running:

compact clean --cache

results in:

compact: removed /Users/username/Library/Caches/compactc/github_cache.json
compact: removing versions
compact: removed 0.28.0
compact: removed 0.26.0

Now running:

compact list --installed

results in:

compact: installed versions

no versions available on this machine
try: compact update

Now running:

compact update
compact update 0.26.0
compact clean --keep-current

results in:

compact: removing versions
compact: removed 0.28.0
compact: kept 0.26.0

SELF

Synopsis: compact self options subcommand

Manages the Compact command-line tool itself.

Running:

compact self check

checks if a newer version of the Compact command-line tool is available or not. Assuming the latest version of the Compact command-line tool is 0.4.0 and it is already installed this results in:

compact: compact -- 0.4.0 -- Up to date

However, if the latest version of the Compact command-line tool is not installed the command above results in:

compact: compact -- Update available -- 0.5.0

Running:

compact self update

updates the Compact command-line tool to the latest version.

If the tool is already at the latest version, running compact self update results in (assuming the latest version is 0.5.0):

compact: compact -- 0.5.0 -- Up to date