Commands and workflow
clerk build
Build files or clerk targets listed in your clerk.toml file.
This command is quite versatile, and can be used to build individual specific
files in any of the backends allowed by Catala (see help below), but the
Catala team advises to only use clerk build with targets properly defined
in clerk.toml.
The results of clerk build are available in the _targets directory by
default, if you have not specified another target directory in clerk.toml.
Each target generates a set of source code files in the target programming
languages, generated by the Catala compiler from the Catala source code
files. Please refer to the compilation and deployment
walkthrough for more examples about how to use clerk build and the resulting
artifacts.
clerk build --help
clerk build --help
NAME
clerk-build - Build command for either individual files or clerk
targets.
SYNOPSIS
clerk build [OPTION]… [TARGET(S)]…
DESCRIPTION
For individual files, and given the corresponding Catala module is
declared, this can be used to build .ml, .cmxs, .c, .py files, etc.
These files, along with their dependencies, are written into build-dir
(by default _build). If a file with a catala extension is used as
target, this compiles all its dependencies. The format of the targets
is src-dir/BACKEND/file.ext. For example, to build a C object file
from foo/bar.catala_en, one would run:
clerk build foo/c/bar.o
and the resulting file would be in _build/foo/c/bar.o. When given
clerk targets, that are defined in a clerk.toml configuration file, it
will build all their required dependencies for all their specified
backends along with their source files and copy them over to the
target-dir (by default _target).
For instance, clerk build my-target will generate a directory
target-dir/my-target/c/ that contains all necessary files to export
the target as a self contained library. When no arguments are given,
clerk build will build all the defined clerk targets found in the
clerk.toml or the project's default targets if any.
ARGUMENTS
TARGET(S)
Clerk target(s) or individual file(s) to process
OPTIONS
--autotest
When compiling to the backends, enable the Catala --autotest
option that runs an evaluation of test scopes (understood as
scopes that need no input) and instruments their compiled version
with assertions that the results match. This shouldn't be
specified directly using --catala-opts=--autotest because that
wouldn't guarantee that the necessary artifacts for interpretation
are present.
--build-dir=DIR (absent CLERK_BUILD_DIR env)
Directory where intermediate compilation artifacts should be
written. Defaults to '_build'.
-c FLAG, --catala-opts=FLAG
Option to pass to the Catala compiler. Can be repeated. If neither
this nor --test-flags is specified, the flags for the different
backends default to -O.
--color[=VAL] (default=always) (absent=auto or CATALA_COLOR env)
Allow output of colored and styled text. Use auto, to enable when
the standard output is to a terminal, never to disable.
--config=FILE
Clerk configuration file to use, instead of looking up
"clerk.toml" in parent directories.
-d, --debug
Prints debug information
-e EXE, --exe=EXE
Catala compiler executable.
-I DIR, --include=DIR (absent CATALA_INCLUDE env)
Make modules from the given directory available from everywhere.
Several dirs can be specified by repeating the flag or separating
them with ':'.
--makeflags=FLAG (absent MAKEFLAGS env)
Provides the contents of a MAKEFLAGS variable to pass on to Ninja.
Currently recognizes the -i and -j options.
-o FILE, --output=FILE
FILE is the file that will contain the build.ninja file output. If
not specified, the build.ninja file is set to
/clerk.ninja in debug mode, and a temporary file
otherwise
--target-dir=DIR (absent CLERK_TARGET_DIR env)
Directory where final compilation targets should be written.
Defaults to '_target'.
-W, --whole-program
Use Catala --whole-program option when testing or executing Catala
scopes.
COMMON OPTIONS
--help[=FMT] (default=auto)
Show this help in format FMT. The value FMT must be one of auto,
pager, groff or plain. With auto, the format is pager or plain
whenever the TERM env var is dumb or undefined.
--version
Show version information.
EXIT STATUS
clerk build exits with:
0 on success.
123 on indiscriminate errors reported on standard error.
124 on command line parsing errors.
125 on unexpected internal errors (bugs).
ENVIRONMENT
These environment variables affect the execution of clerk build:
CATALA_COLOR
See option --color.
CATALA_INCLUDE
See option --include.
CLERK_BUILD_DIR
See option --build-dir.
CLERK_TARGET_DIR
See option --target-dir.
MAKEFLAGS
make-compatible flags handling. Currently recognizes the -i and -j
options and forwards them through to Ninja.
SEE ALSO
clerk(1)
clerk test
Discover, build and run tests.
Running the tests
clerk test can be used without any arguments at the root directory of
a Catala project, with the following output:
$ clerk test
┏━━━━━━━━━━━━━━━━━━━━━━━━ ALL TESTS PASSED ━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ ┃
┃ FAILED PASSED TOTAL ┃
┃ files 0 37 37 ┃
┃ tests 0 261 261 ┃
┃ ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
The tests line of this report counts the number of failed and passed
tests. The files line displays the number of files where either all tests
pass, or there is at least one failing test.
You can print the details about the files containing passing and failing tests
with the --verbose flag. In addition, it is possible to run the
command with the flag --xml to obtain a JUnit-compatible report.
You can restrict the scope of which tests are executed by clerk test by providing another argument:
clerk test <file>will run only the tests in<file>;clerk test <folder>will run only the tests inside files in<folder>(or its sub-directories);clerk test <target>will run only the tests related to the build<target>.
clerk test executes the tests with the Catala interpreter. If your deployment
uses a specific backend, say python, it is highly recommended that you also
include a run of clerk test --backend=python in your CI. With this option,
clerk test runs Python on the generated Python code by the Catala compiler.
This way, you will be shielded from the eventuality that a bug in the backend
you use leads to a different outcome for the same Catala program. Trust does
not exclude checking throughouly!
Declaring the tests
Catala supports two distinct flavors of tests, tailored for different purposes:
- Scope tests should be the main way to write tests that validate
expected results on a given computation. This is the natural way to automate the
clerk run --scope=TestXxxcommands you use to run your tests manually. - Cram tests provide a way to run custom catala commands and check their
output on
stdoutandstderr. They are sometimes useful for more specific needs, like ensuring the correct error is triggered in a given situation.
The command clerk test can be run on any file or directory holding catala
files, will process both kinds of tests and print a report.
Scope tests
A test scope is a scope that is marked with the "test" attribute: simply
write #[test] just before its declaration keyword.
#[test]
declaration scope TestMoneyRounding:
output result content money
There are two requirements for a test scope:
- The scope must be public (declared in a
```catala-metadatasection) so that it can be run and checked in real conditions - It must not require any input: only
internal,outputandcontextvariables are allowed
The expected output of the test should be validated with assertion statements.
Without them, the only thing the test would validate is that the computation
doesn't trigger an error.
scope TestMoneyRounding:
definition result equals $100 / 3
assertion result = $33.33
As seen in the tutorial, a test scope almost always take the form of a call to the real scope you want to test, providing it with specific inputs and an expected result:
#[test]
declaration scope Test_IncomeTaxComputation_1:
output computation content IncomeTaxComputation
scope Test_IncomeTaxComputation_1:
# Define the computation as IncomeTaxComputation applied to specific inputs
definition computation equals
output of IncomeTaxComputation with {
-- individual:
Individual {
-- income: $20,000
-- number_of_children: 0
}
}
# Check that the result is as expected
assertion computation.income_tax = $4,000
Cram testing
Cram testing (or CLI testing) provides a means to validate the output of a given Catala command, which may be useful in more specific integration scenarios. It is inspired by the Cram test system, in that a single source file includes both the test command and its expected output.
For example, checking that an error happens when expected cannot be done with
test scopes, which must succeed. You may want to include tests that make use of
catala proof. Or you could want, for a simple test, to validate that the trace is
exactly as intended. For this, a ```catala-test-cli section should be
introduced in the source Catala file. The first line always starts with
$ catala , followed by the Catala command to run on the current file ; the
rest is the expected output from the command ; additionally, if the command
terminated with an error, the last line will show the error code.
```catala-test-cli
$ catala interpret --scope=Test --trace
[LOG] ☛ Definition applied:
─➤ tutorial.catala_en:214.14-214.25:
│
214 │ definition computation equals
│ ‾‾‾‾‾‾‾‾‾‾‾
Test
[LOG] → IncomeTaxComputation.direct
...
[LOG] ≔ IncomeTaxComputation.direct.output: IncomeTaxComputation { -- income_tax: $4,000.00 }
[LOG] ← IncomeTaxComputation.direct
[LOG] ≔ Test.computation: IncomeTaxComputation { -- income_tax: $4,000.00 }
┌─[RESULT]─ Test ─
│ computation = IncomeTaxComputation { -- income_tax: $4,000.00 }
└─
```
When running clerk test, the specified command is run on the file or directory (truncated
to that point). If the output exactly matches what is in the file, the tests
passes. Otherwise, it fails, and the precise differences are shown side-by-side.
Beware, cram tests this cannot be used to test backend-generated code; so clerk test --backend=... won't run cram tests.
Note that for these ```catala-test-cli, $catala test-scope Test is a shorthand for
$ catala interpret --scope=Test
If a cram test fail, but due to a legitimate difference (for example, a line
number change in the example above), it is possible to run
clerk test --reset to automatically update the expected result. This will
immediately make the cram test pass, but versionning
systems and a standard code review will highlight the changes.
clerk test --reset can also be used to initialise a new test, from a
```catala-test-cli section that only provides the command without expected
output.
clerk test --help
clerk test --help
NAME
clerk-test - Scan the given files, directories or clerk targets for
catala tests, build their requirements and run them all. If --backend
is unspecified or interpret, both scope tests and CLI tests are run ;
--reset can be used to rewrite the expected results of CLI tests to
their current result. For any other --backend, CLI tests are skipped
and scope tests are compiled to the specified backend with the catala
option --autotest, and then run, ensuring the consistency of results.
When clerk targets are provided, only their specifically defined tests
will be executed.
SYNOPSIS
clerk test [OPTION]… [TARGET(S)]…
ARGUMENTS
TARGET(S)
Clerk target(s), individual file(s) or folder(s) to process
OPTIONS
--backend=BACKEND (absent=interpret)
Run the program using the given backend. BACKEND must be one of
interpret, ocaml, c, python, java
--build-dir=DIR (absent CLERK_BUILD_DIR env)
Directory where intermediate compilation artifacts should be
written. Defaults to '_build'.
-c FLAG, --catala-opts=FLAG
Option to pass to the Catala compiler. Can be repeated. If neither
this nor --test-flags is specified, the flags for the different
backends default to -O.
--color[=VAL] (default=always) (absent=auto or CATALA_COLOR env)
Allow output of colored and styled text. Use auto, to enable when
the standard output is to a terminal, never to disable.
--config=FILE
Clerk configuration file to use, instead of looking up
"clerk.toml" in parent directories.
-d, --debug
Prints debug information
--diff[=VAL] (default=) (absent CATALA_DIFF_COMMAND env)
Use a standard diff command instead of the default side-by-side
view. If no argument is supplied, the command will be patdiff if
available or diff otherwise. A supplied argument will be used as
diff command with arguments pointing to the reference file and the
output file
-e EXE, --exe=EXE
Catala compiler executable.
--failures
Show details of files with failed tests only
-I DIR, --include=DIR (absent CATALA_INCLUDE env)
Make modules from the given directory available from everywhere.
Several dirs can be specified by repeating the flag or separating
them with ':'.
--makeflags=FLAG (absent MAKEFLAGS env)
Provides the contents of a MAKEFLAGS variable to pass on to Ninja.
Currently recognizes the -i and -j options.
-o FILE, --output=FILE
FILE is the file that will contain the build.ninja file output. If
not specified, the build.ninja file is set to
/clerk.ninja in debug mode, and a temporary file
otherwise
-r, --reset
Used with the `test` command, resets the test output to whatever
is output by the Catala compiler.
--short
Don't display detailed test failures diff
--summary
Only display a summary of the test results
--target-dir=DIR (absent CLERK_TARGET_DIR env)
Directory where final compilation targets should be written.
Defaults to '_target'.
--test-flags[=FLAGS] (default=) (absent CATALA_TEST_FLAGS env)
Flags to pass to the catala interpreter on catala test-scope
tests. Comma-separated list. A subset may also be applied to the
compilation of modules, as needed. WARNING: flag shortcuts are not
allowed here (i.e. don't use non-ambiguous prefixes such as
--closure for --closure-conversion) NOTE: if this is set, all cli
tests that are not catala test-scope are skipped to avoid
redundant testing.
-v, --verbose
Display the full list of tests that have been run
-W, --whole-program
Use Catala --whole-program option when testing or executing Catala
scopes.
--xml (absent CATALA_XML_REPORT env)
Output the test report in JUnit-compatible XML format
COMMON OPTIONS
--help[=FMT] (default=auto)
Show this help in format FMT. The value FMT must be one of auto,
pager, groff or plain. With auto, the format is pager or plain
whenever the TERM env var is dumb or undefined.
--version
Show version information.
EXIT STATUS
clerk test exits with:
0 on success.
123 on indiscriminate errors reported on standard error.
124 on command line parsing errors.
125 on unexpected internal errors (bugs).
ENVIRONMENT
These environment variables affect the execution of clerk test:
CATALA_COLOR
See option --color.
CATALA_DIFF_COMMAND
See option --diff.
CATALA_INCLUDE
See option --include.
CATALA_TEST_FLAGS
See option --test-flags.
CATALA_XML_REPORT
See option --xml.
CLERK_BUILD_DIR
See option --build-dir.
CLERK_TARGET_DIR
See option --target-dir.
MAKEFLAGS
make-compatible flags handling. Currently recognizes the -i and -j
options and forwards them through to Ninja.
SEE ALSO
clerk(1)
clerk ci
Scan the project and run all possible actions. This includes
the interpretation of all catala tests and CLI tests (equivalent to
running the clerk test command), and also, the build of all clerk
targets (equivalent to running the clerk build command) alongside the
execution of their tests against all their defined backend. This
command is useful for the execution of continuous integrations (CIs)
where all build and test actions are often meant to be executed.
clerk ci --help
clerk ci --help
NAME
clerk-ci - Scan the project and run all possible actions. This
includes the interpretation of all catala tests and CLI tests
(equivalent to running the clerk test command), and also, the build of
all clerk targets (equivalent to running the clerk build command)
alongside the execution of their tests against all their defined
backend. This command is useful for the execution of continuous
integrations (CIs) where all build and test actions are often meant to
be executed. Run with --debug for the full log of events.
SYNOPSIS
clerk ci [OPTION]…
OPTIONS
--build-dir=DIR (absent CLERK_BUILD_DIR env)
Directory where intermediate compilation artifacts should be
written. Defaults to '_build'.
-c FLAG, --catala-opts=FLAG
Option to pass to the Catala compiler. Can be repeated. If neither
this nor --test-flags is specified, the flags for the different
backends default to -O.
--color[=VAL] (default=always) (absent=auto or CATALA_COLOR env)
Allow output of colored and styled text. Use auto, to enable when
the standard output is to a terminal, never to disable.
--config=FILE
Clerk configuration file to use, instead of looking up
"clerk.toml" in parent directories.
-d, --debug
Prints debug information
--diff[=VAL] (default=) (absent CATALA_DIFF_COMMAND env)
Use a standard diff command instead of the default side-by-side
view. If no argument is supplied, the command will be patdiff if
available or diff otherwise. A supplied argument will be used as
diff command with arguments pointing to the reference file and the
output file
-e EXE, --exe=EXE
Catala compiler executable.
--failures
Show details of files with failed tests only
-I DIR, --include=DIR (absent CATALA_INCLUDE env)
Make modules from the given directory available from everywhere.
Several dirs can be specified by repeating the flag or separating
them with ':'.
-o FILE, --output=FILE
FILE is the file that will contain the build.ninja file output. If
not specified, the build.ninja file is set to
/clerk.ninja in debug mode, and a temporary file
otherwise
--short
Don't display detailed test failures diff
--summary
Only display a summary of the test results
--target-dir=DIR (absent CLERK_TARGET_DIR env)
Directory where final compilation targets should be written.
Defaults to '_target'.
--test-flags[=FLAGS] (default=) (absent CATALA_TEST_FLAGS env)
Flags to pass to the catala interpreter on catala test-scope
tests. Comma-separated list. A subset may also be applied to the
compilation of modules, as needed. WARNING: flag shortcuts are not
allowed here (i.e. don't use non-ambiguous prefixes such as
--closure for --closure-conversion) NOTE: if this is set, all cli
tests that are not catala test-scope are skipped to avoid
redundant testing.
-v, --verbose
Display the full list of tests that have been run
-W, --whole-program
Use Catala --whole-program option when testing or executing Catala
scopes.
--xml (absent CATALA_XML_REPORT env)
Output the test report in JUnit-compatible XML format
COMMON OPTIONS
--help[=FMT] (default=auto)
Show this help in format FMT. The value FMT must be one of auto,
pager, groff or plain. With auto, the format is pager or plain
whenever the TERM env var is dumb or undefined.
--version
Show version information.
EXIT STATUS
clerk ci exits with:
0 on success.
123 on indiscriminate errors reported on standard error.
124 on command line parsing errors.
125 on unexpected internal errors (bugs).
ENVIRONMENT
These environment variables affect the execution of clerk ci:
CATALA_COLOR
See option --color.
CATALA_DIFF_COMMAND
See option --diff.
CATALA_INCLUDE
See option --include.
CATALA_TEST_FLAGS
See option --test-flags.
CATALA_XML_REPORT
See option --xml.
CLERK_BUILD_DIR
See option --build-dir.
CLERK_TARGET_DIR
See option --target-dir.
SEE ALSO
clerk(1)
clerk run
Runs the Catala interpreter on the given files, after
building their dependencies. The scope to be executed can be specified
using the -s option.
As of writing, clerk run is restricted to scopes that do
not require inputs, so it is used to run test scopes.
Example
$ clerk run tests/tests_allocations_familiales.catala_fr -s Test1
clerk run --help
clerk run --help
NAME
clerk-run - Runs the Catala interpreter on the given files, after
building their dependencies. The scope to be executed can be specified
using the -s option.
SYNOPSIS
clerk run [OPTION]… [FILE]…
ARGUMENTS
FILE
File(s) or folder(s) to process
OPTIONS
--backend=BACKEND (absent=interpret)
Run the program using the given backend. BACKEND must be one of
interpret, ocaml, c, python, java
--build-dir=DIR (absent CLERK_BUILD_DIR env)
Directory where intermediate compilation artifacts should be
written. Defaults to '_build'.
-c FLAG, --catala-opts=FLAG
Option to pass to the Catala compiler. Can be repeated. If neither
this nor --test-flags is specified, the flags for the different
backends default to -O.
--color[=VAL] (default=always) (absent=auto or CATALA_COLOR env)
Allow output of colored and styled text. Use auto, to enable when
the standard output is to a terminal, never to disable.
--command=CMD (absent=interpret)
The catala command to run on the input files. Normally interpret,
this flag can be used to run typecheck or a custom plugin instead.
This is ignored if --backend isn't interpret.
--config=FILE
Clerk configuration file to use, instead of looking up
"clerk.toml" in parent directories.
-d, --debug
Prints debug information
-e EXE, --exe=EXE
Catala compiler executable.
-I DIR, --include=DIR (absent CATALA_INCLUDE env)
Make modules from the given directory available from everywhere.
Several dirs can be specified by repeating the flag or separating
them with ':'.
--makeflags=FLAG (absent MAKEFLAGS env)
Provides the contents of a MAKEFLAGS variable to pass on to Ninja.
Currently recognizes the -i and -j options.
-o FILE, --output=FILE
FILE is the file that will contain the build.ninja file output. If
not specified, the build.ninja file is set to
/clerk.ninja in debug mode, and a temporary file
otherwise
--prepare-only
Compile dependencies of the target(s) but do not run it.
-s SCOPE, --scope=SCOPE
Used with the `run` command, selects which scope of a given Catala
file to run.
--target-dir=DIR (absent CLERK_TARGET_DIR env)
Directory where final compilation targets should be written.
Defaults to '_target'.
-W, --whole-program
Use Catala --whole-program option when testing or executing Catala
scopes.
COMMON OPTIONS
--help[=FMT] (default=auto)
Show this help in format FMT. The value FMT must be one of auto,
pager, groff or plain. With auto, the format is pager or plain
whenever the TERM env var is dumb or undefined.
--version
Show version information.
EXIT STATUS
clerk run exits with:
0 on success.
123 on indiscriminate errors reported on standard error.
124 on command line parsing errors.
125 on unexpected internal errors (bugs).
ENVIRONMENT
These environment variables affect the execution of clerk run:
CATALA_COLOR
See option --color.
CATALA_INCLUDE
See option --include.
CLERK_BUILD_DIR
See option --build-dir.
CLERK_TARGET_DIR
See option --target-dir.
MAKEFLAGS
make-compatible flags handling. Currently recognizes the -i and -j
options and forwards them through to Ninja.
SEE ALSO
clerk(1)
clerk clean
Remove files and directories previously generated by clerk, notably
the _build and _targets directory. Useful to clean up the machine after
a CI job or to make sure you're not including stale, old files in your build
pipeline.
clerk clean --help
clerk clean --help
NAME
clerk-clean - Removes files and directories previously generated by
clerk if any.
SYNOPSIS
clerk clean [OPTION]…
OPTIONS
--build-dir=DIR (absent CLERK_BUILD_DIR env)
Directory where intermediate compilation artifacts should be
written. Defaults to '_build'.
-c FLAG, --catala-opts=FLAG
Option to pass to the Catala compiler. Can be repeated. If neither
this nor --test-flags is specified, the flags for the different
backends default to -O.
--color[=VAL] (default=always) (absent=auto or CATALA_COLOR env)
Allow output of colored and styled text. Use auto, to enable when
the standard output is to a terminal, never to disable.
--config=FILE
Clerk configuration file to use, instead of looking up
"clerk.toml" in parent directories.
-d, --debug
Prints debug information
-e EXE, --exe=EXE
Catala compiler executable.
-I DIR, --include=DIR (absent CATALA_INCLUDE env)
Make modules from the given directory available from everywhere.
Several dirs can be specified by repeating the flag or separating
them with ':'.
-o FILE, --output=FILE
FILE is the file that will contain the build.ninja file output. If
not specified, the build.ninja file is set to
/clerk.ninja in debug mode, and a temporary file
otherwise
--target-dir=DIR (absent CLERK_TARGET_DIR env)
Directory where final compilation targets should be written.
Defaults to '_target'.
-W, --whole-program
Use Catala --whole-program option when testing or executing Catala
scopes.
COMMON OPTIONS
--help[=FMT] (default=auto)
Show this help in format FMT. The value FMT must be one of auto,
pager, groff or plain. With auto, the format is pager or plain
whenever the TERM env var is dumb or undefined.
--version
Show version information.
EXIT STATUS
clerk clean exits with:
0 on success.
123 on indiscriminate errors reported on standard error.
124 on command line parsing errors.
125 on unexpected internal errors (bugs).
ENVIRONMENT
These environment variables affect the execution of clerk clean:
CATALA_COLOR
See option --color.
CATALA_INCLUDE
See option --include.
CLERK_BUILD_DIR
See option --build-dir.
CLERK_TARGET_DIR
See option --target-dir.
SEE ALSO
clerk(1)