PkgTemplates Developer Guide

• PkgTemplates Developer Guide
• • Template + Package Creation Pipeline
  • Plugin Walkthrough
  • FilePlugin Walkthrough
  • Doing Extra Work With FilePlugins
  • Supporting Interactive Mode
  • Miscellaneous Tips
  • Testing

Issues and pull requests are welcome! New contributors should make sure to read the ColPrac Contributor Guide.

PkgTemplates can be easily extended by adding new Plugins.

There are three types of plugins: Plugin, FilePlugin, and BadgePlugin.

Template + Package Creation Pipeline

The Template constructor basically does this:

- extract values from keyword arguments
- create a Template from the values
- for each plugin:
  - validate plugin against the template

The plugin validation step uses the validate function. It lets us catch mistakes before we try to generate packages.

validate(::Plugin, ::Template)

The package generation process looks like this:

- create empty directory for the package
- for each plugin, ordered by priority:
  - run plugin prehook
- for each plugin, ordered by priority:
  - run plugin hook
- for each plugin, ordered by priority:
  - run plugin posthook

As you can tell, plugins play a central role in setting up a package.

The three main entrypoints for plugins to do work are the prehook, the hook, and the posthook. As the names might imply, they basically mean "before the main stage", "the main stage", and "after the main stage", respectively.

Each stage is basically identical, since the functions take the exact same arguments. However, the multiple stages allow us to depend on artifacts of the previous stages. For example, the Git plugin uses posthook to commit all generated files, but it wouldn't make sense to do that before the files are generated.

But what about dependencies within the same stage? In this case, we have priority to define which plugins go when. The Git plugin also uses this function to lower its posthook's priority, so that even if other plugins generate files in their posthooks, they still get committed (provided that those plugins didn't set an even lower priority).

prehook(::Plugin, ::Template, pkg_dir::AbstractString)

hook(::Plugin, ::Template, pkg_dir::AbstractString)

posthook(::Plugin, ::Template, pkg_dir::AbstractString)

priority(::Plugin, ::Union{typeof(prehook), typeof(hook), typeof(posthook)}) -> Int

Plugin Walkthrough

Concrete types that subtype Plugin directly are free to do almost anything. To understand how they're implemented, let's look at simplified versions of two plugins: Documenter to explore templating, and Git to further clarify the multi-stage pipeline.

Example: Documenter

@plugin struct Documenter <: Plugin
    make_jl::String = default_file("docs", "make.jlt")
    index_md::String = default_file("docs", "src", "index.md")
end

gitignore(::Documenter) = ["/docs/build/"]

badges(::Documenter) = [
    Badge(
        "Stable",
        "https://img.shields.io/badge/docs-stable-blue.svg",
        "https://{{{USER}}}.github.io/{{{PKG}}}.jl/stable",
    ),
    Badge(
        "Dev",
        "https://img.shields.io/badge/docs-dev-blue.svg",
        "https://{{{USER}}}.github.io/{{{PKG}}}.jl/dev",
    ),
]

view(p::Documenter, t::Template, pkg::AbstractString) = Dict(
    "AUTHORS" => join(t.authors, ", "),
    "PKG" => pkg,
    "REPO" => "$(t.host)/$(t.user)/$pkg.jl",
    "USER" => t.user,
)

function hook(p::Documenter, t::Template, pkg_dir::AbstractString)
    pkg = pkg_name(pkg_dir)
    docs_dir = joinpath(pkg_dir, "docs")

    make = render_file(p.make_jl, combined_view(p, t, pkg), tags(p))
    gen_file(joinpath(docs_dir, "make.jl"), make)

    index = render_file(p.index_md, combined_view(p, t, pkg), tags(p))
    gen_file(joinpath(docs_dir, "src", "index.md"), index)

    # What this function does is not relevant here.
    create_documentation_project()
end

The @plugin macro defines some helpful methods for us. Inside of our struct definition, we're using default_file to refer to files in this repository.

@plugin struct ... end

using PkgTemplates: PkgTemplates, @plugin, @with_kw_noshow, Plugin
@plugin struct MyPlugin <: Plugin
    x::String = "hello!"
    y::Union{Int, Nothing} = nothing
end

using PkgTemplates: PkgTemplates, Plugin
struct MyPlugin <: Plugin
    x::String
end
PkgTemplates.defaultkw(::Type{MyPlugin}, ::Val{:x}) = "my default"

default_file(paths::AbstractString...) -> String

The first method we implement for Documenter is gitignore, so that packages created with this plugin ignore documentation build artifacts.

gitignore(::Plugin) -> Vector{String}

Second, we implement badges to add a couple of badges to new packages' README files.

badges(::Plugin) -> Union{Badge, Vector{Badge}}

Badge(hover::AbstractString, image::AbstractString, link::AbstractString)

