I started playing with this today, and have come up with a sample application here. The basic concept behind rebar plugins is fairly simple: you refer to them in your
rebar.config and they get hooked into the build at execution time. Naturally rebar (which is executed via escript) needs to be able to find the beam code for these (plugin) modules on the code path, so if you’re putting one together specifically for a project, you’ll need to take advantage of rebar’s
sub_dirs support in order to pre-compile them before the rest of your code. The sample project does just that, by compiling the build project prior to the rest of the sources. Including it in your
lib_dirs also ensures it is on the code path.
So what can you do with your plugins?
Plugins do not participate in rebar’s preprocess stage, so they cannot run in isolation from the core (internal) rebar modules – edit: as of a while back, plugins do in fact participate in the pre and post processing via the same callbacks as built in modules. Check out some of my later posts, or better still head over to http://hyperthunk.github.com/rebar-plugin-tutorial/ for more details.
In practise, this means that your plugin can do one of two things:
- Hook into an existing command (such as ‘compile’), or
- Expose a new command (such as ‘frobble’ in the example code on github)
The second approach comes with (yet more) caveats though: new, custom commands cannot run in isolation. I suspect this is because plugins do not participate in the preprocess stage, or that they’re excluded from the code that identified modules willing to handle a given command, or both. This means that the
rebar_frobble plugin from the example project, runs in two contexts:
- During execution of the ‘compile’ command, after the other (internal) modules have handled it
- After execution of the ‘compile’ command, during execution of the ‘frobble’ command
In practice, this means you can run [
rebar compile frobble], but not [
rebar frobble]. [UPDATE] If you referenced the plugin in the top level rebar.config, it would remedy this situation, but you don’t always want to do that. This isn’t very intuitive and I suspect the developers may decide to clarify (or change) this behaviour in future. Despite the slightly confusing execution profile, rebar plugins are a very neat way of customising your rebar build. With full access to all the rebar internal modules, as well as the current (local and global) configuration, the plugin author has a lot of flexibility and power at their fingertips. Naturally with great power comes great responsibility, and plugin authors should consider carefully the use of exports besides published command names and their command/2 function interfaces.