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.
Note
Pardon Our Dust
This mason guide is a work-in-progress as mason development itself is still a work-in-progress. If you’re not already using the main branch of the documentation (which tracks real-time GitHub development), you may find that it contains a more complete set of sections. We welcome feedback and requests on the guide as we go.
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.
- Basic Usage
- Building and Running
- Building Larger Packages
- Runtime/Compilation Arguments
- Testing your Package
- Creating and Running Examples
- Documenting a Package
- Using Chapel Dependencies
- Specifying Dependencies from
git
Repositories - Using Non-Chapel Dependencies
- Mason-Registry
- Local Registries
- Submit a Package
- Semantic Versioning
- Incompatible Version Resolution Strategy
- The Manifest File
- The Lock File
- Environment Variables
- Namespacing