This article is about rebar3_plugin — a simple

In the article “Spell check your Erlang code with Sheldon” I quickly mentioned this tool — but since all should start from something… I think it deserved its own article.

What is rebar3_plugin?

I don’t know about you, but when I first tried to build a plugin for rebar3, I had a lot of questions, and I spent quite a lot of time looking for documentation with examples. I also spent a lot of time comparing the skeleton of my plugin with already existing ones.

Then,

A rebar3-plugin template repo in

GitHub

: I know that

GitHub

has template repos now and, after building multiple too similar projects, I would like to see if we can use it to avoid code duplication.

What Should my Template Include?

The first question on my mind was: what does he mean by code duplication?
Since I had never developed plugins before, the first thing I did was to start comparing repositories…

These are my findings:

• All rebar3 plugin repos have a basic skeleton based on the rebar3 docs.
• Almost all plugins could take extra arguments through the command line.
• Nearly all plugins have additional project plugins that they use, for instance, to format and check their code.
• Most plugins have basic common tests.
• Most all plugins are verified with GitHub Actions
• Most plugins use
  GitHub
  Issues Templates

How powerful are

Now that I had all I needed, I started my initial attempt at setting up a

After some googling and reading the official GitHub documentation about creating a template repository — to my surprise, I found that they don’t auto-generate code, and they don’t have template variables or any other mechanism to personalize the repo automatically when you generate a new one based on it. In the end, it ends up being not much more than a forked repo.

For me, that was not nearly enough; I wanted plugin developers to be able to introduce the name and description of their repo somewhere… and then… boom! Automagically have a full-fledged rebar3 plugin that they could start improving on. ✨

The Workaround

For this project to be actually helpful, we needed to implement something that would automatically and quickly turn the template code into something useful. To do that, I considered some options, namely using a script, or a shell script, or just using Makefile.

I went for a bash script since it could look simple and efficient. That’s why the template repository includes a bootstrap script that you need to run (as you will see below) to go from rebar3_plugin to your_plugin.

How to build your plugin based on rebar3_plugin?

So that was the story of how rebar3_plugin came to be. Now let’s see what you can do with it?

• Go to the rebar3_plugin
  GitHub
  page.
• Find and click on the button labeled Use this template or use this link.
• Add a name and a description for your new rebar3 plugin on the new page.
• Click the Create Repository from Template button.
• You will be redirected to your new repository page.
• Clone your new repository on your computer.
• Run ./bootstrap.
• Verify the generated code.
• Commit and publish your changes.
• Celebrate! 🎉

After following those steps, you will now have your rebar3 plugin, including:

• GitHub
  Actions with Linux/Windows jobs
• GitHub
  Issue Templates
• The basic structure to start adding Common Tests
• Project Plugins (rebar3_hex, rebar3_format, rebar3_lint, rebar3_hank), including the great rebar3 test alias to run them all at once.
• A fantastic and pretty useful configuration on rebar.config with all the OTP stuff.

The structure of your folder tree will look like the following one:

$ ./bootstrap
$ tree -a
├── .github
│   ├── ISSUE_TEMPLATE
│   │   ├── bug_report.md
│   │   ├── feature_request.md
│   │   └── other_issues.md
│   └── workflows
│       └── ci.yaml
├── src
│   ├── rebar3_plugin.app.src
│   ├── rebar3_plugin.erl
│   └── rebar3_plugin_prv.erl
└── test
    └── rebar3_plugin_SUITE.erl
├── .gitignore
├── LICENSE
├── README.md
├── CHANGELOG.md
├── rebar.config
├── elvis.config
├── rebar.lock

Since a picture is worth a thousand words, you will find screenshots for all the steps we just went through below.

What if I use GitLab or don’t want to use GitHub Actions, Issue Templates, and project plugins?

Well, this is sad 😢
But we have a solution for you! 😋
You can use bootstrap with the argument clean to build a rebar3 plugin without any additional config and

$ ./bootstrap clean
$ tree -a
├── src
│   ├── rebar3_plugin.app.src
│   ├── rebar3_plugin.erl
│   └── rebar3_plugin_prv.erl
└── test
    └── rebar3_plugin_SUITE.erl
├── .gitignore
├── LICENSE
├── README.md
├── CHANGELOG.md
├── rebar.config
├── rebar.lock

As you can see, you don’t need to spend a lot of time making the next awesome rebar3 plugin using the rebar3_plugintemplate. So… what are you waiting for?! 😉

What plugins use rebar3_plugin template already?

At the very least:

• rebar3_sheldon— A rebar plugin for spellchecking code with Sheldon
• rebar3_edoc_extensions — A plugin for extensions of EDoc

And much more will come! 🔥

Of course, this is not the final version of rebar3_plugin. Multiple ideas are floating around for extending it and adding support for additional command-line attributes and what-not. As usual, feel free to leave comments or open issues in

Special Thanks!

Thank you,