Dist::Iller - A Dist::Zilla & Pod::Weaver preprocessor

Requires Perl 5.14+ coverage 84.4% Build status at Github


Version 0.1411, released 2020-01-01.


    # dzil new, but...
    $ dzil new -P DistIller::AMintingProvider My::Module

    $ cd My/Module

    # ...all other commands can be used via iller
    $ iller build


This is alpha software. Anything can change at any time.

It is mostly here to document how I build my distributions. It is perfectly fine to use dzil with a distribution built with Dist::Iller (after a fork, for example).


Dist::Iller is a Dist::Zilla and Pod::Weaver preprocessor. It comes with a command line tool (iller) which is a dzil wrapper: When run, it first generates files specified in iller.yaml in the current directory and then executes dzil automatically. (Since iller requires that an iller.yaml is present, iller new ... does not work.)

The doctype key in a document in iller.yaml matches a camelized class in the Dist::Iller::DocType namespace; so doctype: dist is parsed by Dist::Iller::DocType::Dist.


This is the general syntax of an iller.yaml file:

    # This specifies that this yaml document will generate dist.ini.
    doctype: dist

    # This generates the top part of C<dist.ini>. C<author> can be a list or string.
      name: My-Module
      author: Ex Ample <>
      license: Perl_5
      copyright_holder: Ex Ample
      copyright_year: 2015

    # It is possible to list all prereqs. The groups are specified in CPAN::Meta::Spec.
    # Minimum version numbers are optional.
          - perl: 5.010001
          - Moose

    # List all plugins under the 'plugins' key.
    # Each +plugin item is a Dist::Zilla> plugin.
    # All commands for Dist::Iller is prepended with a +.
      # Includes all plugins specified in Dist::Iller::Config::My::Config
      - +config: My::Config

      - +plugin: DistIller::MetaGeneratedBy
      - +plugin: AutoVersion
      - +plugin: GatherDir

      # 'dir' is a parameter for ShareDir
      - +plugin: ShareDir
        dir: myshare


    # Here starts the weaver.ini configuration.
    doctype: weaver

      # Same Dist::Iller::Config as in the 'dist' document
      - +config: My::Config

      # Use PluginBundles
      - +plugin: '@CorePrep'

      - +plugin: -SingleEncoding

      - +plugin: Name

      - +plugin: Version
        format: Version %v, released %{YYYY-MM-dd}d.

      - +plugin: prelude
        +base:  Region

      - +plugin: List
        +base: -Transformer
        +in: Elemental
        transformer: List


    # Here starts the .gitignore configuration
    doctype: gitignore

      - /.build
      - /_build*
      - /Build
      - MYMETA.*
      - '!META.json'
      - /.prove
    # No configuration for .cpanfile, but by having a YAML document for it, it gets generated from
    # the prereqs listed in the 'dist' document
    doctype: cpanfile


PluginBundles for both Dist::Zilla and Pod::Weaver have a few downsides:

  • Mixes code and configuration.

  • Not straightforward to remove or replace specific plugins for a certain distribution

  • Difficult to insert a plugin before another plugin for a certain distribution.

  • PluginBundles can change after a distribution has been released.

  • Difficult for others to understand/know which plugins actually were in effect when the distribution was built.

Dist::Iller tries to solve this:

  • Dist::Iller configs (similar to PluginBundles) has their own iller.yaml (normally in share/) where plugins are specified. See tests and Dist::Iller::Config::Author::CSSON.

  • Since dist.ini and weaver.ini are generated each time iller is run, the plugins listed in them are those that were used to build the distribution.

  • Remove a plugin:

      - +remove_plugin: GatherDir
  • Insert a plugin:

      - +add_plugin: Git::GatherDir
        +before: AutoVersion
  • Replace a plugin:

      - +replace_plugin: ShareDir
        +with: ShareDir::Tarball
  • Set more attributes for an already included plugin:

      - +extend_plugin: Git::GatherDir
          - examples/.*\.html





Erik Carlsson <>


This software is copyright (c) 2021 by Erik Carlsson.

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