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

VERSION
    Version 0.0001, released 2015-11-24.

SYNOPSIS
        $ iller new -P DistIller::AMintingProvider My::Module

        $ cd My/Module

        $ iller build

STATUS
    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 "Dist::Iller" built distribution
    (after a fork, for example).

DESCRIPTION
    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 "dist.ini" and/or "weaver.ini" from "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.)

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

        ---
        # This specifies that this yaml document will generate C<dist.ini>.
        doctype: dist

        # This generates the top part of C<dist.ini>. C<author> can be a list or string.
        header:
          name: My-Module
          author: Ex Ample <ample@example.org>
          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.
        prereqs:
          runtime:
            requires:
              - 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 +.
        plugins:
          # 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 C<weaver.ini> configuration.
        doctype: weaver

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

          # Use PluginBundles, but they need ''.
          - +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

         [...]

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

    *   Mixes code and configuration.

    *   Not straightforward to remove specific plugins for a certain
        distribution

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

    *   Difficult for others to understand which plugins actually were in
        effect when building the distribution.

    *   PluginBundles can change after a distribution has been released.

    "Dist::Iller" tries to solve this:

    *   Dist::Iller configs (similar to PluginBundles) also has a separate
        "iller.yaml" (normally in "share/") for specifying which plugins it
        includes. See tests and Dist::Iller::Config::Author::CSSON).

    *   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
            exclude_match:
              - examples/.*\.html

    *   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.

SEE ALSO
    *   Dist::Zilla

    *   Pod::Weaver

    *   Dist::Iller::Config::Author::CSSON

SOURCE
    <https://github.com/Csson/p5-Dist-Iller>

HOMEPAGE
    <https://metacpan.org/release/Dist-Iller>

AUTHOR
    Erik Carlsson <info@code301.com>

COPYRIGHT AND LICENSE
    This software is copyright (c) 2015 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.