These two functions, gitignore and badges, are currently the only "special" functions for cross-plugin interactions. In other cases, you can still access the Template's plugins to depend on the presence/properties of other plugins via getplugin, although that's less powerful.

getplugin(t::Template, ::Type{T<:Plugin}) -> Union{T, Nothing}

Third, we implement view, which is used to fill placeholders in badges and rendered files.

view(::Plugin, ::Template, pkg::AbstractString) -> Dict{String, Any}

Finally, we implement hook, which is the real workhorse for the plugin. Inside of this function, we generate a couple of files with the help of a few more text templating functions.

render_file(file::AbstractString, view::Dict{<:AbstractString}, tags=nothing) -> String

render_text(text::AbstractString, view::Dict{<:AbstractString}, tags=nothing) -> String

gen_file(file::AbstractString, text::AbstractString)

combined_view(::Plugin, ::Template, pkg::AbstractString) -> Dict{String, Any}

tags(::Plugin) -> Tuple{String, String}

pkg_name(pkg_dir::AbstractString)

For more information on text templating, see the FilePlugin Walkthrough and the section on Custom Template Files.

Example: Git

struct Git <: Plugin end

priority(::Git, ::typeof(posthook)) = 5

function validate(::Git, ::Template)
    foreach(("user.name", "user.email")) do k
        if isempty(LibGit2.getconfig(k, ""))
            throw(ArgumentError("Git: Global Git config is missing required value '$k'"))
        end
    end
end

function prehook(::Git, t::Template, pkg_dir::AbstractString)
    LibGit2.with(LibGit2.init(pkg_dir)) do repo
        LibGit2.commit(repo, "Initial commit")
        pkg = pkg_name(pkg_dir)
        url = "https://$(t.host)/$(t.user)/$pkg.jl"
        close(GitRemote(repo, "origin", url))
    end
end

function hook(::Git, t::Template, pkg_dir::AbstractString)
    ignore = mapreduce(gitignore, append!, t.plugins)
    unique!(sort!(ignore))
    gen_file(joinpath(pkg_dir, ".gitignore"), join(ignore, "\n"))
end

function posthook(::Git, ::Template, pkg_dir::AbstractString)
    LibGit2.with(GitRepo(pkg_dir)) do repo
        LibGit2.add!(repo, ".")
        LibGit2.commit(repo, "Files generated by PkgTemplates")
    end
end

We didn't use @plugin for this one, because there are no fields. Validation and all three hooks are implemented:

• validate makes sure that all required Git configuration is present.
• prehook creates the Git repository for the package.
• hook generates the .gitignore file, using the special gitignore function.
• posthook adds and commits all the generated files.

As previously mentioned, we use priority to make sure that we wait until all other plugins are finished their work before committing files.

Hopefully, this demonstrates the level of control you have over the package generation process when developing plugins, and when it makes sense to exercise that power!

FilePlugin Walkthrough

Most of the time, you don't really need all of the control that we showed off above. Plugins that subtype FilePlugin perform a much more limited task. In general, they just generate one templated file.

To illustrate, let's look at the Citation plugin, which creates a CITATION.bib file.

@plugin struct Citation <: FilePlugin
    file::String = default_file("CITATION.bib")
end

source(p::Citation) = p.file
destination(::Citation) = "CITATION.bib"

tags(::Citation) = "<<", ">>"

view(::Citation, t::Template, pkg::AbstractString) = Dict(
    "AUTHORS" => join(t.authors, ", "),
    "MONTH" => month(today()),
    "PKG" => pkg,
    "URL" => "https://$(t.host)/$(t.user)/$pkg.jl",
    "YEAR" => year(today()),
)

Similar to the Documenter example above, we're defining a keyword constructor, and assigning a default template file from this repository. This plugin adds nothing to .gitignore, and it doesn't add any badges, so implementations for gitignore and badges are omitted.

First, we implement source and destination to define where the template file comes from, and where it goes. These functions are specific to FilePlugins, and have no effect on regular Plugins by default.

source(::FilePlugin) -> Union{String, Nothing}

destination(::FilePlugin) -> String

Next, we implement tags. We briefly saw this function earlier, but in this case it's necessary to change its behaviour from the default. To see why, it might help to see the template file in its entirety:

@misc{<<&PKG>>.jl,
	author  = {<<&AUTHORS>>},
	title   = {<<&PKG>>.jl},
	url     = {<<&URL>>},
	version = {v0.1.0},
	year    = {<<&YEAR>>},
	month   = {<<&MONTH>>}
}

Because the file contains its own {} delimiters, we need to use different ones for templating to work properly.

Finally, we implement view to fill in the placeholders that we saw in the template file.

Doing Extra Work With FilePlugins

Notice that we didn't have to implement hook for our plugin. It's implemented for all FilePlugins, like so:

