👷 Using Bricks

In this section, we'll take a look at how to use the make command to generate code from an existing brick.

🚀 Overview

As we saw in the overview, we can run the mason make command followed by the name of an installed brick to generate code from that brick:

mason make hello
? What is your name? (Dash) Mason
✓ Generated 1 file. (29ms)
  created HELLO.md

🧑‍💻 Command-line Args

By default, if a brick requires variables mason will prompt for those variables as seen in the snippet above. If we know in advance what variables a brick requires, we can provide variables to mason as command-line arguments:

mason make hello --name Mason
✓ Generated 1 file. (29ms)
  created HELLO.md

Notice how in the above example, mason did not prompt for the name since it was already provided as an argument.

note

In cases where there are multiple variables, it's possible to supply any number of variables directly as command-line args and mason will prompt for any missing variables automatically.

📝 Config File

In some cases, it may be inconvenient to have to provide variables manually or via command-line args (especially for templates that require many variables). In these cases, we can provide variables via a configuration file. For example, if we create a file called config.json with the following contents:

{
  "name": "Mason"
}

We can then pass the config file to mason make via the -c option:

mason make hello -c config.json
✓ Generated 1 file. (29ms)
  created HELLO.md

note

The configuration file can have any name and can live anywhere on your local file system.

🗂 Custom Output Directory

By default mason make will generate the output in the current working directory but a custom output directory can be specified via the -o option:

mason make hello --name Mason -o ./out
✓ Generated 1 file. (29ms)
  created out/HELLO.md

note

mason will automatically create any missing directories for you if you specify an output directory which doesn't already exist.

❗️ File Conflict Resolution

A conflict can occur when mason attempts to generate a file which already exists and the contents of the existing file differ from the contents of the generated file.

mason make hello --name Dash
conflict HELLO.md
Overwrite HELLO.md? (Yyna) y
✓ Generated 1 file. (21.6s)
  created HELLO.md

HELLO.md

- Hello Mason! 👋
+ Hello Dash! 👋

By default, mason make will prompt on each file conflict and will allow users to specify how the conflict should be resolved via the following options:

y - yes, overwrite (default)
Y - yes, overwrite this and all others
n - no, do not overwrite
a - append to existing file

✅ Conflict Resolution Strategy

A custom file conflict resolution strategy can be specified via the --on-conflict option:

# Always prompt when there is a file conflict (default)
mason make hello --name Mason --on-conflict prompt

# Always overwrite when there is a file conflict
mason make hello --name Mason --on-conflict overwrite

# Always skip when there is a file conflict
mason make hello --name Mason --on-conflict skip

# Always append when there is a file conflict
mason make hello --name Mason --on-conflict append

🕵️ Detecting Changes

In some cases, it may be useful to detect whether running mason make for a given brick produces a diff. For example, you may want to add a step in a continuous integration workflow which runs mason make for a given brick to ensure developers ran a codegen step prior to opening a pull request. The --set-exit-if-changed flag will exit with an error code if any files were changed after running mason make:

# 🚨 Exit with error if any files were changed
mason make hello --name Dash --set-exit-if-changed