Dist::...tstrap(3pm)

💖 Dist::Zilla::Role::Bootstrap 💖

okay bestie, welcome to Dist::...tstrap(3pm) — yeah the title got truncated by the terminal, it's giving "my name is too long for this column width" energy 😭. It lives in the User Contributed Perl Documentation section, and it's a role for Dist::Zilla. Let's get into it 💅

---

✨ NAME ✨

Dist::Zilla::Role::Bootstrap — shared logic for bootstrap things. that's it. that's the whole name. short, sweet, iconic 🎀

---

🌸 VERSION 🌸

version 1.001004 🦋

---

🧚 SYNOPSIS 🧚

for the plugin authors out there (the builders, the icon queens 👑)

use Moose;
with 'Dist::Zilla::Role::Bootstrap';

sub bootstrap {
    my $bootstrap_root = $_[0]->_bootstrap_root;
    # Do the actual bootstrap work here
    $_[0]->_add_inc('./some/path/here');
}

for the plugin users (the ones just vibing in dist.ini 💜)

[Some::Plugin::Name]
try_built = 0 ; # use / as the root to bootstrap
try_built = 1 ; # try to use /Dist-Name-.*/ instead of /

fallback  = 0 ; # don't bootstrap at all if /Dist-Name-.*/ matches != 1 things
fallback  = 1 ; # fallback to / if /Dist-Name-.*/ matches != 1 things

---

🫶 DESCRIPTION 🫶

So this module is a role, right? And its whole personality is being consumed by plugins that wanna do some very early bootstrap operation. Like, so early. Before everyone else shows up to the party. 🎉

And why do we care? Because that bootstrap can affect the loading environment of successive plugins — especially the ones that might wanna build with themselves (main character energy tbh). Either by consuming the source tree itself, or by consuming a previous built iteration. no cap.

The implementation is lowkey simple, here's the whole recipe:

1. with this role in your plugin

with 'Dist::Zilla::Role::Bootstrap'

2. Implement the bootstrap sub.

sub bootstrap {
  my ( $self ) = @_;
}

3. Optional: fetch the discovered bootstrap root via:

$self->_bootstrap_root

4. Optional: load some path into @INC via:

$self->_add_inc($path)

that's the whole thing bestie, go slay ✨

---

🔥 REQUIRED METHODS 🔥

bootstrap

Any user specified bootstrap method will be invoked during plugin_from_config. 📣

This is AFTER ->new, AFTER ->BUILD, and AFTER dzil's internal plugin_from_config steps. (yeah it's a whole queue, everything has its moment 💅)

This occurs within the register_component phase of the plug-in loading and configuration.

This also occurs BEFORE Dist::Zilla attaches the plug-in into the plug-in stash. so like, it's early early. ⏰

---

💀 ATTRIBUTES 💀

distname

The name of the distribution. 📦

This value is vivified by asking zilla->name.

Usually this value is populated by dist.ini in the property name.

However, occasionally, this value is discovered by a plugin. 🙈

In such a case, that plugin cannot be bootstrapped, because that plugin MUST be loaded prior to bootstrap. (chicken-and-egg but make it Perl 😭)

try_built

This attribute controls how the consuming plugin behaves.

• false (default) : bootstrapping is only done to PROJECTROOT/lib
• true : bootstrap attempts to try PROJECTROOT/<distname>-<version>/lib

fallback

This attribute is for use in conjunction with try_built. 🤝

• false : When PROJECTROOT/<distname>-<version> does not exist, don't perform any bootstrapping
• true (default) : When PROJECTROOT/<distname>-<version> does not exist, bootstrap to PROJECTROOT/lib

try_built_method

This attribute controls how try_built behaves when multiple directories exist that match PROJECTROOT/<distname>-.*. (multiple candidates?? it's giving drama 🍿)

Two valid options at this time:

• mtime (default) : Pick the directory with the most recent mtime
• parseversion : Attempt to parse versions on all candidate directories and use the one with the largest version.

Prior to 0.2.0 this property did not exist, and default behavior was to assume 0 Candidates and 2 or more Candidates were the same problem. 💀

---

👑 AUTHOR 👑

Kent Fredric <kentnl@cpan.org> 🫡

---

🌈 COPYRIGHT AND LICENSE 🌈

This software is copyright (c) 2017 by Kent Fredric <kentfredric@gmail.com>.

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

---

and that's a wrap, bestie! this page was rendered by perl v5.34.0 on 2022-06-13, filed under Dist::...tstrap(3pm) 💖 go forth and bootstrap responsibly, ily, bye ✨🎀🦋