.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43) .\" .\" 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 .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "Dist::Zilla::Plugin::Run 3pm" .TH Dist::Zilla::Plugin::Run 3pm "2023-10-27" "perl v5.36.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::Run \- Run external commands and code at specific phases of Dist::Zilla .SH "VERSION" .IX Header "VERSION" version 0.049 .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 4 \& [Run::AfterBuild] \& run = script/do_this.pl \-\-dir %d \-\-version %v \& run = script/do_that.pl \& eval = unlink scratch.dat \& \& [Run::BeforeBuild] \& fatal_errors = 0 \& run = script/do_this.pl \-\-version %v \& run = script/do_that_crashy_thing.pl \& eval = if ($ENV{SOMETHING}) { \& eval = $_[0]\->log(\*(Aqsome message\*(Aq) \& eval = } \& \& [Run::BeforeArchive] \& run = script/myapp_before1.pl %d %v \& run = script/myapp_before2.pl %n %v \& run_no_trial = script/no_execution_on_trial.pl %n %v \& \& [Run::BeforeRelease] \& run = script/myapp_before1.pl %a \& run = script/myapp_before2.pl %n %v \& run_no_trial = script/no_execution_on_trial.pl %n %v \& \& [Run::Release] \& run = script/myapp_deploy1.pl %a \& run = deployer.pl \-\-dir %d \-\-tgz %a \-\-name %n \-\-version %v \& run_no_trial = script/no_execution_on_trial.pl \-\-dir %d \-\-tgz %a \-\-name %n \-\-version %v \& \& [Run::AfterRelease] \& run = script/myapp_after.pl \-\-archive %a \-\-dir %d \-\-version %v \& ; %p can be used as the path separator if you have contributors on a different OS \& run = script%pmyapp_after.pl \-\-archive %a \-\-dir %d \-\-version %v \& \& [Run::AfterRelease / MyAppAfter] \& run = script/myapp_after.pl \-\-archive %a \-\-dir %d \-\-version %v \& \& [Run::Test] \& run = script/tester.pl \-\-name %n \-\-version %v some_file.ext \& run_if_release = ./Build install \& run_if_release = make install \& \& [Run::AfterMint] \& run = some command %d \& eval = unlink scratch.dat \& eval = print "I just minted %n for you. Have a nice day!\en"; .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" Run arbitrary commands and code at various Dist::Zilla phases. .SH "PARAMETERS" .IX Header "PARAMETERS" .SS "run" .IX Subsection "run" Run the specific command at the specific Dist::Zilla phase given by the plugin. For example, \f(CW\*(C`[Run::Release]\*(C'\fR runs during the release phase. .SS "run_if_trial" .IX Subsection "run_if_trial" Only run the given command if this is a \fItrial\fR build or release. .SS "run_no_trial" .IX Subsection "run_no_trial" Only run the given command if this isn't a \fItrial\fR build or release. .SS "run_if_release" .IX Subsection "run_if_release" Only run the given command if this is a release. .SS "run_no_release" .IX Subsection "run_no_release" Only run a given command if this isn't a release. .SS "eval" .IX Subsection "eval" Treats the input as a list of lines of Perl code; the code is evaluated at the specific Dist::Zilla phase given by the plugin. The code is executed in its own \f(CW\*(C`eval\*(C'\fR scope, within a subroutine body; \f(CW@_\fR contains the instance of the plugin executing the code. (Remember that \f(CW\*(C`shift\*(C'\fR in an \f(CW\*(C`eval\*(C'\fR actually operates on \f(CW@ARGV\fR, not \f(CW@_\fR, so to access the plugin instance, use \&\f(CW$_[0]\fR.) .SS "censor_commands" .IX Subsection "censor_commands" Normally, \f(CW\*(C`run*\*(C'\fR commands are included in distribution metadata when used with the [MetaConfig] plugin. To bypass this, set \f(CW\*(C`censor_commands = 1\*(C'\fR. Additionally, this command is set to true automatically when a \s-1URL\s0 with embedded password is present. .PP Defaults to false. .SS "fatal_errors" .IX Subsection "fatal_errors" When true, if the \f(CW\*(C`run\*(C'\fR command returns a non-zero exit status or the \f(CW\*(C`eval\*(C'\fR command dies, the build will fail. Defaults to true. .SS "quiet" .IX Subsection "quiet" When true, diagnostic messages are not printed (except in \f(CW\*(C`\-\-verbose\*(C'\fR mode). .PP Defaults to false. .SH "EXECUTION ORDER" .IX Header "EXECUTION ORDER" All commands for a given option name are executed together, in the order in which they are documented above. Within commands of the same option name, order is preserved (from the order provided in \fIdist.ini\fR). .SH "ENVIRONMENT" .IX Header "ENVIRONMENT" For executed commands, \*(L"open3\*(R" in IPC::Open3 is used \*(-- there is no subshell. Consequently environment variables may or may not be available depending on the individual architecture used. For Perl strings that are evaluated, they are done in the dzil process, so all current global variables and other state is available for use. .PP The current working directory is undefined, and may vary depending on the version of Dist::Zilla being used. If the state of the filesystem is important, explicitly change directories first, or base your relative paths off of the build root (available as \f(CW%d\fR, see below). .SH "CONVERSIONS" .IX Header "CONVERSIONS" The following conversions/format specifiers are defined for passing as arguments to the specified commands and eval strings (though not all values are available at all phases). .IP "\(bu" 4 \&\f(CW%a\fR the archive of the release (only available to all \f(CW*Release\fR phases), as documented to be passed to BeforeRelease, Release, AfterRelease plugins .IP "\(bu" 4 \&\f(CW%o\fR the directory in which the distribution source originated .IP "\(bu" 4 \&\f(CW%d\fR the directory in which the distribution was built (or minted) (not available in \f(CW\*(C`BeforeBuild\*(C'\fR) .IP "\(bu" 4 \&\f(CW%n\fR the distribution name .IP "\(bu" 4 \&\f(CW%p\fR path separator ('/' on Unix, '\e\e' on Win32... useful for cross-platform \fIdist.ini\fR files) .IP "\(bu" 4 \&\f(CW%v\fR the distribution version, if available (depending on the phase, the \f(CW\*(C`VersionProvider\*(C'\fR plugin may not be able to return a version) .IP "\(bu" 4 \&\f(CW%t\fR \f(CW\*(C`\-TRIAL\*(C'\fR if the release is a trial release, otherwise the empty string .IP "\(bu" 4 \&\f(CW%x\fR full path to the current perl interpreter (like \f(CW$^X\fR but from Config) .PP Additionally \f(CW%s\fR is retained for backward compatibility (for those plugins that existed when it was documented). Each occurrence is replaced by a different value (like the regular \f(CW\*(C`sprintf\*(C'\fR function). Individual plugins define their own values for the positional replacement of \f(CW%s\fR. .PP \&\fB\s-1NOTE\s0\fR: when using filenames (e.g. \f(CW%d\fR, \f(CW%n\fR and \f(CW%x\fR), be mindful that these paths could contain special characters or whitespace, so if they are to be used in a shell command, take care to use quotes or escapes! .SH "DANGER! SECURITY RISK!" .IX Header "DANGER! SECURITY RISK!" The very nature of these plugins is to execute code. Be mindful that your code may run on someone else's machine and don't be a jerk! .SH "SUPPORT" .IX Header "SUPPORT" Bugs may be submitted through the \s-1RT\s0 bug tracker (or bug\-Dist\-Zilla\-Plugin\-Run@rt.cpan.org ). .PP There is also a mailing list available for users of this distribution, at . .PP There is also an irc channel available for users of this distribution, at \&\f(CW\*(C`#distzilla\*(C'\fR on \f(CW\*(C`irc.perl.org\*(C'\fR . .SH "AUTHOR" .IX Header "AUTHOR" Torsten Raudssus .SH "CONTRIBUTORS" .IX Header "CONTRIBUTORS" .IP "\(bu" 4 Karen Etheridge .IP "\(bu" 4 Randy Stauner .IP "\(bu" 4 Nickolay Platonov .IP "\(bu" 4 Olivier Mengue\*' .IP "\(bu" 4 Al Newkirk .IP "\(bu" 4 David Golden .IP "\(bu" 4 Graham Ollis .IP "\(bu" 4 Tatsuhiko Miyagawa .IP "\(bu" 4 Thomas Sibley .SH "COPYRIGHT AND LICENCE" .IX Header "COPYRIGHT AND LICENCE" This software is copyright (c) 2010 by Raudssus Social Software . .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.