| … | |
… | |
| 20 | |
20 | |
| 21 | Typical Examples: |
21 | Typical Examples: |
| 22 | |
22 | |
| 23 | staticperl install # fetch, configure, build and install perl |
23 | staticperl install # fetch, configure, build and install perl |
| 24 | staticperl cpan # run interactive cpan shell |
24 | staticperl cpan # run interactive cpan shell |
| 25 | staticperl mkperl -M '"Config_heavy.pl"' # build a perl that supports -V |
25 | staticperl mkperl -MConfig_heavy.pl # build a perl that supports -V |
| 26 | staticperl mkperl -MAnyEvent::Impl::Perl -MAnyEvent::HTTPD -MURI -MURI::http |
26 | staticperl mkperl -MAnyEvent::Impl::Perl -MAnyEvent::HTTPD -MURI -MURI::http |
| 27 | # build a perl with the above modules linked in |
27 | # build a perl with the above modules linked in |
| 28 | staticperl mkapp myapp --boot mainprog mymodules |
28 | staticperl mkapp myapp --boot mainprog mymodules |
| 29 | # build a binary "myapp" from mainprog and mymodules |
29 | # build a binary "myapp" from mainprog and mymodules |
| 30 | |
30 | |
| … | |
… | |
| 252 | |
252 | |
| 253 | # first make sure we have perl and the required modules |
253 | # first make sure we have perl and the required modules |
| 254 | staticperl instcpan AnyEvent::HTTPD |
254 | staticperl instcpan AnyEvent::HTTPD |
| 255 | |
255 | |
| 256 | # now build the perl |
256 | # now build the perl |
| 257 | staticperl mkperl -M'"Config_heavy.pl"' -MAnyEvent::Impl::Perl \ |
257 | staticperl mkperl -MConfig_heavy.pl -MAnyEvent::Impl::Perl \ |
| 258 | -MAnyEvent::HTTPD -MURI::http \ |
258 | -MAnyEvent::HTTPD -MURI::http \ |
| 259 | --add 'eg/httpd httpd.pm' |
259 | --add 'eg/httpd httpd.pm' |
| 260 | |
260 | |
| 261 | # finally, invoke it |
261 | # finally, invoke it |
| 262 | ./perl -Mhttpd |
262 | ./perl -Mhttpd |
| … | |
… | |
| 381 | |
381 | |
| 382 | =over 4 |
382 | =over 4 |
| 383 | |
383 | |
| 384 | =item C<--use> F<module> | C<-M>F<module> |
384 | =item C<--use> F<module> | C<-M>F<module> |
| 385 | |
385 | |
| 386 | Include the named module and trace direct dependencies. This is done by |
386 | Include the named module or perl library and trace direct |
| 387 | C<use>'ing the module from a fresh package in a subprocess and tracing |
387 | dependencies. This is done by loading the module in a subprocess and |
| 388 | which other modules and files it actually loads. |
388 | tracing which other modules and files it actually loads. |
| 389 | |
389 | |
| 390 | Example: include AnyEvent and AnyEvent::Impl::Perl. |
390 | Example: include AnyEvent and AnyEvent::Impl::Perl. |
| 391 | |
391 | |
| 392 | staticperl mkbundle --use AnyEvent --use AnyEvent::Impl::Perl |
392 | staticperl mkbundle --use AnyEvent --use AnyEvent::Impl::Perl |
| 393 | |
393 | |
| 394 | Sometimes you want to load old-style "perl libraries" (F<.pl> files), |
394 | Sometimes you want to load old-style "perl libraries" (F<.pl> files), or |
| 395 | or maybe other weirdly named files. To do that, you need to quote |
395 | maybe other weirdly named files. To support this, the C<--use> option |
| 396 | the name in single or double quotes (this is because F<staticperl> |
396 | actually tries to do what you mean, depending on the string you specify: |
| 397 | I<literally> just adds the string after the C<require> - which acts |
397 | |
| 398 | different when confronted with quoted vs. unquoted strings). When given on |
398 | =over 4 |
| 399 | the command line, you probably need to quote once more to avoid your shell |
399 | |
| 400 | interpreting it. Common cases that need this are F<Config_heavy.pl> and |
400 | =item a possibly valid module name, e.g. F<common::sense>, F<Carp>, |
| 401 | F<utf8_heavy.pl>. |
401 | F<Coro::Mysql>. |
|
|
402 | |
|
|
403 | If the string contains no quotes, no F</> and no F<.>, then C<--use> |
|
|
404 | assumes that it is a normal module name. It will create a new package and |
|
|
405 | evaluate a C<use module> in it, i.e. it will load the package and do a |
|
|
406 | default import. |
|
|
407 | |
|
|
408 | The import step is done because many modules trigger more dependencies |
|
|
409 | when something is imported than without. |
|
|
410 | |
|
|
411 | =item anything that contains F</> or F<.> characters, |
|
|
412 | e.g. F<utf8_heavy.pl>, F<Module/private/data.pl>. |
|
|
413 | |
|
|
414 | The string will be quoted and passed to require, as if you used C<require |
|
|
415 | $module>. Nothing will be imported. |
|
|
416 | |
|
|
417 | =item "path" or 'path', e.g. C<"utf8_heavy.pl">. |
|
|
418 | |
|
|
419 | If you enclose the name into single or double quotes, then the quotes will |
|
|
420 | be removed and the resulting string will be passed to require. This syntax |
|
|
421 | is form compatibility with older versions of staticperl and should not be |
|
|
422 | used anymore. |
|
|
423 | |
|
|
424 | =back |
|
|
425 | |
|
|
426 | Example: C<use> AnyEvent::Socket, once using C<use> (importing the |
|
|
427 | symbols), and once via C<require>, not importing any symbols. The first |
|
|
428 | form is preferred as many modules load some extra dependencies when asked |
|
|
429 | to export symbols. |
|
|
430 | |
|
|
431 | staticperl mkbundle -MAnyEvent::Socket # use + import |
|
|
432 | staticperl mkbundle -MAnyEvent/Socket.pm # require only |
| 402 | |
433 | |
| 403 | Example: include the required files for F<perl -V> to work in all its |
434 | Example: include the required files for F<perl -V> to work in all its |
| 404 | glory (F<Config.pm> is included automatically by this). |
435 | glory (F<Config.pm> is included automatically by the dependency tracker). |
| 405 | |
436 | |
| 406 | # bourne shell |
437 | # shell command |
| 407 | staticperl mkbundle --use '"Config_heavy.pl"' |
438 | staticperl mkbundle -MConfig_heavy.pl |
| 408 | |
439 | |
| 409 | # bundle specification file |
440 | # bundle specification file |
| 410 | use "Config_heavy.pl" |
441 | use Config_heavy.pl |
| 411 | |
442 | |
| 412 | The C<-M>module syntax is included as a convenience that might be easier |
443 | The C<-M>module syntax is included as a convenience that might be easier |
| 413 | to remember than C<--use> - it's the same switch as perl itself uses |
444 | to remember than C<--use> - it's the same switch as perl itself uses |
| 414 | to load modules. Or maybe it confuses people. Time will tell. Or maybe |
445 | to load modules. Or maybe it confuses people. Time will tell. Or maybe |
| 415 | not. Sigh. |
446 | not. Sigh. |
| … | |
… | |
| 681 | Example: create a standalone perl binary called F<./myexe> that will |
712 | Example: create a standalone perl binary called F<./myexe> that will |
| 682 | execute F<appfile> when it is started. |
713 | execute F<appfile> when it is started. |
| 683 | |
714 | |
| 684 | staticperl mkbundle --app myexe --boot appfile |
715 | staticperl mkbundle --app myexe --boot appfile |
| 685 | |
716 | |
|
|
717 | =item C<--ignore-env> |
|
|
718 | |
|
|
719 | Generates extra code to unset some environment variables before |
|
|
720 | initialising/running perl. Perl supports a lot of environment variables |
|
|
721 | that might alter execution in ways that might be undesirablre for |
|
|
722 | standalone applications, and this option removes those known to cause |
|
|
723 | trouble. |
|
|
724 | |
|
|
725 | Specifically, these are removed: |
|
|
726 | |
|
|
727 | C<PERL_HASH_SEED_DEBUG> and C<PERL_DEBUG_MSTATS> can cause underaible |
|
|
728 | output, C<PERL5OPT>, C<PERL_DESTRUCT_LEVEL>, C<PERL_HASH_SEED> and |
|
|
729 | C<PERL_SIGNALS> can alter execution significantly, and C<PERL_UNICODE>, |
|
|
730 | C<PERLIO_DEBUG> and C<PERLIO> can affect input and output. |
|
|
731 | |
|
|
732 | The variables C<PERL_LIB> and C<PERL5_LIB> are always ignored because the |
|
|
733 | startup code used by F<staticperl> overrides C<@INC> in all cases. |
|
|
734 | |
|
|
735 | This option will not make your program more secure (unless you are |
|
|
736 | running with elevated privileges), but it will reduce the surprise effect |
|
|
737 | when a user has these environment variables set and doesn't expect your |
|
|
738 | standalone program to act like a perl interpreter. |
|
|
739 | |
| 686 | =item C<--static> |
740 | =item C<--static> |
| 687 | |
741 | |
| 688 | Add C<-static> to F<bundle.ldopts>, which means a fully static (if |
742 | Add C<-static> to F<bundle.ldopts>, which means a fully static (if |
| 689 | supported by the OS) executable will be created. This is not immensely |
743 | supported by the OS) executable will be created. This is not immensely |
| 690 | useful when just creating the bundle files, but is most useful when |
744 | useful when just creating the bundle files, but is most useful when |
| … | |
… | |
| 1130 | |
1184 | |
| 1131 | Some functionality in the utf8 module, such as swash handling (used |
1185 | Some functionality in the utf8 module, such as swash handling (used |
| 1132 | for unicode character ranges in regexes) is implemented in the |
1186 | for unicode character ranges in regexes) is implemented in the |
| 1133 | C<"utf8_heavy.pl"> library: |
1187 | C<"utf8_heavy.pl"> library: |
| 1134 | |
1188 | |
| 1135 | -M'"utf8_heavy.pl"' |
1189 | -Mutf8_heavy.pl |
| 1136 | |
1190 | |
| 1137 | Many Unicode properties in turn are defined in separate modules, |
1191 | Many Unicode properties in turn are defined in separate modules, |
| 1138 | such as C<"unicore/Heavy.pl"> and more specific data tables such as |
1192 | such as C<"unicore/Heavy.pl"> and more specific data tables such as |
| 1139 | C<"unicore/To/Digit.pl"> or C<"unicore/lib/Perl/Word.pl">. These tables |
1193 | C<"unicore/To/Digit.pl"> or C<"unicore/lib/Perl/Word.pl">. These tables |
| 1140 | are big (7MB uncompressed, although F<staticperl> contains special |
1194 | are big (7MB uncompressed, although F<staticperl> contains special |
