Sources

Sources are a way to declare many related templates together into a single collection. By convention, you typically define them at the root of a template or Git repo as boilermaker_source.toml and they have the following structure:

Structure

[source]
name = ""
description = ""
backend = "sql::sqlite"

[[templates]]
repo = ""
name = ""
lang = ""
branch = ""

[[templates]]
...

NOTE: "sql::sqlite" is the only option as of writing but will likely be expanded in the future.

Usage

Once you have this, a "Source" is basically just a file that lives at some URL ("coordinate" in Boilermaker parlance). For instance, maybe you saved it to the root directory of a Git repo.

To add the source to your local database, you can use the boil sources add command which simply takes the coordinate to the raw source content. Boilermaker will then download the file and install each template as a "Source Template."

boil sources add COORDINATE

TIP: that while very similar, an "installed template" and "source template" are not identical. However, you can install templates from source templates.

Example

This example is from an early version of the boil-hello-world template, which is both the template and source. It demonstrates using a single template but adding each language implementation as a separate template in the source. Why, you ask? This allows adding all these templates to the database in a single go and makes them immediately available for the search engine.

TIP: There is no hard and fast rule about how or why you may want to group templates together. Sources just provide a generic, reusable way to accomplish it.

TIP: Bootstrapping the repo as both the template and source is not a requirement.

Without further explanation, given this source definition:

[source]
name = "source_boil-hello-world"
description = "Source for official Boilermake Hello World templates"
backend = "sql::sqlite"

[[templates]]
repo = "https://github.com/yeajustmars/boil-hello-world"
name = "hello-world"
lang = "bash"
branch = "main"

[[templates]]
repo = "https://github.com/yeajustmars/boil-hello-world"
name = "hello-world"
lang = "clojure"
branch = "main"

[[templates]]
repo = "https://github.com/yeajustmars/boil-hello-world"
name = "hello-world"
lang = "javascript"
branch = "main"

[[templates]]
repo = "https://github.com/yeajustmars/boil-hello-world"
name = "hello-world"
lang = "python"
branch = "main"

[[templates]]
repo = "https://github.com/yeajustmars/boil-hello-world"
name = "hello-world"
lang = "rust"
branch = "main"

We can see a few things:

• the [source] section is for the source metadata about the source itself.
• [[templates]] just creates a list of templates in TOML.
• each template states its repo url, name, language and branch. There is a lot of overlap here with the fields that exist in the [project] section of a boilermaker.toml template config.

To add this source, you can run the following command:

boil sources add https://raw.githubusercontent.com/yeajustmars/boil-hello-world/refs/heads/main/boilermaker_source.toml