mobundle

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