Why would I want to use mason?¶
So, you want to write some Chapel code and find yourself asking if it would make sense to use mason or if it would just end up adding needless overhead to your project in the long run. Here’s an answer for you: Yes! You should use mason!
Using mason brings with it a number of valuable features that are not available
to users of the old-fashioned
chpl command. Some of these are:
access to libraries contributed by the Chapel community (see Using a Mason Package)
portable, simple build commands (see Building and Running)
a built-in testing framework to help test your code (see Testing your Package)
make your code easily shareable on GitHub (see Specifying Dependencies from git Repositories)
contribute your own libraries and help the Chapel community grow (see Submit a Package)
So, you see, a better question would be “Why not use mason?” instead of “Why use mason?”
The Three Modes of Mason¶
Now, having answered the “why” of mason, let’s get into the “how”.
There are three distinct types of mason packages:
mason lightweight projects
Each of these types of mason packages serve different purposes and, to use mason effectively, it helps to know what each type has been designed for.
A mason application, which is the default type of mason package, is meant to be a self-contained, executable, full application. What this means is that a mason application will have a main module and expect to be built and run as a standalone application, as opposed to being only a library that contains functions that are valuable to users, but you wouldn’t want to run by themselves.
When you create a mason application with
mason new <package-name> or
mason new <package-name> --app, the default module created will have a
already in place. This is what drives your application and where the execution will start.
main() function is unique to the mason application package type and makes it the only
type of mason package that can be ran via
When compiling Chapel code, there can only be one
main() function (or you will need to use the
--main-module flag to specify which one to run). This means that mason application package
types are not meant to be used as dependencies for other mason packages and cannot be added as a
dependency with the
mason add <library-name@version> command. Rather, mason applications published
to the mason registry can be downloaded, built, and run using the mason install <application-name>
command (which is currently a work in progress). If you would like to create a library with functions
to be exposed to other users, the mason library is what you are looking for (see Mason Libraries).
Some examples of when you would want to use a mason application as opposed to one of the other types are a benchmark that you would like others to be able to compile and execute in a reproducible way, an application that simulates the weather, or just about anywhere you have a cool program that you would like to share.
A mason library is meant to be a module that contains functions that are to be made accessible
to other users. Mason libraries do not have a
main() function and cannot be run with the
mason run command, but Mason library code can be executed through examples
(see Creating and Running Examples).
To start writing your own mason library, use the
mason new <package-name> --lib command and
mason will create an empty default module. Inside the empty module you can define the
functions your library will provide to its users.
Some examples of when you would want to create a mason library as opposed to an application are:
You want to provide a linear algebra library for other Chapel programs
You have multiple Chapel projects that depend on a common set of functionality you wish to centralize
You found some functionality missing from Chapel, and think others could benefit from your solution
Mason Lightweight Projects¶
A mason lightweight project is simply a mason manifest file that tracks which mason packages your Chapel code depends on. This gives all Chapel users the ability to use mason libraries as dependencies, without forcing your project to use the folder structure defined for mason packages.
Lightweight packages cannot use most mason commands, such as
mason build or
mason run, but a special
mason modules command allows you to get the
chpl compiler flags necessary to include the list of
dependencies in your Chapel project.
When you run the
mason new --light command to create a lightweight package, mason creates a basic
Mason.toml file in the current directory. You can add dependencies to that file by using the
mason add <package-name@ver> command or specifying a git dependency (see Specifying Dependencies from git Repositories),
the same as you would for other mason package types.
After adding your project’s dependencies to the
Mason.toml file, use the
mason modules command to
print out the flags that should be added to your build system’s chpl compilation step.
The main reason you would use a lightweight mason project as opposed to one of the other
types of mason project types would be in the case that you already have a project that is
built out and has its own well-defined build process that uses something like a
to handle building, so you just want to use some mason packages without having to corral
your directory structure to fit the requirements of a mason application.