Creating and Running Examples

Mason supports examples as a way to demonstrate typical usage of a package. The following example adds an example to MyPackage and runs it. The example below prints a message a number of times based on the config const count:

config const count: int = 10;

for i in 1..count {
  writeln("This is an example!!");
}

To build the example without running it, use the command mason build --example. This command will build ALL examples found either in the example/ directory or listed in the Mason.toml

Note

If examples or tests are listed in the Mason.toml, Mason will not search for any examples or tests not listed.

To view what examples are available, enter mason run --example without any other arguments. This will produce the names of all examples that are currently available to Mason:

--- available examples ---
--- myPackageExample.chpl
--------------------------

To run the example, use the command mason run --example myPackageExample.chpl.

After the program is run via the command above, the package structure will look as follows:

MyPackage/
 │
 ├── Mason.lock
 ├── Mason.toml
 ├── example/
 │   └── myPackageExample.chpl
 ├── src/
 │   └── myPackage.chpl
 ├── target/
 │   ├── debug/
 │   │   └── myPackage
 │   ├── example/
 │   │   └── myPackageExample
 │   ├── release/
 │   │   └── myPackage
 │   └── test/
 └── test/
      └── myPackageTest.chpl

Examples can either be specified in the Mason.toml, or found automatically by Mason. However, to include compile time or runtime arguments for examples, users must explicitly declare them in their Mason.toml as follows:

[brick]
chplVersion = "1.18.0"
license = "None"
name = "myPackage"
version = "0.1.0"

[dependencies]

[examples]
examples = ["myPackageExample.chpl"]

[examples.myPackageExample]
compopts = "--savec tmp"
execopts = "--count=20"