> dzil

Customizing the Minting Process

Dist::Zilla lets you create any number of "minting profiles" to create distributions with different default contents. You might have one for work and one for personal code; one for object-oriented code and one for functional code; or one for web applications and one for command-line applications, etc.

Preparation For the tasks below, you'll want to:

• install Dist::Zilla, version 4.101780 or later

• run dzil setup

The rest of this document assumes that you haven't already made a custom minting profile, meaning that you haven't got anything in ~/.dzil/profiles. If you have a default profile, just rename it if you want to follow the steps exactly as described below.

Create a default profile

Create a directory called ~/.dzil/profiles/default. This will hold your default minting profile, overriding the very simple default that ships with Dist::Zilla.

The first thing you want to do is change into that directory and create a profile.ini. That file picks and configures the plugins that will contribute to minting new distributions. For now, populate the file with the following content:

1:  2:  3:  4:  5:  6:  7:  8:

[TemplateModule/:DefaultModuleMaker] template = Module.pm [DistINI] append_file = plugins.ini [GatherDir::Template] root = skel

The profile.ini file defines two components for minting your new distribution. The first one, TemplateModule, is given a special name :DefaultModuleMaker, to tell Dist::Zilla that this component will be used for creating the new module file. The template parameter tells it a file to use, so create a Module.pm file (in the same directory as profile.ini) with the following content:

  use strict;
  use warnings;
  package {{$name}};

  1;

The second component in profile.ini is DistINI, which says to build a dist.ini file based on your initial configuration plus the contents of plugins.ini. That's where you'll put any special plugins you want.

We'll create a plugins.ini and put in our preferred default configuration, which might look like this:

1:  2:  3:

[@Basic] [NextRelease] [@Git]

The third component in our profile.ini was GatherDir::Template, which specifies a directory of templates that will also be created in your new distribution. We could put templates there that would be rendered into files in our new distribution.

Just create ~/.dzil/profiles/default/skel, change to that directory, and add normal Text::Template template files.

Instead of using this for a starter Changes file, though, we'll use the GenerateFile plugin, which lets us specify the file's content right in our profile.ini. We'll add this to the profile:

1:  2:  3:  4:  5:  6:

[GenerateFile / Generate-Changes ] filename = Changes is_template = 0 content = Revision history for {{$dist->name}} content = content = {{$NEXT}}

Change to your work directory and run dzil new My::Module. You should get a new distribution that is almost exactly like the original default included with Dist::Zilla, except that it has the addition of the plugins we wanted in our dist.ini, and there's a Changes file.

Now, all you have to do is customize the plugins.ini and Module.pm files in the minting profile to suit your own personal style.

Setting up an alternate minting profile

The easiest way to set up an alternate profile is to copy your default profile to a new directory. For example, if you wanted to set up a profile that provided a Moose-specific starter module, you could create a copy like this:

  $ cp -a ~/.dzil/profiles/default ~/.dzil/profiles/moose

Then, customize the ~/.dzil/profiles/moose/Module.pm file to load Moose and provide any boilerplate you like.

You can run dzil new with the -p flag to use the alternate profile:

  $ dzil new -p moose My::Moose::Module

Distifying Your Profile

Maybe you want to be able to install your minting profile along with your plugin bundle. Maybe, more usefully, you run a project (or a department) that needs to have consistent settings for all new dists. In these cases, putting a profile in your home directory isn't enough. You want something that can be shared across many users. This is easy: you can include your profile in a distribution for installation.

There are lots of ways to do this, and you can accomplish lots of interesting things with minting profiles, but the simplest way is very simple, and will work for just about everything.

First, make a new distribution, with a module in it named Dist::Zilla::MintingProfile::ProviderNameHere -- replacing ProviderNameHere with a name for your provider. A provider is a module that can provide minting profiles. Here, it's just there to get a File::ShareDir slot, so it doesn't need much code. This should do it:

1:  2:  3:  4:

package Dist::Zilla::MintingProfile::ProviderNameHere; use Moose; with 'Dist::Zilla::Role::MintingProfile::ShareDir';

The MintingProfile::ShareDir role means that the profile will try look in the module's ShareDir for the profile's profile.ini and other files. To get them into the ShareDir, you'll need to use ModuleShareDirs in your dist.ini:

1:  2:

[ModuleShareDirs] Dist::Zilla::MintingProfile::ProviderNameHere = profiles

This says "the files in my dist's ./profiles directory will get installed into the sharedir for this module." It's critical that you use ModuleShareDirs, and not just ShareDirs, here.

Notice that we called the directory profiles. That's because you can have many profiles for this one module. As with the profiles in your home directory, the default profile goes under default. Make the directory ./profiles/default in your distribution and put your profile.ini and other files in it. If you want to make other profiles, put them in other subdirectories. Now, when you install the minting profile distribution, you can use these profiles. Instead of -p, which gave an alternate profile name, use -P to give an alternate profile provider. For example, you could run:

  $ dzil new -P ProviderNameHere  New::Module

Or, to get a non-default profile from that provider:

  $ dzil new -P ProviderNameHere -p otherprofile New::Module