.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Dist::Zilla::Plugin::Bootstrap::lib 3pm" .TH Dist::Zilla::Plugin::Bootstrap::lib 3pm "2022-06-13" "perl v5.34.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Dist::Zilla::Plugin::Bootstrap::lib \- A minimal boot\-strapping for Dist::Zilla Plug\-ins. .SH "VERSION" .IX Header "VERSION" version 1.001002 .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 4 \& [Bootstrap::lib] \& try_built = 1 ; try using an existing built distribution named Dist\-Name\-* \& fallback = 0 ; if try_built can\*(Aqt find a built distribution, or there\*(Aqs more than one, don\*(Aqt bootstrap \& ; using lib/ instead .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This module exists for loading either \f(CW\*(C`/lib\*(C'\fR or \f(CW\*(C`/Dist\-Name\-$VERSION/lib\*(C'\fR into your \f(CW@INC\fR early on. .PP This is mostly useful for writing \f(CW\*(C`Dist::Zilla\*(C'\fR plug-ins, so that you may build and release a plug-in using itself. .SH "USE CASES" .IX Header "USE CASES" .SS "Simple single-phase self-dependency" .IX Subsection "Simple single-phase self-dependency" This module really is only useful in the case where you need to use something like .PP .Vb 1 \& dzil \-Ilib .Ve .PP For \fIevery\fR call to \f(CW\*(C`Dist::Zilla\*(C'\fR, and this is mainly a convenience. .PP For that .PP .Vb 1 \& [Bootstrap::lib] .Ve .PP on its own will do the right thing. .SS "Installed-Only self-dependency" .IX Subsection "Installed-Only self-dependency" The other useful case is when you would normally do .PP .Vb 2 \& 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 .Ve .PP For that .PP .Vb 3 \& [Bootstap::lib] \& try_built = 1 \& fallback = 0 .Ve .PP Will do what you want. .PP .Vb 2 \& dzil build # pass1 \-> creates Foo\-1.234 without bootstrapping \& dzil build # pass2 \-> creates Foo\-1.234 boot\-strapped from the previous build .Ve .SS "2\-step self-dependency" .IX Subsection "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.: \f(CW$VERSION\fR being \f(CW\*(C`undef\*(C'\fR in code that is run during release is \*(L"bad\*(R" ) .PP .Vb 3 \& [Bootstrap::lib] \& try_built = 1 \& fallback = 1 .Ve .PP Then .PP .Vb 2 \& dzil build # pass1 \-> creates Foo\-1.234 from bootstrapped $root/lib \& dzil build # pass2 \-> creates Foo\-1.234 from bootstrapped $root/Foo\-1.234 .Ve .SH "PRECAUTIONS" .IX Header "PRECAUTIONS" .SS "\s-1DO NOT\s0" .IX Subsection "DO NOT" \&\fB\s-1DO NOT\s0\fR use this library from inside a bundle. It will not likely work as expected, and you \fB\s-1DO NOT\s0\fR want to bootstrap everything in all cases. .SS "\s-1NO VERSION\s0" .IX Subsection "NO VERSION" On its own, .PP .Vb 1 \& [Bootstrap::lib] .Ve .PP At present, using this module in conjunction with a module with no explicitly defined version in the source will result in the \fIexecuted\fR instance of that plug-in \fIalso\fR having \fB\s-1NO VERSION\s0\fR. .PP If this is a problem for you, then its suggested you try either variation of using .PP .Vb 3 \& [Bootstrap::lib] \& try_built = 1 \& ; no_fallback = 1 # .Ve .SS "\s-1SUCKS AT GUESSING\s0" .IX Subsection "SUCKS AT GUESSING" The core mechanism behind \f(CW\*(C`try_built\*(C'\fR relies on looking in your project directory for a previous build directory of some kind. .PP And there's no way for it to presently pick a \*(L"best\*(R" version when there are more than one, or magically provide a better solution if there are \*(L"zero\*(R" versions readily available. .PP This is mostly because there is no way to determine the \*(L"current\*(R" 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. .PP Even as it is, us using \f(CW\*(C`zilla\->name\*(C'\fR means that if your dist relies on some process to divine its name, the module that does this must: .IP "\(bu" 4 be loaded and declared prior to \f(CW\*(C`Bootstrap::lib\*(C'\fR in the \f(CW\*(C`dist.ini\*(C'\fR .IP "\(bu" 4 not itself be the module you are presently developing/bootstrapping .PP The only way of working around that I can envision is adding parameters to \f(CW\*(C`Bootstrap::lib\*(C'\fR 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 \f(CW\*(C`dist.ini\*(C'\fR to start with. .SS "\s-1STILL NOT REALLY A PLUGIN\s0" .IX Subsection "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 \f(CW\*(C`::Bootstrap\*(C'\fR phase, which is more or less a different name and implementation of \f(CW\*(C`BUILD\*(C'\fR, in that \f(CW\*(C`bootstrap\*(C'\fR is invoked after \f(CW\*(C`plugin_from_config\*(C'\fR is called ( where \f(CW\*(C`new\*(C'\fR is called ), which occurs somewhere in the middle of \&\f(CW\*(C`register_component\*(C'\fR .PP This module also appears on the plugin stash, and responds naturally to \f(CW\*(C`metaconfig\*(C'\fR requests. .SH "AUTHOR" .IX Header "AUTHOR" Kent Fredric .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2017 by Kent Fredric . .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.