ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/App-Staticperl/README
(Generate patch)

Comparing App-Staticperl/README (file contents):
Revision 1.11 by root, Wed Jan 12 03:35:40 2011 UTC vs.
Revision 1.12 by root, Thu Feb 24 07:10:03 2011 UTC

… …
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

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines