Building and Running

When invoked, mason build [ options ] will do the following:

• Run update to make sure any manual manifest edits are reflected in the dependency code.

• Build MyPackage.chpl in the src/ directory.

• All packages are compiled into binaries and placed into target/.

• To forward options to the Chapel compiler(chpl), separate them with a double dash.

  • e.g., mason build --force -- --savec tmpdir

mason run [ options ] will, in turn:

• Run the executable built above out of target/, if it exists.

• To forward options to the executable, separate them with a double dash.

  • e.g., mason run -- --myConfig=2

For example, after mason run --build [ options ], the package directory appears as follows:

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

As you can see, new files have been added to the package, the first of which is the Mason.lock. You can think of this file as a snapshot of a single run of the program. This file “locks” in the settings in which the program was built upon invocation of mason build. This file can be generated manually with the mason update command. mason update will read the Mason.toml, resolve dependencies, and generate the Mason.lock based on it’s contents.

The target/ directory is where Mason stores all the binaries related to your package. These could be binaries for the main source code as well as examples and tests. There are two types of targets for building. The default location of a package binary is target/debug/, as shown in the example above. However, if a final version of an application or library is being produced, the --release flag can be thrown as follows:

mason build --release --force

# OR

mason run --build --release --force

The --release option adds the --fast argument to the compilation step.

The argument --force is included as Mason will only build the package if the package has been modified. Throwing the --release flag will result in the following package structure:

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

As you can see there are now two binaries of MyPackage, one under debug/ and one under release. To remove the target/ directory along with all of the binaries for your package, use the mason clean command.