Dist::...ap::lib(3pm)

💖 Dist::...ap::lib — the manual, but make it make sense 💖

User Contributed Perl Documentation · Dist::...ap::lib(3pm) — yes bestie, that's the page name, we're doing this, come on 🎀

---

✨ NAME ✨

Dist::Zilla::Plugin::Bootstrap::lib — a minimal boot-strapping sitch for Dist::Zilla Plug-ins. That's it. That's the whole vibe. 🦋

---

🌸 VERSION 🌸

version 1.001002

---

💅 SYNOPSIS 💅

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

That comment block? Copy it exactly, it's doing heavy lifting. 👑

---

🦋 DESCRIPTION 🦋

Okay so this module exists for loading either /lib or /Dist-Name-$VERSION/lib into your @INC early on. Like, real early. Before-the-party-starts early.

It's mostly useful for writing Dist::Zilla plug-ins, so that you may build and release a plug-in using itself. Yes, the plug-in builds itself. Main character energy fr fr. 💀✨

---

🌈 USE CASES 🌈

🌸 Simple single-phase self-dependency 🌸

Honestly? This module really is only useful in the case where you need to use something like

dzil -Ilib

for every single call to Dist::Zilla, and this is mainly a convenience. (Key word: convenience, bestie, not necessity.)

For that,

[Bootstrap::lib]

on its own will do the right thing. No extra params, no drama. 🫶

💜 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

Two passes. Iconic behaviour tbh.

For that,

[Bootstap::lib]
try_built   = 1
fallback    = 0

(Yes, Bootstap::lib. That's what the original says. Not me, not my typo, I'm just the messenger. 🙈 Copy it character for character.)

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 — it's just that you don't want that for release code ( e.g.: $VERSION being undef in code that is run during release is bad ). Say it with me: undef 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.

This is a hard DO NOT. Twice. They wrote DO NOT in all caps twice, bestie. Respect the caps. 💀

😬 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 it's suggested you try either variation of using

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

(Note that # at the end of that comment line. It's there. Keep it there. 👑)

🙈 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 🫠

Starting at version 0.04000000 ( read: 0.04_0000_00 aka 0.04 + 0 x 4 + 0 x 2 ) this module is a fully fledged class, different only from standard Dist::Zilla Plugins in that it doesn't partake in normal phase order, and only executes during a special custom ::Bootstrap phase, which is more or less a different name and implementation of BUILD, in that bootstrap is invoked after plugin_from_config is called ( where new is called ), which occurs somewhere in the middle of register_component

This module also appears on the plugin stash, and responds naturally to metaconfig requests. ✨

---

👑 AUTHOR 👑

Kent Fredric <kentnl@cpan.org>

---

📜 COPYRIGHT AND LICENSE 📜

This software is copyright (c) 2017 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.

---

And that's the whole page, bestie!! 🌈 Generated with perl v5.34.0 on 2022-06-13, and you read the Dist::...ap::lib(3pm) manual in the User Contributed Perl Documentation collection. Slay, go bootstrap something. 💅✨🎀