/ 
Dist-Starter-v0.1.1
/ Dist::Starter

NAME

Dist::Starter - A command-line utility for rendering Perl project templates

DESCRIPTION

This is an alpha release. It is yet another starter kit implementation for a Perl project (distribution). It provides the diststarter script as a CLI. The script has a single mandatory argument that is the distname. The following table lists the options/flags of the script:

Option | Placeholder         | Default                       | Example
-------+---------------------+-------------------------------+--------------------
T:     | n/a                 | 'templates/perl-dist-eummcpf' |
V      | n/a                 | not set (version info)        |
h      | n/a                 | not set (usage info)          |
n      | n/a                 | not set                       |
o:     | n/a                 | current directory             |
A:     | abstract            | 'The great new Foo::Bar::Baz' |
G:     | git_base_url        | ''                            |
M:     | min_perl_version    | '5.010000'                    |
a:     | author.full_name    | from GECOS                    |
a:     | author.email        | from GECOS, fallback EMAIL    |
none   | initial_version     | 'v0.1.0'                      |
none   | license             | 'perl_5'                      |
n/a    | distname            |                               | Foo-Bar-Baz
n/a    | main_module         |                               | Foo::Bar::Baz
n/a    | main_module_file    |                               | lib/Foo/Bar/Baz.pm
n/a    | main_module_podfile |                               | lib/Foo/Bar/Baz.pod

The options that have a "Placeholder" value control the scaffolding. It is recommended to overwrite the "Default" of some of them in your run-control file. Example:

cat ${XDG_CONFIG_HOME}/diststarterrc
G https://github.com/sitcom
M 5.042003
a FROM_GIT

The -a option allows the special values FROM_GIT and FROM_ENV. If you use FROM_GIT, the author information is taken from the user.name and user.email git configuration attributes. If you use FROM_ENV, the author information is taken from the environment variables FULL_NAME and EMAIL. The default is to take the author information (at least its full name) from the GECOS string and if the email extraction isn't possible to fall back to the EMAIL environment variable. The author information has the format

Fred Flintstone <fred.flintstone@example.com> # with email
Fred Flintstone                               # without email

The value of the -T option specifies a directory that includes the template definition. The default refers to a directory shared by this distribution.

The value of the -o option specifies a directory where the generated project should be created. The default refers to the current directory. The special value TEM_DIR can be used to create the project in a temporary directory.

If you set the -n (dry-run) flag, the project will not be created but the so-called context will be printed to standard output. The context is a YAML document that contains the placeholder names and their values.

TODO

  • Explain how to create a new template definition

  • Reorganize documentation

  • Add script (-s) and share (-S) options

  • Provide options to customize the initial version and the license

SEE ALSO

AUTHOR

Sven Willenbuecher <sven.willenbuecher@gmx.de>

COPYRIGHT AND LICENSE

This software is copyright (c) 2026 by Sven Willenbuecher.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.