function render_plugin(p::FilePlugin, t::Template, pkg::AbstractString)
    return render_file(source(p), combined_view(p, t, pkg), tags(p))
end

function hook(p::FilePlugin, t::Template, pkg_dir::AbstractString)
    source(p) === nothing && return
    pkg = pkg_name(pkg_dir)
    path = joinpath(pkg_dir, destination(p))
    text = render_plugin(p, t, pkg)
    gen_file(path, text)
end

But what if we want to do a little more than just generate one file?

A good example of this is the Tests plugin. It creates runtests.jl, but it also modifies the Project.toml to include the Test dependency.

Of course, we could use a normal Plugin, but it turns out there's a way to avoid that while still getting the extra capbilities that we want.

The plugin implements its own hook, but uses invoke to avoid duplicating the file creation code:

@plugin struct Tests <: FilePlugin
    file::String = default_file("runtests.jlt")
end

source(p::Tests) = p.file
destination(::Tests) = joinpath("test", "runtests.jl")
view(::Tests, ::Template, pkg::AbstractString) = Dict("PKG" => pkg)

function hook(p::Tests, t::Template, pkg_dir::AbstractString)
    # Do the normal FilePlugin behaviour to create the test script.
    invoke(hook, Tuple{FilePlugin, Template, AbstractString}, p, t, pkg_dir)
    # Do some other work.
    add_test_dependency()
end

There is also a default validate implementation for FilePlugins, which checks that the plugin's source file exists, and throws an ArgumentError otherwise. If you want to extend the validation but keep the file existence check, use the invoke method as described above.

For more examples, see the plugins in the Continuous Integration (CI) and Code Coverage sections.

Supporting Interactive Mode

When it comes to supporting interactive mode for your custom plugins, you have two options: write your own interactive method, or use the default one. If you choose the first option, then you are free to implement the method however you want. If you want to use the default implementation, then there are a few functions that you should be aware of, although in many cases you will not need to add any new methods.

interactive(T::Type{<:Plugin}) -> T

prompt(::Type{P}, ::Type{T}, ::Val{name::Symbol}) -> Any

customizable(::Type{<:Plugin}) -> Vector{Pair{Symbol, DataType}}

input_tips(::Type{T}) -> Vector{String}

convert_input(::Type{P}, ::Type{T}, s::AbstractString) -> T

Miscellaneous Tips

Writing Template Files

For an overview of writing template files for Mustache.jl, see Custom Template Files in the user guide.

Predicates

There are a few predicate functions for plugins that are occasionally used to answer questions like "does this Template have any code coverage plugins?". If you're implementing a plugin that fits into one of the following categories, it would be wise to implement the corresponding predicate function to return true for instances of your type.

needs_username(::Plugin) -> Bool

is_ci(::Plugin) -> Bool

is_coverage(::Plugin) -> Bool

Formatting Version Numbers

When writing configuration files for CI services, working with version numbers is often needed. There are a few convenience functions that can be used to make this a little bit easier.

compat_version(v::VersionNumber) -> String

format_version(v::Union{VersionNumber, AbstractString}) -> String

collect_versions(t::Template, versions::Vector) -> Vector{String}

Testing

If you write a cool new plugin that could be useful to other people, or find and fix a bug, you're encouraged to open a pull request with your changes. Here are some testing tips to ensure that your PR goes through as smoothly as possible.

Updating Reference Tests & Fixtures

If you've added or modified plugins, you should update the reference tests and the associated test fixtures. In test/reference.jl, you'll find a "Reference tests" test set that basically generates a bunch of packages, and then checks each file against a reference file, which is stored somewhere in test/fixtures. Note the reference tests only run on one specific version of Julia; check test/runtests.jl to see the current version used.

For new plugins, you should add an instance of your plugin to the "All plugins" and "Wacky options" test sets, then run the tests with Pkg.test. They should pass, and there will be new files in test/fixtures. Check them to make sure that they contain exactly what you would expect!

For changes to existing plugins, update the plugin options appropriately in the "Wacky options" test set. Failing tests will give you the option to review and accept changes to the fixtures, updating the files automatically for you.

Running reference tests locally

In the file test/runtests.jl, there is a variable called REFERENCE_JULIA_VERSION, currently set to v"1.7.2". If you use any other Julia version (even the latest stable one) to launch the test suite, the reference tests mentioned above will not run, and you will miss a crucial correctness check for your code. Therefore, we strongly suggest you test PkgTemplates locally against Julia 1.7.2. This version can be easily installed and started with juliaup:

juliaup add 1.7.2
julia +1.7.2

Updating "Show" Tests

Depending on what you've changed, the tests in test/show.jl might fail. To fix those, you'll need to update the expected value to match what is actually displayed in a Julia REPL (assuming that the new value is correct).