Templates

Default Variables

  • date: defaults to today’s date, under universal time, printed according to RFC 8601 (for example, "2014-03-11")
  • datetime: defaults to today’s date and time, under universal time, printed according to RFC 8601 (for example, "2014-03-11T16:06:02+00:00").
  • author_name: Defaults to "Anonymous"
  • author_email: Defaults to "anonymous@example.org"
  • apps_dir: Directory where OTP applications should be created in release projects. Defaults to "apps/".
  • copyright_year: Defaults to the current year, under universal time.

Global Variables

Global variables can be set by editing the file at $HOME/.config/rebar3/templates/globals:

  1. {variables, [
  2.    {author_name, "My Name Is A String"},
  3.    {copyright_year, "2014-2022", "The year or range of years for copyright"},
  4.    {my_custom_var, "hello there"}
  5. ]}.

This will let you define variables for all templates. Variables left undefined will be ignored and revert to the default value.

The override order for these variables will be: Defaults < $HOME/.config/rebar3/templates/globals < command line invocation.

Batteries-Included Templates

Rebar3 ships with a few templates installed, which can be listed by calling rebar3 new:

  1. $ ./rebar3 new
  2. app (built-in): Complete OTP Application structure.
  3. cmake (built-in): Standalone Makefile for building C/C++ in c_src
  4. escript (built-in): Complete escriptized application structure
  5. lib (built-in): Complete OTP Library application (no processes) structure
  6. plugin (built-in): Rebar3 plugin project structure
  7. release (built-in): OTP Release structure for executable programs

Any custom plugins would be followed as (custom): .

Details for each individual plugin can be obtained by calling rebar3 new help :

  1. $ ./rebar3 new help plugin
  2. plugin:
  3.         built-in template
  4.         Description: Rebar3 plugin
  5.         Variables:
  6.                 name="myplugin" (Name of the plugin)
  7.                 desc="A rebar plugin" (Short description of the plugin's purpose)
  8.                 date="2014-11-10"
  9.                 datetime="2014-11-10T18:29:41+00:00"
  10.                 author_name="Anonymous"
  11.                 author_email="anonymous@example.org"
  12.                 copyright_year="2014"
  13.                 apps_dir="apps/" (Directory where applications will be created if needed)

All the variables there have their default values shown, and an optional explanation in parentheses. The variables can also be overriden globally.

A template can be run by calling:

  1. $ ./rebar3 new plugin name=demo author_name="Fred H."
  2. ...
  3. $ ./rebar3 new plugin demo author_name="Fred H."
  4. ...

Then go to the directory created for the project by rebar3.

Custom Templates

Custom templates can be added in $HOME/.config/rebar3/templates/. Each template is at least two files:

  • my_template.erl: There can be many of these files. They are regular Erlang files using the mustache template syntax for variable replacements (provided by soranoba’s implementation).
  • my_template.template; Called the template index, there is one per template callable from rebar3. This one will be visible when calling rebar3 new my_template. This file regroups the different mustache template files into a more cohesive template.

File Syntax

Template Index

The following options are available:

  1. {description, "This template does a thing"}.
  2. {variables, [
  3.     {var1, "default value"},
  4.     {var2, "default", "explain what this does in help files"},
  5.     {app_dir, ".", "The directory where the application goes"}
  6.   ]}.
  7. {dir, "{{appdir}}/src"}.
  8. {file, "mytemplate_README", "README"}.
  9. {chmod, "README", 8#644}.
  10. {template, "myapp/myapp.app.src", "{{appdir}}/src/{{name}}.app.src"}.

Specifically:

  • description: takes a string explaining what the template is for.
  • variables: takes a list of variables in two forms:
    • {Name, DefaultString, HelpString};
    • {Name, DefaultString}.
  • {dir, TemplatablePathString}: creates a given directory. Variable names can be used in the path name.
  • {file, FilePath, DestFilePath}: copies a file literally to its destination.
  • {template, FilePath, TemplatablePathString}: evaluates a given template. The FilePath is relative to the template index.
  • {chmod, FilePath, Int}: changes the permission of a file, using the integer value specified. Octal values can be entered by doing 8#640.

Example

As an example, we’ll create a template for Common Test test suites. Create the directory structure ~/.config/rebar3/templates/ and then go in there.

We’ll start with an index for our template, called ct_suite.template:

  1. {description, "A basic Common Test suite for an OTP application"}.
  2. {variables, [
  3.     {name, "suite", "Name of the suite, prepended to the standard _SUITE suffix"}
  4. ]}.
  6. {dir, "test"}.
  7. {template, "ct_suite.erl", "test/{{name}}_SUITE.erl"}.

This tells rebar3 to create the test directory and to evaluate a mustache template. All the paths are relative to the current working directory.

Let’s create the template file:

  1. -module({{name}}_SUITE).
  3. -include_lib("common_test/include/ct.hrl").
  4. -include_lib("eunit/include/eunit.hrl"). % Eunit macros for convenience
  6. -export([all/0
  7.         ,groups/0
  8.        %,init_per_suite/1, end_per_suite/1
  9.        %,init_per_group/2, end_per_group/2
  10.         ,init_per_testcase/2, end_per_testcase/2
  11.         ]).
  13. -export([fail/1]).
  15. all() -> [fail].
  17. groups() -> [].
  19. init_per_testcase(_Name, Config) -> Config.
  21. end_per_testcase(_Name, _Config) -> ok.
  23. fail(_Config) ->
  24.     ?assert(false).

This one does very simple variable substitution for the name (using {{name}}) and that’s all it needs.

Let’s get to any existing project you have and try it:

  1. $ ./rebar3 new
  2. app (built-in): OTP Application
  3. ct_suite (custom): A basic Common Test suite for an OTP application
  4. lib (built-in): OTP Library application (no processes)
  5. release (built-in): OTP Release structure for executable programs
  6. plugin (built-in): Rebar3 plugin

The first line shows that our ct_suite template has been detected and is usable.

Let’s look at the details:

  1. $ ./rebar3 new help ct_suite
  2. ct_suite:
  3.         custom template (/home/ferd/.config/rebar3/templates/ct_suite.template)
  4.         Description: A basic Common Test suite for an OTP application
  5.         Variables:
  6.                 name="suite" (Name of the suite, prepended to the standard _SUITE suffix)
  7.                 date="2014-11-10"
  8.                 datetime="2014-11-10T18:46:33+00:00"
  9.                 author_name="Anonymous"
  10.                 author_email="anonymous@example.org"
  11.                 copyright_year="2014"
  12.                 apps_dir="apps/" (Directory where applications will be created if needed)

The documentation from variables and the description are well in place. To apply the template, go to any of your OTP application’s top-level directory:

  1. $ ./rebar3 new ct_suite demo
  2. ===> Writing test/demo_SUITE.erl

And you will see the code in place.

Plugin Templates

Plugins can be shipped with their own templates that then get listed along with the rest of templates. The structure is exactly similar to those found in ~/.config/rebar3/templates/, except they must be placed in the plugin’s priv/ directory.