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

Comparing App-Staticperl/staticperl.pod (file contents):
Revision 1.4 by root, Mon Dec 6 21:12:21 2010 UTC vs.
Revision 1.18 by root, Fri Dec 10 02:35:54 2010 UTC

1=head1 NAME 1=head1 NAME
2 2
3staticperl - perl, libc, 50 modules all in one 500kb file 3staticperl - perl, libc, 100 modules, all in one 500kb file
4 4
5=head1 SYNOPSIS 5=head1 SYNOPSIS
6 6
7 staticperl help # print the embedded documentation 7 staticperl help # print the embedded documentation
8 staticperl fetch # fetch and unpack perl sources 8 staticperl fetch # fetch and unpack perl sources
14 staticperl cpan # invoke CPAN shell 14 staticperl cpan # invoke CPAN shell
15 staticperl instmod path... # install unpacked modules 15 staticperl instmod path... # install unpacked modules
16 staticperl instcpan modulename... # install modules from CPAN 16 staticperl instcpan modulename... # install modules from CPAN
17 staticperl mkbundle <bundle-args...> # see documentation 17 staticperl mkbundle <bundle-args...> # see documentation
18 staticperl mkperl <bundle-args...> # see documentation 18 staticperl mkperl <bundle-args...> # see documentation
19 staticperl mkapp appname <bundle-args...> # see documentation
19 20
20Typical Examples: 21Typical Examples:
21 22
22 staticperl install # fetch, configure, build and install perl 23 staticperl install # fetch, configure, build and install perl
23 staticperl cpan # run interactive cpan shell 24 staticperl cpan # run interactive cpan shell
24 staticperl mkperl -M '"Config_heavy.pl"' # build a perl that supports -V 25 staticperl mkperl -M '"Config_heavy.pl"' # build a perl that supports -V
25 staticperl mkperl -MAnyEvent::Impl::Perl -MAnyEvent::HTTPD -MURI -MURI::http 26 staticperl mkperl -MAnyEvent::Impl::Perl -MAnyEvent::HTTPD -MURI -MURI::http
26 # 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
29 # build a binary "myapp" from mainprog and mymodules
27 30
28=head1 DESCRIPTION 31=head1 DESCRIPTION
29 32
30This script helps you creating single-file perl interpreters, or embedding 33This script helps you to create single-file perl interpreters
31a perl interpreter in your applications. Single-file means that it is 34or applications, or embedding a perl interpreter in your
32fully self-contained - no separate shared objects, no autoload fragments, 35applications. Single-file means that it is fully self-contained - no
33no .pm or .pl files are needed. And when linking statically, you can 36separate shared objects, no autoload fragments, no .pm or .pl files are
34create (or embed) a single file that contains perl interpreter, libc, all 37needed. And when linking statically, you can create (or embed) a single
35the modules you need and all the libraries you need. 38file that contains perl interpreter, libc, all the modules you need, all
39the libraries you need and of course your actual program.
36 40
37With F<uClibc> and F<upx> on x86, you can create a single 500kb binary that 41With F<uClibc> and F<upx> on x86, you can create a single 500kb binary
38contains perl and 50 modules such as AnyEvent, EV, IO::AIO, Coro and so 42that contains perl and 100 modules such as POSIX, AnyEvent, EV, IO::AIO,
39on. Or any other choice of modules. 43Coro and so on. Or any other choice of modules.
40 44
41The created files do not need write access to the file system (like PAR 45The created files do not need write access to the file system (like PAR
42does). In fact, since this script is in many ways similar to PAR::Packer, 46does). In fact, since this script is in many ways similar to PAR::Packer,
43here are the differences: 47here are the differences:
44 48
63=item * The generated executables don't need a writable filesystem. 67=item * The generated executables don't need a writable filesystem.
64 68
65F<staticperl> loads all required files directly from memory. There is no 69F<staticperl> loads all required files directly from memory. There is no
66need to unpack files into a temporary directory. 70need to unpack files into a temporary directory.
67 71
68=item * More control over included files. 72=item * More control over included files, more burden.
69 73
70PAR tries to be maintenance and hassle-free - it tries to include more 74PAR tries to be maintenance and hassle-free - it tries to include more
71files than necessary to make sure everything works out of the box. The 75files than necessary to make sure everything works out of the box. It
72extra files (such as the unicode database) can take substantial amounts of 76mostly succeeds at this, but he extra files (such as the unicode database)
73memory and file size. 77can take substantial amounts of memory and file size.
74 78
75With F<staticperl>, the burden is mostly with the developer - only direct 79With F<staticperl>, the burden is mostly with the developer - only direct
76compile-time dependencies and L<AutoLoader> are handled automatically. 80compile-time dependencies and L<AutoLoader> are handled automatically.
77This means the modules to include often need to be tweaked manually. 81This means the modules to include often need to be tweaked manually.
82
83All this does not preclude more permissive modes to be implemented in
84the future, but right now, you have to resolve state hidden dependencies
85manually.
78 86
79=item * PAR works out of the box, F<staticperl> does not. 87=item * PAR works out of the box, F<staticperl> does not.
80 88
81Maintaining your own custom perl build can be a pain in the ass, and while 89Maintaining your own custom perl build can be a pain in the ass, and while
82F<staticperl> tries to make this easy, it still requires a custom perl 90F<staticperl> tries to make this easy, it still requires a custom perl
83build and possibly fiddling with some modules. PAR is likely to produce 91build and possibly fiddling with some modules. PAR is likely to produce
84results faster. 92results faster.
93
94Ok, PAR never has worked for me out of the box, and for some people,
95F<staticperl> does work out of the box, as they don't count "fiddling with
96module use lists" against it, but nevertheless, F<staticperl> is certainly
97a bit more difficult to use.
85 98
86=back 99=back
87 100
88=head1 HOW DOES IT WORK? 101=head1 HOW DOES IT WORK?
89 102
98Afterwards, you create a list of files and modules you want to include, 111Afterwards, you create a list of files and modules you want to include,
99and then either build a new perl binary (that acts just like a normal perl 112and then either build a new perl binary (that acts just like a normal perl
100except everything is compiled in), or you create bundle files (basically C 113except everything is compiled in), or you create bundle files (basically C
101sources you can use to embed all files into your project). 114sources you can use to embed all files into your project).
102 115
103This step is very fast (a few seconds if PPI is not used for stripping, 116This step is very fast (a few seconds if PPI is not used for stripping, or
104more seconds otherwise, as PPI is very slow), and can be tweaked and 117the stripped files are in the cache), and can be tweaked and repeated as
105repeated as often as necessary. 118often as necessary.
106 119
107=head1 THE F<STATICPERL> SCRIPT 120=head1 THE F<STATICPERL> SCRIPT
108 121
109This module installs a script called F<staticperl> into your perl 122This module installs a script called F<staticperl> into your perl
110binary directory. The script is fully self-contained, and can be used 123binary directory. The script is fully self-contained, and can be used
184command by specifying all the directories with modules in them that you 197command by specifying all the directories with modules in them that you
185want to have built. 198want to have built.
186 199
187=item F<staticperl clean> 200=item F<staticperl clean>
188 201
189Runs F<make distclean> in the perl source directory (and potentially 202Deletes the perl source directory (and potentially cleans up other
190cleans up other intermediate files). This can be used to clean up 203intermediate files). This can be used to clean up files only needed for
191intermediate files without removing the installed perl interpreter. 204building perl, without removing the installed perl interpreter, or to
205force a re-build from scratch.
206
207At the moment, it doesn't delete downloaded tarballs.
192 208
193=item F<staticperl distclean> 209=item F<staticperl distclean>
194 210
195This wipes your complete F<~/.staticperl> directory. Be careful with this, 211This wipes your complete F<~/.staticperl> directory. Be careful with this,
196it nukes your perl download, perl sources, perl distribution and any 212it nukes your perl download, perl sources, perl distribution and any
236(required by L<AnyEvent::HTTPD>) implements various URI schemes as extra 252(required by L<AnyEvent::HTTPD>) implements various URI schemes as extra
237modules - since L<AnyEvent::HTTPD> only needs C<http> URIs, we only need 253modules - since L<AnyEvent::HTTPD> only needs C<http> URIs, we only need
238to include that module. I found out about these dependencies by carefully 254to include that module. I found out about these dependencies by carefully
239watching any error messages about missing modules... 255watching any error messages about missing modules...
240 256
257Instead of building a new perl binary, you can also build a standalone
258application:
259
260 # build the app
261 staticperl mkapp app --boot eg/httpd \
262 -MAnyEvent::Impl::Perl -MAnyEvent::HTTPD -MURI::http
263
264 # run it
265 ./app
266
241=head3 OPTION PROCESSING 267=head3 OPTION PROCESSING
242 268
243All options can be given as arguments on the command line (typically 269All options can be given as arguments on the command line (typically
244using long (e.g. C<--verbose>) or short option (e.g. C<-v>) style). Since 270using long (e.g. C<--verbose>) or short option (e.g. C<-v>) style). Since
245specifying a lot of modules can make the command line very cumbersome, 271specifying a lot of modules can make the command line very cumbersome,
281 307
282The default is C<pod>, which uses the L<Pod::Strip> module to remove all 308The default is C<pod>, which uses the L<Pod::Strip> module to remove all
283pod documentation, which is very fast and reduces file size a lot. 309pod documentation, which is very fast and reduces file size a lot.
284 310
285The C<ppi> method uses L<PPI> to parse and condense the perl sources. This 311The C<ppi> method uses L<PPI> to parse and condense the perl sources. This
286saves a lot more than just L<Pod::Strip>, and is generally safer, but 312saves a lot more than just L<Pod::Strip>, and is generally safer,
287is also a lot slower, so is best used for production builds. Note that 313but is also a lot slower (some files take almost a minute to strip -
288this method doesn't optimise for raw file size, but for best compression 314F<staticperl> maintains a cache of stripped files to speed up subsequent
289(that means that the uncompressed file size is a bit larger, but the files 315runs for this reason). Note that this method doesn't optimise for raw file
290compress better, e.g. with F<upx>). 316size, but for best compression (that means that the uncompressed file size
317is a bit larger, but the files compress better, e.g. with F<upx>).
291 318
319Last not least, if you need accurate line numbers in error messages,
292Last not least, in the unlikely case where C<pod> is too slow, or some 320or in the unlikely case where C<pod> is too slow, or some module gets
293module gets mistreated, you can specify C<none> to not mangle included 321mistreated, you can specify C<none> to not mangle included perl sources in
294perl sources in any way. 322any way.
295 323
296=item --perl 324=item --perl
297 325
298After writing out the bundle files, try to link a new perl interpreter. It 326After writing out the bundle files, try to link a new perl interpreter. It
299will be called F<perl> and will be left in the current working 327will be called F<perl> and will be left in the current working
302This switch is automatically used when F<staticperl> is invoked with the 330This switch is automatically used when F<staticperl> is invoked with the
303C<mkperl> command (instead of C<mkbundle>): 331C<mkperl> command (instead of C<mkbundle>):
304 332
305 # build a new ./perl with only common::sense in it - very small :) 333 # build a new ./perl with only common::sense in it - very small :)
306 staticperl mkperl -Mcommon::sense 334 staticperl mkperl -Mcommon::sense
335
336=item --app name
337
338After writing out the bundle files, try to link a new standalone
339program. It will be called C<name>, and the bundle files get removed after
340linking it.
341
342The difference to the (mutually exclusive) C<--perl> option is that the
343binary created by this option will not try to act as a perl interpreter -
344instead it will simply initialise the perl interpreter, clean it up and
345exit.
346
347This switch is automatically used when F<staticperl> is invoked with the
348C<mkapp> command (instead of C<mkbundle>):
349
350To let it do something useful you I<must> add some boot code, e.g. with
351the C<--boot> option.
352
353Example: create a standalone perl binary that will execute F<appfile> when
354it is started.
355
356 staticperl mkbundle --app myexe --boot appfile
307 357
308=item --use module | -Mmodule 358=item --use module | -Mmodule
309 359
310Include the named module and all direct dependencies. This is done by 360Include the named module and all direct dependencies. This is done by
311C<require>'ing the module in a subprocess and tracing which other modules 361C<require>'ing the module in a subprocess and tracing which other modules
366(using a C<require>) before anything else when the new perl is 416(using a C<require>) before anything else when the new perl is
367initialised. This can be used to modify C<@INC> or anything else before 417initialised. This can be used to modify C<@INC> or anything else before
368the perl interpreter executes scripts given on the command line (or via 418the perl interpreter executes scripts given on the command line (or via
369C<-e>). This works even in an embedded interpreter. 419C<-e>). This works even in an embedded interpreter.
370 420
371=item --add "file" | --add "file alias" 421=item --incglob pattern
422
423This goes through all library directories and tries to match any F<.pm>
424and F<.pl> files against the extended glob pattern (see below). If a file
425matches, it is added. This switch will automatically detect L<AutoLoader>
426files and the required link libraries for XS modules, but it will I<not>
427scan the file for dependencies (at the moment).
428
429This is mainly useful to include "everything":
430
431 --incglob '*'
432
433Or to include perl libraries, or trees of those, such as the unicode
434database files needed by many other modules:
435
436 --incglob '/unicore/**.pl'
437
438=item --add file | --add "file alias"
372 439
373Adds the given (perl) file into the bundle (and optionally call it 440Adds the given (perl) file into the bundle (and optionally call it
374"alias"). This is useful to include any custom files into the bundle. 441"alias"). This is useful to include any custom files into the bundle.
375 442
376Example: embed the file F<httpd> as F<httpd.pm> when creating the bundle. 443Example: embed the file F<httpd> as F<httpd.pm> when creating the bundle.
381 448
382 # specification file 449 # specification file
383 add file1 myfiles/file1 450 add file1 myfiles/file1
384 add file2 myfiles/file2 451 add file2 myfiles/file2
385 add file3 myfiles/file3 452 add file3 myfiles/file3
453
454=item --binadd file | --add "file alias"
455
456Just like C<--add>, except that it treats the file as binary and adds it
457without any processing.
458
459You should probably add a C</> prefix to avoid clashing with embedded
460perl files (whose paths do not start with C</>), and/or use a special
461directory, such as C</res/name>.
462
463You can later get a copy of these files by calling C<staticperl::find
464"alias">.
465
466=item --include pattern | -i pattern | --exclude pattern | -x pattern
467
468These two options define an include/exclude filter that is used after all
469files selected by the other options have been found. Each include/exclude
470is applied to all files found so far - an include makes sure that the
471given files will be part of the resulting file set, an exclude will
472exclude files. The patterns are "extended glob patterns" (see below).
473
474For example, to include everything, except C<Devel> modules, but still
475include F<Devel::PPPort>, you could use this:
476
477 --incglob '*' -i '/Devel/PPPort.pm' -x '/Devel/**'
386 478
387=item --static 479=item --static
388 480
389When C<--perl> is also given, link statically instead of dynamically. The 481When C<--perl> is also given, link statically instead of dynamically. The
390default is to link the new perl interpreter fully dynamic (that means all 482default is to link the new perl interpreter fully dynamic (that means all
395systems based on GNU libc don't really support it in a usable fashion 487systems based on GNU libc don't really support it in a usable fashion
396either. Try uClibc if you want to create fully statically linked 488either. Try uClibc if you want to create fully statically linked
397executables, or try the C<--staticlibs> option to link only some libraries 489executables, or try the C<--staticlibs> option to link only some libraries
398statically. 490statically.
399 491
492=item --staticlib libname
493
494When not linking fully statically, this option allows you to link specific
495libraries statically. What it does is simply replace all occurances of
496C<-llibname> with the GCC-specific C<-Wl,-Bstatic -llibname -Wl,-Bdynamic>
497option.
498
499This will have no effect unless the library is actually linked against,
500specifically, C<--staticlib> will not link against the named library
501unless it would be linked against anyway.
502
503Example: link libcrypt statically into the binary.
504
505 staticperl mkperl -MIO::AIO --staticlib crypt
506
507 # ldopts might nwo contain:
508 # -lm -Wl,-Bstatic -lcrypt -Wl,-Bdynamic -lpthread
509
400=item any other argument 510=item any other argument
401 511
402Any other argument is interpreted as a bundle specification file, which 512Any other argument is interpreted as a bundle specification file, which
403supports most long options (without extra quoting), one option per line. 513supports most long options (without extra quoting), one option per line.
404 514
405=back 515=back
406 516
517=head3 EXTENDED GLOB PATTERNS
518
519Some options of F<staticperl mkbundle> expect an I<extended glob
520pattern>. This is neither a normal shell glob nor a regex, but something
521in between. The idea has been copied from rsync, and there are the current
522matching rules:
523
524=over 4
525
526=item Patterns starting with F</> will be a anchored at the root of the library tree.
527
528That is, F</unicore> will match the F<unicore> directory in C<@INC>, but
529nothing inside, and neither any other file or directory called F<unicore>
530anywhere else in the hierarchy.
531
532=item Patterns not starting with F</> will be anchored at the end of the path.
533
534That is, F<idna.pl> will match any file called F<idna.pl> anywhere in the
535hierarchy, but not any directories of the same name.
536
537=item A F<*> matches any single component.
538
539That is, F</unicore/*.pl> would match all F<.pl> files directly inside
540C</unicore>, not any deeper level F<.pl> files. Or in other words, F<*>
541will not match slashes.
542
543=item A F<**> matches anything.
544
545That is, F</unicore/**.pl> would match all F<.pl> files under F</unicore>,
546no matter how deeply nested they are inside subdirectories.
547
548=item A F<?> matches a single character within a component.
549
550That is, F</Encode/??.pm> matches F</Encode/JP.pm>, but not the
551hypothetical F</Encode/J/.pm>, as F<?> does not match F</>.
552
553=back
554
407=head2 F<STATCPERL> CONFIGURATION AND HOOKS 555=head2 F<STATICPERL> CONFIGURATION AND HOOKS
408 556
409During (each) startup, F<staticperl> tries to source the following shell 557During (each) startup, F<staticperl> tries to source the following shell
410files in order: 558files in order:
411 559
412 /etc/staticperlrc 560 /etc/staticperlrc
428=item C<EMAIL> 576=item C<EMAIL>
429 577
430The e-mail address of the person who built this binary. Has no good 578The e-mail address of the person who built this binary. Has no good
431default, so should be specified by you. 579default, so should be specified by you.
432 580
433=back 581=item C<CPAN>
434 582
583The URL of the CPAN mirror to use (e.g. L<http://mirror.netcologne.de/cpan/>).
584
585=item C<EXTRA_MODULES>
586
587Additional modules installed during F<staticperl install>. Here you can
588set which modules you want have to installed from CPAN.
589
590Example: I really really need EV, AnyEvent, Coro and AnyEvent::AIO.
591
592 EXTRA_MODULES="EV AnyEvent Coro AnyEvent::AIO"
593
594Note that you can also use a C<postinstall> hook to achieve this, and
595more.
596
597=back
598
435=head4 Variables you I<might want> to override 599=head4 Variables you might I<want> to override
436 600
437=over 4 601=over 4
438 602
603=item C<STATICPERL>
604
605The directory where staticperl stores all its files
606(default: F<~/.staticperl>).
607
608=item C<PERL_MM_USE_DEFAULT>, C<EV_EXTRA_DEFS>, ...
609
610Usually set to C<1> to make modules "less inquisitive" during their
611installation, you can set any environment variable you want - some modules
612(such as L<Coro> or L<EV>) use environment variables for further tweaking.
613
439=item C<PERLVER> 614=item C<PERL_VERSION>
440 615
441The perl version to install - default is currently C<5.12.2>, but C<5.8.9> 616The perl version to install - default is currently C<5.12.2>, but C<5.8.9>
442is also a good choice (5.8.9 is much smaller than 5.12.2, while 5.10.1 is 617is also a good choice (5.8.9 is much smaller than 5.12.2, while 5.10.1 is
443about as big as 5.12.2). 618about as big as 5.12.2).
444 619
445=item C<CPAN> 620=item C<PERL_PREFIX>
446 621
447The URL of the CPAN mirror to use (e.g. L<http://mirror.netcologne.de/cpan/>). 622The prefix where perl gets installed (default: F<$STATICPERL/perl>),
623i.e. where the F<bin> and F<lib> subdirectories will end up.
624
625=item C<PERL_CONFIGURE>
626
627Additional Configure options - these are simply passed to the perl
628Configure script. For example, if you wanted to enable dynamic loading,
629you could pass C<-Dusedl>. To enable ithreads (Why would you want that
630insanity? Don't! Use L<forks> instead!) you would pass C<-Duseithreads>
631and so on.
632
633More commonly, you would either activate 64 bit integer support
634(C<-Duse64bitint>), or disable large files support (-Uuselargefiles), to
635reduce filesize further.
448 636
449=item C<PERL_CPPFLAGS>, C<PERL_OPTIMIZE>, C<PERL_LDFLAGS>, C<PERL_LIBS> 637=item C<PERL_CPPFLAGS>, C<PERL_OPTIMIZE>, C<PERL_LDFLAGS>, C<PERL_LIBS>
450 638
451These flags are passed to perl's F<Configure> script, and are generally 639These flags are passed to perl's F<Configure> script, and are generally
452optimised for small size (at the cost of performance). Since they also 640optimised for small size (at the cost of performance). Since they also
453contain subtle workarounds around various build issues, changing these 641contain subtle workarounds around various build issues, changing these
454usually requires understanding their default values - best look at the top 642usually requires understanding their default values - best look at the top
455of the F<staticperl> script for more info on these. 643of the F<staticperl> script for more info on these.
456 644
457=item C<STATICPERL>
458
459The directory where staticperl stores all its files
460(default: F<~/.staticperl>).
461
462=item C<PREFIX>
463
464The prefix where perl gets installed (default: F<$STATICPERL/perl>),
465i.e. where the F<bin> and F<lib> subdirectories will end up.
466
467=item C<PERL_MM_USE_DEFAULT>, C<EV_EXTRA_DEFS>, others
468
469Usually set to C<1> to make modules "less inquisitive" during their
470installation, you can set any environment variable you want - some modules
471(such as L<Coro> or L<EV>) use environment variables for further tweaking.
472
473=item C<EXTRA_MODULES>
474
475Additional modules installed during F<staticperl install>. Here you can
476set which modules you want have to installed from CPAN.
477
478Example: I really really need EV, AnyEvent, Coro and IO::AIO.
479
480 EXTRA_MODULES="EV AnyEvent Coro IO::AIO"
481
482Note that you can also use a C<postinstall> hook to achieve this, and
483more.
484
485=back 645=back
486 646
487=head4 Variables you I<probably do not want> to override 647=head4 Variables you probably I<do not want> to override
488 648
489=over 4 649=over 4
490 650
491=item C<MKBUNDLE> 651=item C<MKBUNDLE>
492 652
517 instcpan Anyevent::AIO AnyEvent::HTTPD 677 instcpan Anyevent::AIO AnyEvent::HTTPD
518 } 678 }
519 679
520=over 4 680=over 4
521 681
682=item preconfigure
683
684Called just before running F<./Configur> in the perl source
685directory. Current working directory is the perl source directory.
686
687This can be used to set any C<PERL_xxx> variables, which might be costly
688to compute.
689
522=item postconfigure 690=item postconfigure
523 691
524Called after configuring, but before building perl. Current working 692Called after configuring, but before building perl. Current working
525directory is the perl source directory. 693directory is the perl source directory.
526 694
527Could be used to tailor/patch config.sh (followed by F<./Configure -S>) or 695Could be used to tailor/patch config.sh (followed by F<sh Configure -S>)
528do any other modifications. 696or do any other modifications.
529 697
530=item postbuild 698=item postbuild
531 699
532Called after building, but before installing perl. Current working 700Called after building, but before installing perl. Current working
533directory is the perl source directory. 701directory is the perl source directory.
548The script must return with a zero exit status, or the installation will 716The script must return with a zero exit status, or the installation will
549fail. 717fail.
550 718
551=back 719=back
552 720
721=head1 ANATOMY OF A BUNDLE
722
723When not building a new perl binary, C<mkbundle> will leave a number of
724files in the current working directory, which can be used to embed a perl
725interpreter in your program.
726
727Intimate knowledge of L<perlembed> and preferably some experience with
728embedding perl is highly recommended.
729
730C<mkperl> (or the C<--perl> option) basically does this to link the new
731interpreter (it also adds a main program to F<bundle.>):
732
733 $Config{cc} $(cat bundle.ccopts) -o perl bundle.c $(cat bundle.ldopts)
734
735=over 4
736
737=item bundle.h
738
739A header file that contains the prototypes of the few symbols "exported"
740by bundle.c, and also exposes the perl headers to the application.
741
742=over 4
743
744=item staticperl_init ()
745
746Initialises the perl interpreter. You can use the normal perl functions
747after calling this function, for example, to define extra functions or
748to load a .pm file that contains some initialisation code, or the main
749program function:
750
751 XS (xsfunction)
752 {
753 dXSARGS;
754
755 // now we have items, ST(i) etc.
756 }
757
758 static void
759 run_myapp(void)
760 {
761 staticperl_init ();
762 newXSproto ("myapp::xsfunction", xsfunction, __FILE__, "$$;$");
763 eval_pv ("require myapp::main", 1); // executes "myapp/main.pm"
764 }
765
766=item staticperl_xs_init (pTHX)
767
768Sometimes you need direct control over C<perl_parse> and C<perl_run>, in
769which case you do not want to use C<staticperl_init> but call them on your
770own.
771
772Then you need this function - either pass it directly as the C<xs_init>
773function to C<perl_parse>, or call it from your own C<xs_init> function.
774
775=item staticperl_cleanup ()
776
777In the unlikely case that you want to destroy the perl interpreter, here
778is the corresponding function.
779
780=item PerlInterpreter *staticperl
781
782The perl interpreter pointer used by staticperl. Not normally so useful,
783but there it is.
784
785=back
786
787=item bundle.ccopts
788
789Contains the compiler options required to compile at least F<bundle.c> and
790any file that includes F<bundle.h> - you should probably use it in your
791C<CFLAGS>.
792
793=item bundle.ldopts
794
795The linker options needed to link the final program.
796
797=back
798
799=head1 RUNTIME FUNCTIONALITY
800
801Binaries created with C<mkbundle>/C<mkperl> contain extra functions, which
802are required to access the bundled perl sources, but might be useful for
803other purposes.
804
805In addition, for the embedded loading of perl files to work, F<staticperl>
806overrides the C<@INC> array.
807
808=over 4
809
810=item $file = staticperl::find $path
811
812Returns the data associated with the given C<$path>
813(e.g. C<Digest/MD5.pm>, C<auto/POSIX/autosplit.ix>), which is basically
814the UNIX path relative to the perl library directory.
815
816Returns C<undef> if the file isn't embedded.
817
818=item @paths = staticperl::list
819
820Returns the list of all paths embedded in this binary.
821
822=back
823
824=head1 FULLY STATIC BINARIES - BUILDROOT
825
826To make truly static (Linux-) libraries, you might want to have a look at
827buildroot (L<http://buildroot.uclibc.org/>).
828
829Buildroot is primarily meant to set up a cross-compile environment (which
830is not so useful as perl doesn't quite like cross compiles), but it can also compile
831a chroot environment where you can use F<staticperl>.
832
833To do so, download buildroot, and enable "Build options => development
834files in target filesystem" and optionally "Build options => gcc
835optimization level (optimize for size)". At the time of writing, I had
836good experiences with GCC 4.4.x but not GCC 4.5.
837
838To minimise code size, I used C<-pipe -ffunction-sections -fdata-sections
839-finline-limit=8 -fno-builtin-strlen -mtune=i386>. The C<-mtune=i386>
840doesn't decrease codesize much, but it makes the file much more
841compressible.
842
843If you don't need Coro or threads, you can go with "linuxthreads.old" (or
844no thread support). For Coro, it is highly recommended to switch to a
845uClibc newer than 0.9.31 (at the time of this writing, I used the 20101201
846snapshot) and enable NPTL, otherwise Coro needs to be configured with the
847ultra-slow pthreads backend to work around linuxthreads bugs (it also uses
848twice the address space needed for stacks).
849
850If you use C<linuxthreads.old>, then you should also be aware that
851uClibc shares C<errno> between all threads when statically linking. See
852L<http://lists.uclibc.org/pipermail/uclibc/2010-June/044157.html> for a
853workaround (And L<https://bugs.uclibc.org/2089> for discussion).
854
855C<ccache> support is also recommended, especially if you want
856to play around with buildroot options. Enabling the C<miniperl>
857package will probably enable all options required for a successful
858perl build. F<staticperl> itself additionally needs either C<wget>
859(recommended, for CPAN) or C<curl>.
860
861As for shells, busybox should provide all that is needed, but the default
862busybox configuration doesn't include F<comm> which is needed by perl -
863either make a custom busybox config, or compile coreutils.
864
865For the latter route, you might find that bash has some bugs that keep
866it from working properly in a chroot - either use dash (and link it to
867F</bin/sh> inside the chroot) or link busybox to F</bin/sh>, using it's
868built-in ash shell.
869
870Finally, you need F</dev/null> inside the chroot for many scripts to work
871- F<cp /dev/null output/target/dev> or bind-mounting your F</dev> will
872both provide this.
873
874After you have compiled and set up your buildroot target, you can copy
875F<staticperl> from the C<App::Staticperl> distribution or from your
876perl f<bin> directory (if you installed it) into the F<output/target>
877filesystem, chroot inside and run it.
878
879=head1 RECIPES / SPECIFIC MODULES
880
881This section contains some common(?) recipes and information about
882problems with some common modules or perl constructs that require extra
883files to be included.
884
885=head2 MODULES
886
887=over 4
888
889=item utf8
890
891Some functionality in the utf8 module, such as swash handling (used
892for unicode character ranges in regexes) is implemented in the
893C<"utf8_heavy.pl"> library:
894
895 -M'"utf8_heavy.pl"'
896
897Many Unicode properties in turn are defined in separate modules,
898such as C<"unicore/Heavy.pl"> and more specific data tables such as
899C<"unicore/To/Digit.pl"> or C<"unicore/lib/Perl/Word.pl">. These tables
900are big (7MB uncompressed, although F<staticperl> contains special
901handling for those files), so including them on demand by your application
902only might pay off.
903
904To simply include the whole unicode database, use:
905
906 --incglob '/unicore/*.pl'
907
908=item AnyEvent
909
910AnyEvent needs a backend implementation that it will load in a delayed
911fashion. The L<AnyEvent::Impl::Perl> backend is the default choice
912for AnyEvent if it can't find anything else, and is usually a safe
913fallback. If you plan to use e.g. L<EV> (L<POE>...), then you need to
914include the L<AnyEvent::Impl::EV> (L<AnyEvent::Impl::POE>...) backend as
915well.
916
917If you want to handle IRIs or IDNs (L<AnyEvent::Util> punycode and idn
918functions), you also need to include C<"AnyEvent/Util/idna.pl"> and
919C<"AnyEvent/Util/uts46data.pl">.
920
921=item Carp
922
923Carp had (in older versions of perl) a dependency on L<Carp::Heavy>. As of
924perl 5.12.2 (maybe earlier), this dependency no longer exists.
925
926=item Config
927
928The F<perl -V> switch (as well as many modules) needs L<Config>, which in
929turn might need L<"Config_heavy.pl">. Including the latter gives you
930both.
931
932=item Term::ReadLine::Perl
933
934Also needs L<Term::ReadLine::readline>.
935
936=item URI
937
938URI implements schemes as separate modules - the generic URL scheme is
939implemented in L<URI::_generic>, HTTP is implemented in L<URI::http>. If
940you need to use any of these schemes, you should include these manually.
941
942=back
943
944=head2 RECIPES
945
946=over 4
947
948=item Linking everything in
949
950To link just about everything installed in the perl library into a new
951perl, try this:
952
953 staticperl mkperl --strip ppi --incglob '*'
954
955=item Getting rid of netdb function
956
957The perl core has lots of netdb functions (C<getnetbyname>, C<getgrent>
958and so on) that few applications use. You can avoid compiling them in by
959putting the following fragment into a C<preconfigure> hook:
960
961 preconfigure() {
962 for sym in \
963 d_getgrnam_r d_endgrent d_endgrent_r d_endhent \
964 d_endhostent_r d_endnent d_endnetent_r d_endpent \
965 d_endprotoent_r d_endpwent d_endpwent_r d_endsent \
966 d_endservent_r d_getgrent d_getgrent_r d_getgrgid_r \
967 d_getgrnam_r d_gethbyaddr d_gethent d_getsbyport \
968 d_gethostbyaddr_r d_gethostbyname_r d_gethostent_r \
969 d_getlogin_r d_getnbyaddr d_getnbyname d_getnent \
970 d_getnetbyaddr_r d_getnetbyname_r d_getnetent_r \
971 d_getpent d_getpbyname d_getpbynumber d_getprotobyname_r \
972 d_getprotobynumber_r d_getprotoent_r d_getpwent \
973 d_getpwent_r d_getpwnam_r d_getpwuid_r d_getsent \
974 d_getservbyname_r d_getservbyport_r d_getservent_r \
975 d_getspnam_r d_getsbyname
976 # d_gethbyname
977 do
978 PERL_CONFIGURE="$PERL_CONFIGURE -U$sym"
979 done
980 }
981
982This mostly gains space when linking staticaly, as the functions will
983liekly not be linked in. The gain for dynamically-linked binaries is
984smaller.
985
986Also, this leaves C<gethostbyname> in - not only is it actually used
987often, the L<Socket> module also exposes it, so leaving it out usually
988gains little. Why Socket exposes a C function that is in the core already
989is anybody's guess.
990
991=back
992
553=head1 AUTHOR 993=head1 AUTHOR
554 994
555 Marc Lehmann <schmorp@schmorp.de> 995 Marc Lehmann <schmorp@schmorp.de>
556 http://software.schmorp.de/pkg/staticperl.html 996 http://software.schmorp.de/pkg/staticperl.html

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines