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

Comparing App-Staticperl/README (file contents):
Revision 1.7 by root, Wed Dec 8 22:27:35 2010 UTC vs.
Revision 1.8 by root, Fri Dec 10 21:15:06 2010 UTC

… …
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
29DESCRIPTION 29DESCRIPTION
30 This script helps you creating single-file perl interpreters, or 30 This script helps you to create single-file perl interpreters or
31 embedding a perl interpreter in your applications. Single-file means 31 applications, or embedding a perl interpreter in your applications.
32 that it is fully self-contained - no separate shared objects, no 32 Single-file means that it is fully self-contained - no separate shared
33 autoload fragments, no .pm or .pl files are needed. And when linking 33 objects, no autoload fragments, no .pm or .pl files are needed. And when
34 statically, you can create (or embed) a single file that contains perl 34 linking statically, you can create (or embed) a single file that
35 interpreter, libc, all the modules you need and all the libraries you 35 contains perl interpreter, libc, all the modules you need, all the
36 need. 36 libraries you need and of course your actual program.
37 37
38 With uClibc and upx on x86, you can create a single 500kb binary that 38 With uClibc and upx on x86, you can create a single 500kb binary that
39 contains perl and 100 modules such as POSIX, AnyEvent, EV, IO::AIO, Coro 39 contains perl and 100 modules such as POSIX, AnyEvent, EV, IO::AIO, Coro
40 and so on. Or any other choice of modules. 40 and so on. Or any other choice of modules.
41
42 To see how this turns out, you can try out smallperl and bigperl, two
43 pre-built static and compressed perl binaries with many and even more
44 modules: just follow the links at <http://staticperl.schmorp.de/>.
41 45
42 The created files do not need write access to the file system (like PAR 46 The created files do not need write access to the file system (like PAR
43 does). In fact, since this script is in many ways similar to 47 does). In fact, since this script is in many ways similar to
44 PAR::Packer, here are the differences: 48 PAR::Packer, here are the differences:
45 49
… …
62 * The generated executables don't need a writable filesystem. 66 * The generated executables don't need a writable filesystem.
63 67
64 staticperl loads all required files directly from memory. There is 68 staticperl loads all required files directly from memory. There is
65 no need to unpack files into a temporary directory. 69 no need to unpack files into a temporary directory.
66 70
67 * More control over included files. 71 * More control over included files, more burden.
68 72
69 PAR tries to be maintenance and hassle-free - it tries to include 73 PAR tries to be maintenance and hassle-free - it tries to include
70 more files than necessary to make sure everything works out of the 74 more files than necessary to make sure everything works out of the
71 box. The extra files (such as the unicode database) can take 75 box. It mostly succeeds at this, but he extra files (such as the
72 substantial amounts of memory and file size. 76 unicode database) can take substantial amounts of memory and file
77 size.
73 78
74 With staticperl, the burden is mostly with the developer - only 79 With staticperl, the burden is mostly with the developer - only
75 direct compile-time dependencies and AutoLoader are handled 80 direct compile-time dependencies and AutoLoader are handled
76 automatically. This means the modules to include often need to be 81 automatically. This means the modules to include often need to be
77 tweaked manually. 82 tweaked manually.
83
84 All this does not preclude more permissive modes to be implemented
85 in the future, but right now, you have to resolve state hidden
86 dependencies manually.
78 87
79 * PAR works out of the box, staticperl does not. 88 * PAR works out of the box, staticperl does not.
80 89
81 Maintaining your own custom perl build can be a pain in the ass, and 90 Maintaining your own custom perl build can be a pain in the ass, and
82 while staticperl tries to make this easy, it still requires a custom 91 while staticperl tries to make this easy, it still requires a custom
… …
101 and then either build a new perl binary (that acts just like a normal 110 and then either build a new perl binary (that acts just like a normal
102 perl except everything is compiled in), or you create bundle files 111 perl except everything is compiled in), or you create bundle files
103 (basically C sources you can use to embed all files into your project). 112 (basically C sources you can use to embed all files into your project).
104 113
105 This step is very fast (a few seconds if PPI is not used for stripping, 114 This step is very fast (a few seconds if PPI is not used for stripping,
106 more seconds otherwise, as PPI is very slow), and can be tweaked and 115 or the stripped files are in the cache), and can be tweaked and repeated
107 repeated as often as necessary. 116 as often as necessary.
108 117
109THE STATICPERL SCRIPT 118THE STATICPERL SCRIPT
110 This module installs a script called staticperl into your perl binary 119 This module installs a script called staticperl into your perl binary
111 directory. The script is fully self-contained, and can be used without 120 directory. The script is fully self-contained, and can be used without
112 perl (for example, in an uClibc chroot environment). In fact, it can be 121 perl (for example, in an uClibc chroot environment). In fact, it can be
… …
137 Most of the following commands simply run one or more steps of this 146 Most of the following commands simply run one or more steps of this
138 sequence. 147 sequence.
139 148
140 To force recompilation or reinstallation, you need to run staticperl 149 To force recompilation or reinstallation, you need to run staticperl
141 distclean first. 150 distclean first.
151
152 staticperl version
153 Prints some info about the version of the staticperl script you are
154 using.
142 155
143 staticperl fetch 156 staticperl fetch
144 Runs only the download and unpack phase, unless this has already 157 Runs only the download and unpack phase, unless this has already
145 happened. 158 happened.
146 159
… …
261 274
262 All options that specify modules or files to be added are processed in 275 All options that specify modules or files to be added are processed in
263 the order given on the command line (that affects the "--use" and 276 the order given on the command line (that affects the "--use" and
264 "--eval" options at the moment). 277 "--eval" options at the moment).
265 278
279 PACKAGE SELECTION WORKFLOW
280 staticperl mkbundle has a number of options to control package
281 selection. This section describes how they interact with each other.
282 Also, since I am still a newbie w.r.t. these issues, maybe future
283 versions of staticperl will change this, so watch out :)
284
285 The idiom "in order" means "in order that they are specified on the
286 commandline". If you use a bundle specification file, then the options
287 will be processed as if they were given in place of the bundle file
288 name.
289
290 1. apply all "--use", "--eval", "--add", "--addbin" and "--incglob"
291 options, in order.
292 In addition, "--use" and "--eval" dependencies will be added when
293 the options are processed.
294
295 2. apply all "--include" and "--exclude" options, in order.
296 All this step does is potentially reduce the number of files already
297 selected or found in phase 1.
298
299 3. find all modules (== .pm files), gather their static archives (.a)
300 and AutoLoader splitfiles (.ix and .al files), find any extra libraries
301 they need for linking (extralibs.ld) and optionally evaluate any
302 .packlist files.
303 This step is required to link against XS extensions and also adds
304 files required for AutoLoader to do it's job.
305
306 After this, all the files selected for bundling will be read and
307 processed (stripped), the bundle files will be written, and optionally a
308 new perl or application binary will be linked.
309
266 MKBUNDLE OPTIONS 310 MKBUNDLE OPTIONS
267 --verbose | -v 311 --verbose | -v
268 Increases the verbosity level by one (the default is 1). 312 Increases the verbosity level by one (the default is 1).
269 313
270 --quiet | -q 314 --quiet | -q
… …
277 The default is "pod", which uses the Pod::Strip module to remove all 321 The default is "pod", which uses the Pod::Strip module to remove all
278 pod documentation, which is very fast and reduces file size a lot. 322 pod documentation, which is very fast and reduces file size a lot.
279 323
280 The "ppi" method uses PPI to parse and condense the perl sources. 324 The "ppi" method uses PPI to parse and condense the perl sources.
281 This saves a lot more than just Pod::Strip, and is generally safer, 325 This saves a lot more than just Pod::Strip, and is generally safer,
282 but is also a lot slower, so is best used for production builds. 326 but is also a lot slower (some files take almost a minute to strip -
283 Note that this method doesn't optimise for raw file size, but for 327 staticperl maintains a cache of stripped files to speed up
284 best compression (that means that the uncompressed file size is a 328 subsequent runs for this reason). Note that this method doesn't
329 optimise for raw file size, but for best compression (that means
330 that the uncompressed file size is a bit larger, but the files
285 bit larger, but the files compress better, e.g. with upx). 331 compress better, e.g. with upx).
286 332
287 Last not least, if you need accurate line numbers in error messages, 333 Last not least, if you need accurate line numbers in error messages,
288 or in the unlikely case where "pod" is too slow, or some module gets 334 or in the unlikely case where "pod" is too slow, or some module gets
289 mistreated, you can specify "none" to not mangle included perl 335 mistreated, you can specify "none" to not mangle included perl
290 sources in any way. 336 sources in any way.
… …
382 executed (using a "require") before anything else when the new perl 428 executed (using a "require") before anything else when the new perl
383 is initialised. This can be used to modify @INC or anything else 429 is initialised. This can be used to modify @INC or anything else
384 before the perl interpreter executes scripts given on the command 430 before the perl interpreter executes scripts given on the command
385 line (or via "-e"). This works even in an embedded interpreter. 431 line (or via "-e"). This works even in an embedded interpreter.
386 432
387 --add "file" | --add "file alias" 433 --usepacklist
434 Read .packlist files for each distribution that happens to match a
435 module name you specified. Sounds weird, and it is, so expect
436 semantics to change somehow in the future.
437
438 The idea is that most CPAN distributions have a .pm file that
439 matches the name of the distribution (which is rather reasonable
440 after all).
441
442 If this switch is enabled, then if any of the .pm files that have
443 been selected match an install distribution, then all .pm, .pl, .al
444 and .ix files installed by this distribution are also included.
445
446 For example, using this switch, when the URI module is specified,
447 then all URI submodules that have been installed via the CPAN
448 distribution are included as well, so you don't have to manually
449 specify them.
450
451 --incglob pattern
452 This goes through all library directories and tries to match any .pm
453 and .pl files against the extended glob pattern (see below). If a
454 file matches, it is added. This switch will automatically detect
455 AutoLoader files and the required link libraries for XS modules, but
456 it will *not* scan the file for dependencies (at the moment).
457
458 This is mainly useful to include "everything":
459
460 --incglob '*'
461
462 Or to include perl libraries, or trees of those, such as the unicode
463 database files needed by many other modules:
464
465 --incglob '/unicore/**.pl'
466
467 --add file | --add "file alias"
388 Adds the given (perl) file into the bundle (and optionally call it 468 Adds the given (perl) file into the bundle (and optionally call it
389 "alias"). This is useful to include any custom files into the 469 "alias"). This is useful to include any custom files into the
390 bundle. 470 bundle.
391 471
392 Example: embed the file httpd as httpd.pm when creating the bundle. 472 Example: embed the file httpd as httpd.pm when creating the bundle.
… …
398 # specification file 478 # specification file
399 add file1 myfiles/file1 479 add file1 myfiles/file1
400 add file2 myfiles/file2 480 add file2 myfiles/file2
401 add file3 myfiles/file3 481 add file3 myfiles/file3
402 482
403 --binadd "file" | --add "file alias" 483 --binadd file | --add "file alias"
404 Just like "--add", except that it treats the file as binary and adds 484 Just like "--add", except that it treats the file as binary and adds
405 it without any processing. 485 it without any processing.
406 486
407 You should probably add a "/" prefix to avoid clashing with embedded 487 You should probably add a "/" prefix to avoid clashing with embedded
408 perl files (whose paths do not start with "/"), and/or use a special 488 perl files (whose paths do not start with "/"), and/or use a special
409 directory, such as "/res/name". 489 directory, such as "/res/name".
410 490
411 You can later get a copy of these files by calling "staticperl::find 491 You can later get a copy of these files by calling "staticperl::find
412 "alias"". 492 "alias"".
493
494 --include pattern | -i pattern | --exclude pattern | -x pattern
495 These two options define an include/exclude filter that is used
496 after all files selected by the other options have been found. Each
497 include/exclude is applied to all files found so far - an include
498 makes sure that the given files will be part of the resulting file
499 set, an exclude will exclude files. The patterns are "extended glob
500 patterns" (see below).
501
502 For example, to include everything, except "Devel" modules, but
503 still include Devel::PPPort, you could use this:
504
505 --incglob '*' -i '/Devel/PPPort.pm' -x '/Devel/**'
413 506
414 --static 507 --static
415 When "--perl" is also given, link statically instead of dynamically. 508 When "--perl" is also given, link statically instead of dynamically.
416 The default is to link the new perl interpreter fully dynamic (that 509 The default is to link the new perl interpreter fully dynamic (that
417 means all perl modules are linked statically, but all external 510 means all perl modules are linked statically, but all external
… …
421 systems based on GNU libc don't really support it in a usable 514 systems based on GNU libc don't really support it in a usable
422 fashion either. Try uClibc if you want to create fully statically 515 fashion either. Try uClibc if you want to create fully statically
423 linked executables, or try the "--staticlibs" option to link only 516 linked executables, or try the "--staticlibs" option to link only
424 some libraries statically. 517 some libraries statically.
425 518
519 --staticlib libname
520 When not linking fully statically, this option allows you to link
521 specific libraries statically. What it does is simply replace all
522 occurances of "-llibname" with the GCC-specific "-Wl,-Bstatic
523 -llibname -Wl,-Bdynamic" option.
524
525 This will have no effect unless the library is actually linked
526 against, specifically, "--staticlib" will not link against the named
527 library unless it would be linked against anyway.
528
529 Example: link libcrypt statically into the binary.
530
531 staticperl mkperl -MIO::AIO --staticlib crypt
532
533 # ldopts might nwo contain:
534 # -lm -Wl,-Bstatic -lcrypt -Wl,-Bdynamic -lpthread
535
426 any other argument 536 any other argument
427 Any other argument is interpreted as a bundle specification file, 537 Any other argument is interpreted as a bundle specification file,
428 which supports most long options (without extra quoting), one option 538 which supports most long options (without extra quoting), one option
429 per line. 539 per line.
430 540
541 EXTENDED GLOB PATTERNS
542 Some options of staticperl mkbundle expect an *extended glob pattern*.
543 This is neither a normal shell glob nor a regex, but something in
544 between. The idea has been copied from rsync, and there are the current
545 matching rules:
546
547 Patterns starting with / will be a anchored at the root of the library
548 tree.
549 That is, /unicore will match the unicore directory in @INC, but
550 nothing inside, and neither any other file or directory called
551 unicore anywhere else in the hierarchy.
552
553 Patterns not starting with / will be anchored at the end of the path.
554 That is, idna.pl will match any file called idna.pl anywhere in the
555 hierarchy, but not any directories of the same name.
556
557 A * matches any single component.
558 That is, /unicore/*.pl would match all .pl files directly inside
559 "/unicore", not any deeper level .pl files. Or in other words, *
560 will not match slashes.
561
562 A ** matches anything.
563 That is, /unicore/**.pl would match all .pl files under /unicore, no
564 matter how deeply nested they are inside subdirectories.
565
566 A ? matches a single character within a component.
567 That is, /Encode/??.pm matches /Encode/JP.pm, but not the
568 hypothetical /Encode/J/.pm, as ? does not match /.
569
431 STATCPERL CONFIGURATION AND HOOKS 570 STATICPERL CONFIGURATION AND HOOKS
432 During (each) startup, staticperl tries to source the following shell 571 During (each) startup, staticperl tries to source some shell files to
572 allow you to fine-tune/override configuration settings.
573
574 In them you can override shell variables, or define shell functions
575 ("hooks") to be called at specific phases during installation. For
576 example, you could define a "postinstall" hook to install additional
577 modules from CPAN each time you start from scratch.
578
579 If the env variable $STATICPERLRC is set, then staticperl will try to
580 source the file named with it only. Otherwise, it tries the following
433 files in order: 581 shell files in order:
434 582
435 /etc/staticperlrc 583 /etc/staticperlrc
436 ~/.staticperlrc 584 ~/.staticperlrc
437 $STATICPERL/rc 585 $STATICPERL/rc
438
439 They can be used to override shell variables, or define functions to be
440 called at specific phases.
441 586
442 Note that the last file is erased during staticperl distclean, so 587 Note that the last file is erased during staticperl distclean, so
443 generally should not be used. 588 generally should not be used.
444 589
445 CONFIGURATION VARIABLES 590 CONFIGURATION VARIABLES
… …
696 After you have compiled and set up your buildroot target, you can copy 841 After you have compiled and set up your buildroot target, you can copy
697 staticperl from the "App::Staticperl" distribution or from your perl 842 staticperl from the "App::Staticperl" distribution or from your perl
698 f<bin> directory (if you installed it) into the output/target 843 f<bin> directory (if you installed it) into the output/target
699 filesystem, chroot inside and run it. 844 filesystem, chroot inside and run it.
700 845
846RECIPES / SPECIFIC MODULES
847 This section contains some common(?) recipes and information about
848 problems with some common modules or perl constructs that require extra
849 files to be included.
850
851 MODULES
852 utf8
853 Some functionality in the utf8 module, such as swash handling (used
854 for unicode character ranges in regexes) is implemented in the
855 "utf8_heavy.pl" library:
856
857 -M'"utf8_heavy.pl"'
858
859 Many Unicode properties in turn are defined in separate modules,
860 such as "unicore/Heavy.pl" and more specific data tables such as
861 "unicore/To/Digit.pl" or "unicore/lib/Perl/Word.pl". These tables
862 are big (7MB uncompressed, although staticperl contains special
863 handling for those files), so including them on demand by your
864 application only might pay off.
865
866 To simply include the whole unicode database, use:
867
868 --incglob '/unicore/*.pl'
869
870 AnyEvent
871 AnyEvent needs a backend implementation that it will load in a
872 delayed fashion. The AnyEvent::Impl::Perl backend is the default
873 choice for AnyEvent if it can't find anything else, and is usually a
874 safe fallback. If you plan to use e.g. EV (POE...), then you need to
875 include the AnyEvent::Impl::EV (AnyEvent::Impl::POE...) backend as
876 well.
877
878 If you want to handle IRIs or IDNs (AnyEvent::Util punycode and idn
879 functions), you also need to include "AnyEvent/Util/idna.pl" and
880 "AnyEvent/Util/uts46data.pl".
881
882 Or you can use "--usepacklist" and specify "-MAnyEvent" to include
883 everything.
884
885 Carp
886 Carp had (in older versions of perl) a dependency on Carp::Heavy. As
887 of perl 5.12.2 (maybe earlier), this dependency no longer exists.
888
889 Config
890 The perl -V switch (as well as many modules) needs Config, which in
891 turn might need "Config_heavy.pl". Including the latter gives you
892 both.
893
894 Term::ReadLine::Perl
895 Also needs Term::ReadLine::readline, or "--usepacklist".
896
897 URI URI implements schemes as separate modules - the generic URL scheme
898 is implemented in URI::_generic, HTTP is implemented in URI::http.
899 If you need to use any of these schemes, you should include these
900 manually, or use "--usepacklist".
901
902 RECIPES
903 Linking everything in
904 To link just about everything installed in the perl library into a
905 new perl, try this:
906
907 staticperl mkperl --strip ppi --incglob '*'
908
909 Getting rid of netdb function
910 The perl core has lots of netdb functions ("getnetbyname",
911 "getgrent" and so on) that few applications use. You can avoid
912 compiling them in by putting the following fragment into a
913 "preconfigure" hook:
914
915 preconfigure() {
916 for sym in \
917 d_getgrnam_r d_endgrent d_endgrent_r d_endhent \
918 d_endhostent_r d_endnent d_endnetent_r d_endpent \
919 d_endprotoent_r d_endpwent d_endpwent_r d_endsent \
920 d_endservent_r d_getgrent d_getgrent_r d_getgrgid_r \
921 d_getgrnam_r d_gethbyaddr d_gethent d_getsbyport \
922 d_gethostbyaddr_r d_gethostbyname_r d_gethostent_r \
923 d_getlogin_r d_getnbyaddr d_getnbyname d_getnent \
924 d_getnetbyaddr_r d_getnetbyname_r d_getnetent_r \
925 d_getpent d_getpbyname d_getpbynumber d_getprotobyname_r \
926 d_getprotobynumber_r d_getprotoent_r d_getpwent \
927 d_getpwent_r d_getpwnam_r d_getpwuid_r d_getsent \
928 d_getservbyname_r d_getservbyport_r d_getservent_r \
929 d_getspnam_r d_getsbyname
930 # d_gethbyname
931 do
932 PERL_CONFIGURE="$PERL_CONFIGURE -U$sym"
933 done
934 }
935
936 This mostly gains space when linking staticaly, as the functions
937 will liekly not be linked in. The gain for dynamically-linked
938 binaries is smaller.
939
940 Also, this leaves "gethostbyname" in - not only is it actually used
941 often, the Socket module also exposes it, so leaving it out usually
942 gains little. Why Socket exposes a C function that is in the core
943 already is anybody's guess.
944
701AUTHOR 945AUTHOR
702 Marc Lehmann <schmorp@schmorp.de> 946 Marc Lehmann <schmorp@schmorp.de>
703 http://software.schmorp.de/pkg/staticperl.html 947 http://software.schmorp.de/pkg/staticperl.html
704 948

Diff Legend

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