lib/App/MoBundle.pod

   1 =pod
   2
   3 =encoding UTF-8
   4
   5 =head1 NAME
   6
   7 App::MoBundle - workhorse for mobundle
   8
   9 =head1 SYNOPSIS
  10
  11    # the one I always look for
  12    shell$ mobundle -LPo bundled.pl -m Mod::One -m Mod::Two script.pl
  13
  14    # other useful examples
  15    shell$ mobundle -m Template::Perlish yourscript.pl
  16
  17    shell$ mobundle -m Template::Perlish --head '#!/path/to/perl' script.pl
  18
  19    shell$ mobundle -m Acme::Laugh --head-from-paragraph laugh.pl
  20
  21    # This lists all the modules that mobundle would include with
  22    # --autoscan|--scan|-a. Save it, trim it and you're done!
  23    shell$ mobundle --autoscan-list laugh.pl
  24
  25    # If you want to bundle some module that is local to your project
  26    shell$ mobundle -I ./lib -m My::Module ./bin/script.pl
  27
  28    # If you have a recently-bundled file you can easily extract modules
  29    shell% mobundle -u bundled-program.pl -o mylib
  30
  31 =head1 DESCRIPTION
  32
  33 FIXME to adapt for module
  34
  35 C<mobundle> lets you bundle Perl modules inside your Perl script, in order
  36 to ship a single script instead of N separate files.
  37
  38 The underlying logic is simple: all modules are included in the generated
  39 script, and the module loading mechanism is tweaked in order to let you
  40 load the bundled modules. See the documentation for L<perlfunc/require>
  41 to understand how.
  42
  43 The generated script will be compound of three main parts: a C<head>,
  44 a section with the bundled modules and the logic to load them, and
  45 a C<body>. Briefly speaking:
  46
  47 =over
  48
  49 =item B<head>
  50
  51 this is where you should put your shabang and the C<use>s that you would
  52 like to happen before the module loading mechanism is tweaked.
  53
  54 The C<head> is guaranteed to start at the very first octet in the result,
  55 so you can put a shabang.
  56
  57 =item B<modules>
  58
  59 this part is generated automatically based on your instructions about which
  60 modules should be bundled.
  61
  62 =item B<body>
  63
  64 this is the body of your script, i.e. what your script is supposed to do.
  65 It will likely contain either C<use>s or C<require>s that need the modules
  66 that are bundled in the C<modules> section.
  67
  68 =back
  69
  70 If you have a bundled script, apart from doing it yourself you can also
  71 unbundle it, see C<< --unbundle | -u >> below.
  72
  73 =head2 Why Another? Use PAR!
  74
  75 L<PAR> is fantastic: lets you bundle all the needed components of your
  76 application inside a single executable, and ship it. But... there's a
  77 niche that it's not able to cover, at least looking at the documentation.
  78
  79 In particular, there seem to be two different operation modes, depending
  80 on your needs
  81
  82 =over
  83
  84 =item *
  85
  86 either you're willing to bundle the interpreter as well, in which case
  87 L<PAR> (or, better, L<pp>) will generate a super-executable bundling all
  88 necessary stuff
  89
  90 =item *
  91
  92 or you have to be sure that L<PAR> is installed in the target directory.
  93
  94 =back
  95
  96 My need was somewhere in between: on the one side I wasn't willing to bundle
  97 the interpreter, on the other I couldn't ensure that L<PAR> was available.
  98
  99 In particular, this kind of need arises every time that my programs only need
 100 Pure-Perl modules, that do not need any platform-specific installation
 101 process. In this case, bundling the interpreter means restricting the
 102 applicability to one (or more, at some cost) platform only; the other way
 103 is simply not acceptable in some environments.
 104
 105
 106 =head1 OPTIONS
 107
 108 =over
 109
 110 =item --add-modules-list | -L
 111
 112 adds a list of the modules that have been embedded in package variable
 113 C<@__MOBUNDLE_MODULES__>. This list can then be read, e.g.:
 114
 115    {
 116       our @__MOBUNDLE_MODULES__;
 117       print "have module <$_>\n" for @__MOBUNDLE_MODULES__;
 118    }
 119
 120 =item --autoscan | -scan | -a
 121
 122 tries to use L<Module::ScanDeps> to find non-core modules that might be
 123 needed. Note that this is not PAR, so you should be careful of what is
 124 taken in.
 125
 126 For example, L<Archive::Tar> can operate without L<IO::Zlib>, but
 127 L<Module::ScanDeps> will bring it in together with a lot of stuff.
 128
 129 =item --autoscan-list | --scan-list | --modules-list | -l
 130
 131 print out the list of modules that would be included by L</--autoscan>.
 132
 133 =item --body | -b <body>
 134
 135 turn your one-liner in a self contained script! Just pass the C<body> of your
 136 script and you're done.
 137
 138 =item --body-from | -B <filename>
 139
 140 get the body of the target script from the given filename.
 141
 142 =item --head | -h <head>
 143
 144 the C<head> is the part that will be put at the very beginning of the
 145 resulting script. Can be useful to specify a shabang.
 146
 147 =item --head-from | -H <filename>
 148
 149 get the C<head> from the given filename. See L</head>.
 150
 151 =item --head-from-body | -S <n>
 152
 153 get the C<head> taking it from the first C<n> lines of the body. See
 154 L</head> and L</body>.
 155
 156 =item --head-from-paragraph | -P
 157
 158 get the C<head> from the very first paragraph in the C<body>. See
 159 L</head> and L</body>.
 160
 161 =item --help
 162
 163 print a somewhat more verbose help, showing usage, this description of
 164 the options and some examples from the synopsis.
 165
 166 =item --include | -I <dirname>
 167
 168 add C<dirname> to @INC, which is also the directory used to look for
 169 modules' sources.
 170
 171 =item --man
 172
 173 print out the full documentation for the script.
 174
 175 =item --module | -m <name>
 176
 177 include the given module in the final script. You can specify this option
 178 multiple times for multiple modules.
 179
 180 When used with L</--autoscan>, these modules are skipped during the scan.
 181
 182 =item --modules-from | -M <filename>
 183
 184 get a list of modules to bundle from the given filename.
 185
 186 =item --output | -o <filename>
 187
 188 set a filename for output, instead of standard output. When C<-> is given,
 189 standard output is assumed.
 190
 191 When used with C<< --unbundle | -u >>, it is the name of the base output
 192 directory where modules will be written.
 193
 194 =item --standard-head | -s
 195
 196 put a standard header at the beginning of the generated script, i.e.:
 197
 198    #!/usr/bin/env perl
 199
 200 =item --unbundle | -u
 201
 202 unbundle an already-bundled script. In this case, the C<--output|-o>
 203 option is considered a directory; if not specified, the C<lib> directory
 204 is used (and created if needed).
 205
 206 Unbundling assumes that the bundled script was produced with a fairly recent
 207 version of I<mobundle>; in particular, it is important that the
 208 C<__MOBUNDLE_INCLUSION__> comments are present.
 209
 210 =item --usage
 211
 212 print a concise usage line and exit. You can specify this option
 213 multiple times for multiple modules.
 214
 215 =item --version
 216
 217 print the version of the script.
 218
 219 =back
 220
 221 =head1 CONFIGURATION AND ENVIRONMENT
 222
 223 mobundle requires no configuration files or environment variables.
 224
 225 =head1 DEPENDENCIES
 226
 227 Non-core modules needed:
 228
 229 =over
 230
 231 =item B<< File::Slurp >>
 232
 233 =item B<< Template::Perlish >>
 234
 235 =item B<< Path::Class >>
 236
 237 =item B<< Module::ScanDeps >>
 238
 239 but only if you want to use the L</--autoscan> option.
 240
 241 =back
 242
 243 Did you say that I should I<bundle> them?!?
 244
 245 =head1 BUGS AND LIMITATIONS
 246
 247 No bugs have been reported.
 248
 249 Please report any bugs or feature requests through http://rt.cpan.org/
 250
 251 Undoubtfully there are many bugs, and more limitations.
 252
 253 =head1 AUTHOR
 254
 255 Flavio Poletti C<polettix@cpan.org>
 256
 257 =head1 COPYRIGHT AND LICENSE
 258
 259 Copyright (c) 2008-2011, 2023 by Flavio Poletti C<polettix@cpan.org>.
 260
 261 Up to version 0.1.1 this program was licensed under the terms of the
 262 Artistic License 2.0.
 263
 264 Since version 0.1.2 on, this program is licensed under the Apache License,
 265 Version 2.0 (the "License"); you may not use this file except in compliance
 266 with the License.  You may obtain a copy of the License at
 267
 268     http://www.apache.org/licenses/LICENSE-2.0
 269
 270 Unless required by applicable law or agreed to in writing, software
 271 distributed under the License is distributed on an "AS IS" BASIS,
 272 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 273 See the License for the specific language governing permissions and
 274 limitations under the License.
 275
 276 If this is a bundled version of the program, the following subsections
 277 apply to the embedded modules.
 278
 279 =head2 Copyright for C<File::Slurp>
 280
 281 Copyright (c) 2003 Uri Guttman. All rights reserved.
 282
 283 This program is free software; you can redistribute it and/or modify it
 284 under the same terms as Perl itself.
 285
 286 =head2 Copyright for C<Module::ScanDeps>
 287
 288 Copyright 2002-2008 by Audrey Tang <cpan@audreyt.org>; 2005-2010 by Steffen
 289 Mueller <smueller@cpan.org>.
 290
 291 This program is free software; you can redistribute it and/or modify it
 292 under the same terms as Perl itself.
 293
 294 See http://www.perl.com/perl/misc/Artistic.html
 295
 296 =head2 Copyright for C<Path::Class>
 297
 298 Copyright (c) Ken Williams. All rights reserved.
 299
 300 This library is free software; you can redistribute it and/or modify it
 301 under the same terms as Perl itself.
 302
 303 =head2 Copyright for C<Template::Perlish>
 304
 305 Copyright (c) 2008-2016 by Flavio Poletti polettix@cpan.org.
 306
 307 This module is free software. You can redistribute it and/or modify it under
 308 the terms of the Artistic License 2.0.
 309
 310 This program is distributed in the hope that it will be useful, but without
 311 any warranty; without even the implied warranty of merchantability or
 312 fitness for a particular purpose.
 313
 314 =cut