Mason¶

Overview¶

This guide on Mason Packages contains everything that you need to know to hit the ground developing in Chapel using mason, whether that be to create a library to contribute to the community, use an existing package, or just to help with the process of building your Chapel programs.

When to Leverage Mason for Chapel Builds¶

Mason simplifies the build process for Chapel applications. Here’s a breakdown of when Mason shines and when alternative approaches might be better suited.

Ideal Use Cases for Mason:

Pure Chapel Projects: Mason excels at managing the build process for applications written entirely in Chapel. If your program relies solely on Chapel dependencies and compiles directly from Chapel modules, Mason is the perfect tool.
External Dependencies with Spack or pkg-config: Mason integrates seamlessly with external dependencies managed by Spack or pkg-config. If your project uses such dependencies, Mason can handle them efficiently.

Considering Alternatives:

Complex Compilation Needs Beyond chpl: For Chapel programs requiring compilation steps beyond what the Chapel compiler offers, Mason might not be the most suitable choice. Consider alternatives like Make for greater flexibility in crafting intricate build commands. As an example, the Arkouda project, a prominent open-source Chapel application, uses Make to run preparatory Python scripts before the final binary compilation.

Combining Mason with Make:

Mason and Make can co-exist effectively. You can leverage Mason for its dependency management capabilities while employing Make for broader build commands requiring more control.

Quick Start Instructions¶

To install mason, run make mason from your Chapel home directory.

To create a new mason application run: mason new <MyAppName>. This will create a mason project in a new directory MyAppName with the following structure:

MyAppName/
├── src/
│   └── MyAppName.chpl
└── Mason.toml

The app can be run by calling mason build followed by mason run from within MyAppName.

Or, to create a mason package that can be used as a dependency in other mason projects, run: mason new <MyPackageName> --lib. This will create a similar file structure; however, the primary source file, MyPackageName.chpl, won’t have a main routine because the library is not intended to be run as a standalone program:

MyPackageName/
├── src/
│   └── MyPackageName.chpl
└── Mason.toml

For either type of mason project, add new dependencies with mason add <package name>. This will add the new dependency to the list in the toml file. When the project is built, mason will download source files for all Chapel dependencies using the Mason-Registry, allowing them to be used in the application or library.

Note that mason also supports numerous other features such as unit testing, examples, and documentation. See the sections below for more information.

Getting Started with Mason¶

In this section, you will find more detailed information about installing mason and a basic HelloWorld example to get you started using mason packages in your own code.

Mason Guide¶

This section aims to explain why a user would want to use mason, point out what types of users would benefit from using mason, outline some typical use-cases of mason, and introduce some of the features that make using mason worthwhile.