Generic project template generator for Mix.
This project implements a Mix task named newer
which can take a specially
prepared file hierarchy and create scaffolding for a new project from it.
Download the latest archive from the Releases page
$ mix archive.install https://github.com/Rastopyr/mix-newer/releases/download/alpha2/mix_newer-0.2.0.ez
or build from source as follows:
$ mix archive.build
$ mix archive.install
Some examples:
# Build a project from Phoenix template, overriding the 'session_secret'
# parameter's value
$ mix newer
-t https://github.com/alco/mix-phoenix-template.git
-o session_secret=abc
myphoenix
$ ls myphoenix
README.md config lib mix.exs priv test web
$ ls myphoenix/lib
myphoenix.ex
# Build a project from Elixir template, passing the custom --sup flag defined
# by it
$ mix newer -t https://github.com/alco/mix-elixir-template.git myapp --sup
$ ls myapp
README.md config lib mix.exs test
$ ls myapp/test
myapp_test.exs test_helper.exs
A template is essentially an arbitrary file hierarchy that will be copied verbatim at the destination path and postprocessed in some way.
When a template is instantiated, all occurrences of strings that look like
{{parameter_name}}
will be replaced by the values of corresponding
parameters. By default, mix newer
defines the following parameters:
-
APP_NAME
– it takes as its value the directory name passed on the command line -
MODULE_NAME
– a "camelized" version ofAPP_NAME
used to name user modules in the template -
MIX_VERSION
– full version (e.g.1.0.0
) of Mix (which is the same as Elixir version) with which the template is instantiated -
MIX_VERSION_SHORT
– shortened version (e.g.1.0
) recommended for use in Elixir version requirement inmix.exs
To add custom parameters or flags, a file named defs.exs
should be placed
under the special _template_config
directory inside the template. Certain
files in this directory will be evaluated during template instantiation and
the directory will be removed in the end.
An example defs.exs
file might look as follows:
flag :custom, :string
param :my_param, config[:APP_NAME]<>"tail"
The newly defined parameter can be used in any file as {{my_param}}
. The
custom flag can be passed on the command line as --custom value
or
--custom='longer string'
.
After defining custom flags and parameters, mix newer
will look for
_template_config/init.exs
script and execute it if present. The script can
contain any valid Elixir code. It will have two dicts available:
-
flags
will contain the values of custom flags passed by the user on the command line -
config
will contain all parameters and their values (whether builtin or specified on the command line)
Additionally, the init script will also have select
macro autoimported which
can be used to selectively choose one of special template files described
below.
Files with names ending in ._template
won't be copied into the destination
directory unless picked explicitly. To pick such a file, the select
macro
should be used. For instance, if there are two such files under the lib/
directory named option_1.ex._template
and option_2.ex._template
, one of
them can be picked in init.exs
as follows:
# Decide which file to pick based on the value of our a custom flag
if flags[:custom] == "second" do
select "lib/option_2.ex", rename: "{{APP_NAME}}.ex"
else
select "lib/option_1.ex", rename: "{{APP_NAME}}.ex"
end
The picked file will be kept under the lib/
directory with a new name, and
the other file will be removed before the template instantiation completes.
If rename
option isn't set, default name will be kept.
See the following examples for reference:
This software is licensed under the MIT license.