NAME
    Dist::Zilla::Plugin::Bootstrap::lib - A minimal boot-strapping for
    Dist::Zilla Plug-ins.

VERSION
    version 0.03000100

SYNOPSIS
        [Bootstrap::lib]
        try_built   = 1  ; try using an existing built distribution named Dist-Name-*
        no_fallback = 1  ; if try_built can't find a built distribution, or there's more than one, don't bootstrap
                         ; using lib/ instead

DESCRIPTION
    This module does the very simple task of injecting the distributions
    'lib' directory into @INC at the point of its inclusion, so that you can
    use plug-ins you're writing for "Dist::Zilla", to release the plug-in
    itself.

METHODS
  "log_debug"
    1;
  "plugin_name"
    'Bootstrap::lib'
  "new"
        my $conf = __PACKAGE__->new({ config => \%arbitrary_hash});

  "does"
    Lazily invokes Role::Tiny::does_role on demand.

  "meta"
    Lazily creates a meta object using Moo

  "dump_config"
    Dumps the configuration of this plugin to "dzil"

  "register_component"
    This is where all the real work happens.

USE CASES
  Simple single-phase self-dependency
    This module really is only useful in the case where you need to use
    something like

        dzil -Ilib

    For *every* call to "Dist::Zilla", and this is mainly a convenience.

    For that

        [Bootstrap::lib]

    on its own will do the right thing.

  Installed-Only self-dependency
    The other useful case is when you would normally do

        dzil build                 # pass 1 that generates Foo-1.234 with a pre-installed Foo-1.233
        dzil -IFoo-1.234/lib build # pass 2 that generates Foo-1.234 with Foo-1.234

    For that

        [Bootstap::lib]
        try_built   = 1
        no_fallback = 1

    Will do what you want.

        dzil build   # pass1 -> creates Foo-1.234 without bootstrapping
        dzil build   # pass2 -> creates Foo-1.234 boot-strapped from the previous build

  2-step self-dependency
    There's a 3rd useful case which is a hybrid of the 2, where you /can/
    build from your own sources without needing a pre-installed version,
    just you don't want that for release code ( e.g.: $VERSION being "undef"
    in code that is run during release is "bad" )

        [Bootstrap::lib]
        try_built = 1
        fallback  = 1

    Then

        dzil build  # pass1 -> creates Foo-1.234 from bootstrapped $root/lib
        dzil build  # pass2 -> creates Foo-1.234 from bootstrapped $root/Foo-1.234

PRECAUTIONS
  DO NOT
    DO NOT use this library from inside a bundle. It will not likely work as
    expected, and you DO NOT want to bootstrap everything in all cases.

  NO VERSION
    On its own,

        [Bootstrap::lib]

    At present, using this module in conjunction with a module with no
    explicitly defined version in the source will result in the *executed*
    instance of that plug-in *also* having NO VERSION.

    If this is a problem for you, then its suggested you try either
    variation of using

        [Bootstrap::lib]
        try_built = 1
        ; no_fallback = 1   #

  SUCKS AT GUESSING
    The core mechanism behind "try_built" relies on looking in your project
    directory for a previous build directory of some kind.

    And there's no way for it to presently pick a "best" version when there
    are more than one, or magically provide a better solution if there are
    "zero" versions readily available.

    This is mostly because there is no way to determine the "current"
    version we are building for, because the point in the execution cycle is
    so early, no version plugins are likely to be even instantiated yet, and
    some version plugins are dependent on incredibly complex precursors (
    like git ), so by even trying to garner the version we're currently
    building, we could be prematurely cutting off a vast majority of modules
    from even being able to bootstrap.

    Even as it is, us using "zilla->name" means that if your dist relies on
    some process to divine its name, the module that does this must

    *   be loaded and declared prior to "Bootstrap::lib" in the "dist.ini"

    *   not itself be the module you are presently developing/bootstrapping

    The only way of working around that I can envision is adding parameters
    to "Bootstrap::lib" to specify the dist name and version name... but if
    you're going to do that, you may as well stop using external plugins to
    discover that, and hard-code those values in "dist.ini" to start with.

  STILL NOT REALLY A PLUGIN
    Though the interface is getting more plugin-like every day, all of the
    behaviour is still implemented at construction time, practically as soon
    as the underlying Config::MVP engine has parsed it from the
    configuration.

    As such, it is completely removed from the real plugin execution phases,
    and unlike real plugins which appear on the plugin stash, this module
    does not appear there.

  GOOD LUCK
    I wrote this plug-in, mostly because I was boiler-plating the code into
    every dist I had that needed it, and it became annoying, especially
    having to update the code across distributions to handle "Dist::Zilla"
    "API" changes.

AUTHOR
    Kent Fredric <kentnl@cpan.org>

COPYRIGHT AND LICENSE
    This software is copyright (c) 2013 by Kent Fredric <kentnl@cpan.org>.

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

