SYNOPSIS

    In dist.ini:

     name=Perinci-CmdLine-Any-Bundled
     version=0.01
    
     [Prereqs]
     Perinci::CmdLine::Any=0
    
     [PERLANCAR::AddDeps]
     include_author = PERLANCAR

DESCRIPTION

    WARNING: EXPERIMENTAL

    This plugin will add module files from dependencies into your dist
    during building. When done carefully, can reduce the number of dists
    that users need to install because they are already included in your
    dists.

 How it works

    1. Perform "lcpan deps -R" against the "runtime requires" dependencies
    of your dist. This basically queries your local CPAN index and ask for
    the recursive dependencies of the modules. You can filter this using
    include_author to include only dependencies written by a certain author
    (for example, yourself). The result is a list of modules to add into
    dist (#1a) and a list of modules to stay as deps (#1b).

    2. Perform "lcpan mods-from-same-dist" for all modules found in #1a.
    The result is all modules from all dependency distributions.

    3. Search all the module files found in #2 in your local installation
    and include them to Dist::Zilla for building. Some minor modifications
    will be done first:

      * If the POD indicates which dist the module is in, will replace it
      with our dist. For example if there is a VERSION section with this
      content:

       This document describes version 0.10 of Perinci::CmdLine::Any (from Perl
       distribution Perinci-CmdLine-Any), released on 2015-04-12.

      then the text will be replaced with:

       This document describes version 0.10 of Perinci::CmdLine::Any (from Perl
       distribution Perinci-CmdLine-Any-Bundled version 0.01), released on 2015-04-12.

    4. Add all files in #3 into no_index metadata, so they don't clash with
    the original dists.

    5. Add modules in #1b as dependencies.

 Caveats

      * "lcpan" is used to list dependencies and contents of dists. You
      should have "lcpan" installed and your local CPAN fairly recent (keep
      it up-to-date with "lcpan update").

      * Only modules from each dependency distribution are included. This
      means other stuffs are not included: scripts/binaries, shared files,
      PODs. This is because PAUSE currently only index packages (~
      modules). We have .packlist though, and can use it in the future when
      needed.

      * Your bundle dist (the one you're building which include the deps)
      should be built with a minimal set of Dist::Zilla plugins. It should
      not do POD weaving, or change/fill version numbers (e.g. OurVersion
      which looks for # VERSION and change it), etc. We want the included
      dependency module files to be as pristine as possible.

      * Currently all the dependency dists must be installed on your local
      Perl installation. (This is purely out of my coding laziness though.
      It could/should be extracted from the release file in local CPAN
      index though.)

SEE ALSO

    lcpan