… | |
… | |
18 | |
18 | |
19 | Typical Examples: |
19 | Typical Examples: |
20 | |
20 | |
21 | staticperl install # fetch, configure, build and install perl |
21 | staticperl install # fetch, configure, build and install perl |
22 | staticperl cpan # run interactive cpan shell |
22 | staticperl cpan # run interactive cpan shell |
23 | staticperl mkperl -M '"Config_heavy.pl"' # build a perl that supports -V |
23 | staticperl mkperl -MConfig_heavy.pl # build a perl that supports -V |
24 | staticperl mkperl -MAnyEvent::Impl::Perl -MAnyEvent::HTTPD -MURI -MURI::http |
24 | staticperl mkperl -MAnyEvent::Impl::Perl -MAnyEvent::HTTPD -MURI -MURI::http |
25 | # build a perl with the above modules linked in |
25 | # build a perl with the above modules linked in |
26 | staticperl mkapp myapp --boot mainprog mymodules |
26 | staticperl mkapp myapp --boot mainprog mymodules |
27 | # build a binary "myapp" from mainprog and mymodules |
27 | # build a binary "myapp" from mainprog and mymodules |
28 | |
28 | |
… | |
… | |
131 | installing perl and perl modules, and the "phase 2" commands, which deal |
131 | installing perl and perl modules, and the "phase 2" commands, which deal |
132 | with creating binaries and bundle files. |
132 | with creating binaries and bundle files. |
133 | |
133 | |
134 | PHASE 1 COMMANDS: INSTALLING PERL |
134 | PHASE 1 COMMANDS: INSTALLING PERL |
135 | The most important command is install, which does basically everything. |
135 | The most important command is install, which does basically everything. |
136 | The default is to download and install perl 5.12.2 and a few modules |
136 | The default is to download and install perl 5.12.3 and a few modules |
137 | required by staticperl itself, but all this can (and should) be changed |
137 | required by staticperl itself, but all this can (and should) be changed |
138 | - see CONFIGURATION, below. |
138 | - see CONFIGURATION, below. |
139 | |
139 | |
140 | The command |
140 | The command |
141 | |
141 | |
… | |
… | |
233 | |
233 | |
234 | # first make sure we have perl and the required modules |
234 | # first make sure we have perl and the required modules |
235 | staticperl instcpan AnyEvent::HTTPD |
235 | staticperl instcpan AnyEvent::HTTPD |
236 | |
236 | |
237 | # now build the perl |
237 | # now build the perl |
238 | staticperl mkperl -M'"Config_heavy.pl"' -MAnyEvent::Impl::Perl \ |
238 | staticperl mkperl -MConfig_heavy.pl -MAnyEvent::Impl::Perl \ |
239 | -MAnyEvent::HTTPD -MURI::http \ |
239 | -MAnyEvent::HTTPD -MURI::http \ |
240 | --add 'eg/httpd httpd.pm' |
240 | --add 'eg/httpd httpd.pm' |
241 | |
241 | |
242 | # finally, invoke it |
242 | # finally, invoke it |
243 | ./perl -Mhttpd |
243 | ./perl -Mhttpd |
… | |
… | |
339 | are selected for inclusion in the bundle. The relevant options are |
339 | are selected for inclusion in the bundle. The relevant options are |
340 | executed in order (this makes a difference mostly for "--eval", |
340 | executed in order (this makes a difference mostly for "--eval", |
341 | which can rely on earlier "--use" options to have been executed). |
341 | which can rely on earlier "--use" options to have been executed). |
342 | |
342 | |
343 | "--use" module | "-M"module |
343 | "--use" module | "-M"module |
344 | Include the named module and trace direct dependencies. This is |
344 | Include the named module or perl library and trace direct |
345 | done by "require"'ing the module in a subprocess and tracing |
345 | dependencies. This is done by loading the module in a subprocess |
346 | which other modules and files it actually loads. |
346 | and tracing which other modules and files it actually loads. |
347 | |
347 | |
348 | Example: include AnyEvent and AnyEvent::Impl::Perl. |
348 | Example: include AnyEvent and AnyEvent::Impl::Perl. |
349 | |
349 | |
350 | staticperl mkbundle --use AnyEvent --use AnyEvent::Impl::Perl |
350 | staticperl mkbundle --use AnyEvent --use AnyEvent::Impl::Perl |
351 | |
351 | |
352 | Sometimes you want to load old-style "perl libraries" (.pl |
352 | Sometimes you want to load old-style "perl libraries" (.pl |
353 | files), or maybe other weirdly named files. To do that, you need |
353 | files), or maybe other weirdly named files. To support this, the |
354 | to quote the name in single or double quotes (this is because |
354 | "--use" option actually tries to do what you mean, depending on |
355 | staticperl *literally* just adds the string after the "require" |
355 | the string you specify: |
356 | - which acts different when confronted with quoted vs. unquoted |
356 | |
357 | strings). When given on the command line, you probably need to |
357 | a possibly valid module name, e.g. common::sense, Carp, |
358 | quote once more to avoid your shell interpreting it. Common |
358 | Coro::Mysql. |
359 | cases that need this are Config_heavy.pl and utf8_heavy.pl. |
359 | If the string contains no quotes, no / and no ., then |
|
|
360 | "--use" assumes that it is a normal module name. It will |
|
|
361 | create a new package and evaluate a "use module" in it, i.e. |
|
|
362 | it will load the package and do a default import. |
|
|
363 | |
|
|
364 | The import step is done because many modules trigger more |
|
|
365 | dependencies when something is imported than without. |
|
|
366 | |
|
|
367 | anything that contains / or . characters, e.g. utf8_heavy.pl, |
|
|
368 | Module/private/data.pl. |
|
|
369 | The string will be quoted and passed to require, as if you |
|
|
370 | used "require $module". Nothing will be imported. |
|
|
371 | |
|
|
372 | "path" or 'path', e.g. "utf8_heavy.pl". |
|
|
373 | If you enclose the name into single or double quotes, then |
|
|
374 | the quotes will be removed and the resulting string will be |
|
|
375 | passed to require. This syntax is form compatibility with |
|
|
376 | older versions of staticperl and should not be used anymore. |
|
|
377 | |
|
|
378 | Example: "use" AnyEvent::Socket, once using "use" (importing the |
|
|
379 | symbols), and once via "require", not importing any symbols. The |
|
|
380 | first form is preferred as many modules load some extra |
|
|
381 | dependencies when asked to export symbols. |
|
|
382 | |
|
|
383 | staticperl mkbundle -MAnyEvent::Socket # use + import |
|
|
384 | staticperl mkbundle -MAnyEvent/Socket.pm # require only |
360 | |
385 | |
361 | Example: include the required files for perl -V to work in all |
386 | Example: include the required files for perl -V to work in all |
362 | its glory (Config.pm is included automatically by this). |
387 | its glory (Config.pm is included automatically by the dependency |
|
|
388 | tracker). |
363 | |
389 | |
364 | # bourne shell |
390 | # shell command |
365 | staticperl mkbundle --use '"Config_heavy.pl"' |
391 | staticperl mkbundle -MConfig_heavy.pl |
366 | |
392 | |
367 | # bundle specification file |
393 | # bundle specification file |
368 | use "Config_heavy.pl" |
394 | use Config_heavy.pl |
369 | |
395 | |
370 | The "-M"module syntax is included as a convenience that might be |
396 | The "-M"module syntax is included as a convenience that might be |
371 | easier to remember than "--use" - it's the same switch as perl |
397 | easier to remember than "--use" - it's the same switch as perl |
372 | itself uses to load modules. Or maybe it confuses people. Time |
398 | itself uses to load modules. Or maybe it confuses people. Time |
373 | will tell. Or maybe not. Sigh. |
399 | will tell. Or maybe not. Sigh. |
… | |
… | |
378 | special use statement. In that case, you can use "--eval" to |
404 | special use statement. In that case, you can use "--eval" to |
379 | execute some perl snippet or set some variables or whatever you |
405 | execute some perl snippet or set some variables or whatever you |
380 | need. All files "require"'d or "use"'d while executing the |
406 | need. All files "require"'d or "use"'d while executing the |
381 | snippet are included in the final bundle. |
407 | snippet are included in the final bundle. |
382 | |
408 | |
383 | Keep in mind that mkbundle will only "require" the modules named |
409 | Keep in mind that mkbundle will not import any symbols from the |
384 | by the "--use" option, so do not expect the symbols from modules |
410 | modules named by the "--use" option, so do not expect the |
385 | you "--use"'d earlier on the command line to be available. |
411 | symbols from modules you "--use"'d earlier on the command line |
|
|
412 | to be available. |
386 | |
413 | |
387 | Example: force AnyEvent to detect a backend and therefore |
414 | Example: force AnyEvent to detect a backend and therefore |
388 | include it in the final bundle. |
415 | include it in the final bundle. |
389 | |
416 | |
390 | staticperl mkbundle --eval 'use AnyEvent; AnyEvent::detect' |
417 | staticperl mkbundle --eval 'use AnyEvent; AnyEvent::detect' |
… | |
… | |
427 | "--add" file | "--add" "file alias" |
454 | "--add" file | "--add" "file alias" |
428 | Adds the given (perl) file into the bundle (and optionally call |
455 | Adds the given (perl) file into the bundle (and optionally call |
429 | it "alias"). The file is either an absolute path or a path |
456 | it "alias"). The file is either an absolute path or a path |
430 | relative to the current directory. If an alias is specified, |
457 | relative to the current directory. If an alias is specified, |
431 | then this is the name it will use for @INC searches, otherwise |
458 | then this is the name it will use for @INC searches, otherwise |
432 | the file will be used as the internal name. |
459 | the path file will be used as the internal name. |
433 | |
460 | |
434 | This switch is used to include extra files into the bundle. |
461 | This switch is used to include extra files into the bundle. |
435 | |
462 | |
436 | Example: embed the file httpd in the current directory as |
463 | Example: embed the file httpd in the current directory as |
437 | httpd.pm when creating the bundle. |
464 | httpd.pm when creating the bundle. |
438 | |
465 | |
439 | staticperl mkperl --add "httpd httpd.pm" |
466 | staticperl mkperl --add "httpd httpd.pm" |
|
|
467 | |
|
|
468 | # can be accessed via "use httpd" |
|
|
469 | |
|
|
470 | Example: add a file initcode from the current directory. |
|
|
471 | |
|
|
472 | staticperl mkperl --add 'initcode &initcode' |
|
|
473 | |
|
|
474 | # can be accessed via "do '&initcode'" |
440 | |
475 | |
441 | Example: add local files as extra modules in the bundle. |
476 | Example: add local files as extra modules in the bundle. |
442 | |
477 | |
443 | # specification file |
478 | # specification file |
444 | add file1 myfiles/file1.pm |
479 | add file1 myfiles/file1.pm |
… | |
… | |
453 | "--binadd" file | "--add" "file alias" |
488 | "--binadd" file | "--add" "file alias" |
454 | Just like "--add", except that it treats the file as binary and |
489 | Just like "--add", except that it treats the file as binary and |
455 | adds it without any postprocessing (perl files might get |
490 | adds it without any postprocessing (perl files might get |
456 | stripped to reduce their size). |
491 | stripped to reduce their size). |
457 | |
492 | |
458 | You should probably add a "/" prefix to avoid clashing with |
493 | If you specify an alias you should probably add a "&" prefix to |
459 | embedded perl files (whose paths do not start with "/"), and/or |
494 | avoid clashing with embedded perl files (whose paths never start |
460 | use a special directory prefix, such as "/res/name". |
495 | with "&"), and/or use a special directory prefix, such as |
|
|
496 | "&res/name". |
461 | |
497 | |
462 | You can later get a copy of these files by calling |
498 | You can later get a copy of these files by calling |
463 | "staticperl::find "alias"". |
499 | "staticperl::find "alias"". |
464 | |
500 | |
465 | An alternative way to embed binary files is to convert them to |
501 | An alternative way to embed binary files is to convert them to |
… | |
… | |
608 | The difference to the (mutually exclusive) "--perl" option is |
644 | The difference to the (mutually exclusive) "--perl" option is |
609 | that the binary created by this option will not try to act as a |
645 | that the binary created by this option will not try to act as a |
610 | perl interpreter - instead it will simply initialise the perl |
646 | perl interpreter - instead it will simply initialise the perl |
611 | interpreter, clean it up and exit. |
647 | interpreter, clean it up and exit. |
612 | |
648 | |
613 | This means that, by default, it will do nothing but burna few |
649 | This means that, by default, it will do nothing but burn a few |
614 | CPU cycles - for it to do something useful you *must* add some |
650 | CPU cycles - for it to do something useful you *must* add some |
615 | boot code, e.g. with the "--boot" option. |
651 | boot code, e.g. with the "--boot" option. |
616 | |
652 | |
617 | Example: create a standalone perl binary called ./myexe that |
653 | Example: create a standalone perl binary called ./myexe that |
618 | will execute appfile when it is started. |
654 | will execute appfile when it is started. |
619 | |
655 | |
620 | staticperl mkbundle --app myexe --boot appfile |
656 | staticperl mkbundle --app myexe --boot appfile |
|
|
657 | |
|
|
658 | "--ignore-env" |
|
|
659 | Generates extra code to unset some environment variables before |
|
|
660 | initialising/running perl. Perl supports a lot of environment |
|
|
661 | variables that might alter execution in ways that might be |
|
|
662 | undesirablre for standalone applications, and this option |
|
|
663 | removes those known to cause trouble. |
|
|
664 | |
|
|
665 | Specifically, these are removed: |
|
|
666 | |
|
|
667 | "PERL_HASH_SEED_DEBUG" and "PERL_DEBUG_MSTATS" can cause |
|
|
668 | underaible output, "PERL5OPT", "PERL_DESTRUCT_LEVEL", |
|
|
669 | "PERL_HASH_SEED" and "PERL_SIGNALS" can alter execution |
|
|
670 | significantly, and "PERL_UNICODE", "PERLIO_DEBUG" and "PERLIO" |
|
|
671 | can affect input and output. |
|
|
672 | |
|
|
673 | The variables "PERL_LIB" and "PERL5_LIB" are always ignored |
|
|
674 | because the startup code used by staticperl overrides @INC in |
|
|
675 | all cases. |
|
|
676 | |
|
|
677 | This option will not make your program more secure (unless you |
|
|
678 | are running with elevated privileges), but it will reduce the |
|
|
679 | surprise effect when a user has these environment variables set |
|
|
680 | and doesn't expect your standalone program to act like a perl |
|
|
681 | interpreter. |
621 | |
682 | |
622 | "--static" |
683 | "--static" |
623 | Add "-static" to bundle.ldopts, which means a fully static (if |
684 | Add "-static" to bundle.ldopts, which means a fully static (if |
624 | supported by the OS) executable will be created. This is not |
685 | supported by the OS) executable will be created. This is not |
625 | immensely useful when just creating the bundle files, but is |
686 | immensely useful when just creating the bundle files, but is |
… | |
… | |
733 | installation, you can set any environment variable you want - some |
794 | installation, you can set any environment variable you want - some |
734 | modules (such as Coro or EV) use environment variables for further |
795 | modules (such as Coro or EV) use environment variables for further |
735 | tweaking. |
796 | tweaking. |
736 | |
797 | |
737 | "PERL_VERSION" |
798 | "PERL_VERSION" |
738 | The perl version to install - default is currently 5.12.2, but 5.8.9 |
799 | The perl version to install - default is currently 5.12.3, but 5.8.9 |
739 | is also a good choice (5.8.9 is much smaller than 5.12.2, while |
800 | is also a good choice (5.8.9 is much smaller than 5.12.3, while |
740 | 5.10.1 is about as big as 5.12.2). |
801 | 5.10.1 is about as big as 5.12.3). |
741 | |
802 | |
742 | "PERL_PREFIX" |
803 | "PERL_PREFIX" |
743 | The prefix where perl gets installed (default: $STATICPERL/perl), |
804 | The prefix where perl gets installed (default: $STATICPERL/perl), |
744 | i.e. where the bin and lib subdirectories will end up. |
805 | i.e. where the bin and lib subdirectories will end up. |
745 | |
806 | |
… | |
… | |
843 | bundle.h |
904 | bundle.h |
844 | A header file that contains the prototypes of the few symbols |
905 | A header file that contains the prototypes of the few symbols |
845 | "exported" by bundle.c, and also exposes the perl headers to the |
906 | "exported" by bundle.c, and also exposes the perl headers to the |
846 | application. |
907 | application. |
847 | |
908 | |
848 | staticperl_init () |
909 | staticperl_init (xs_init = 0) |
849 | Initialises the perl interpreter. You can use the normal perl |
910 | Initialises the perl interpreter. You can use the normal perl |
850 | functions after calling this function, for example, to define |
911 | functions after calling this function, for example, to define |
851 | extra functions or to load a .pm file that contains some |
912 | extra functions or to load a .pm file that contains some |
852 | initialisation code, or the main program function: |
913 | initialisation code, or the main program function: |
853 | |
914 | |
… | |
… | |
859 | } |
920 | } |
860 | |
921 | |
861 | static void |
922 | static void |
862 | run_myapp(void) |
923 | run_myapp(void) |
863 | { |
924 | { |
864 | staticperl_init (); |
925 | staticperl_init (0); |
865 | newXSproto ("myapp::xsfunction", xsfunction, __FILE__, "$$;$"); |
926 | newXSproto ("myapp::xsfunction", xsfunction, __FILE__, "$$;$"); |
866 | eval_pv ("require myapp::main", 1); // executes "myapp/main.pm" |
927 | eval_pv ("require myapp::main", 1); // executes "myapp/main.pm" |
867 | } |
928 | } |
|
|
929 | |
|
|
930 | When your bootcode already wants to access some XS functions at |
|
|
931 | compiletime, then you need to supply an "xs_init" function |
|
|
932 | pointer that is called as soon as perl is initialised enough to |
|
|
933 | define XS functions, but before the preamble code is executed: |
|
|
934 | |
|
|
935 | static void |
|
|
936 | xs_init (pTHX) |
|
|
937 | { |
|
|
938 | newXSproto ("myapp::xsfunction", xsfunction, __FILE__, "$$;$"); |
|
|
939 | } |
|
|
940 | |
|
|
941 | static void |
|
|
942 | run_myapp(void) |
|
|
943 | { |
|
|
944 | staticperl_init (xs_init); |
|
|
945 | } |
|
|
946 | |
|
|
947 | staticperl_cleanup () |
|
|
948 | In the unlikely case that you want to destroy the perl |
|
|
949 | interpreter, here is the corresponding function. |
868 | |
950 | |
869 | staticperl_xs_init (pTHX) |
951 | staticperl_xs_init (pTHX) |
870 | Sometimes you need direct control over "perl_parse" and |
952 | Sometimes you need direct control over "perl_parse" and |
871 | "perl_run", in which case you do not want to use |
953 | "perl_run", in which case you do not want to use |
872 | "staticperl_init" but call them on your own. |
954 | "staticperl_init" but call them on your own. |
873 | |
955 | |
874 | Then you need this function - either pass it directly as the |
956 | Then you need this function - either pass it directly as the |
875 | "xs_init" function to "perl_parse", or call it from your own |
957 | "xs_init" function to "perl_parse", or call it as one of the |
876 | "xs_init" function. |
958 | first things from your own "xs_init" function. |
877 | |
|
|
878 | staticperl_cleanup () |
|
|
879 | In the unlikely case that you want to destroy the perl |
|
|
880 | interpreter, here is the corresponding function. |
|
|
881 | |
959 | |
882 | PerlInterpreter *staticperl |
960 | PerlInterpreter *staticperl |
883 | The perl interpreter pointer used by staticperl. Not normally so |
961 | The perl interpreter pointer used by staticperl. Not normally so |
884 | useful, but there it is. |
962 | useful, but there it is. |
885 | |
963 | |
… | |
… | |
973 | utf8 |
1051 | utf8 |
974 | Some functionality in the utf8 module, such as swash handling (used |
1052 | Some functionality in the utf8 module, such as swash handling (used |
975 | for unicode character ranges in regexes) is implemented in the |
1053 | for unicode character ranges in regexes) is implemented in the |
976 | "utf8_heavy.pl" library: |
1054 | "utf8_heavy.pl" library: |
977 | |
1055 | |
978 | -M'"utf8_heavy.pl"' |
1056 | -Mutf8_heavy.pl |
979 | |
1057 | |
980 | Many Unicode properties in turn are defined in separate modules, |
1058 | Many Unicode properties in turn are defined in separate modules, |
981 | such as "unicore/Heavy.pl" and more specific data tables such as |
1059 | such as "unicore/Heavy.pl" and more specific data tables such as |
982 | "unicore/To/Digit.pl" or "unicore/lib/Perl/Word.pl". These tables |
1060 | "unicore/To/Digit.pl" or "unicore/lib/Perl/Word.pl". These tables |
983 | are big (7MB uncompressed, although staticperl contains special |
1061 | are big (7MB uncompressed, although staticperl contains special |