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.19 by root, Fri Dec 10 15:25:24 2010 UTC vs.
Revision 1.23 by root, Mon Dec 13 18:08:01 2010 UTC

… …
40 40
41With F<uClibc> and F<upx> on x86, you can create a single 500kb binary 41With F<uClibc> and F<upx> on x86, you can create a single 500kb binary
42that contains perl and 100 modules such as POSIX, AnyEvent, EV, IO::AIO, 42that contains perl and 100 modules such as POSIX, AnyEvent, EV, IO::AIO,
43Coro and so on. Or any other choice of modules. 43Coro and so on. Or any other choice of modules.
44 44
45To see how this turns out, you can try out smallperl and bigperl, two
46pre-built static and compressed perl binaries with many and even more
47modules: just follow the links at L<http://staticperl.schmorp.de/>.
48
45The created files do not need write access to the file system (like PAR 49The created files do not need write access to the file system (like PAR
46does). In fact, since this script is in many ways similar to PAR::Packer, 50does). In fact, since this script is in many ways similar to PAR::Packer,
47here are the differences: 51here are the differences:
48 52
49=over 4 53=over 4
… …
118often as necessary. 122often as necessary.
119 123
120=head1 THE F<STATICPERL> SCRIPT 124=head1 THE F<STATICPERL> SCRIPT
121 125
122This module installs a script called F<staticperl> into your perl 126This module installs a script called F<staticperl> into your perl
123binary directory. The script is fully self-contained, and can be used 127binary directory. The script is fully self-contained, and can be
124without perl (for example, in an uClibc chroot environment). In fact, 128used without perl (for example, in an uClibc chroot environment). In
125it can be extracted from the C<App::Staticperl> distribution tarball as 129fact, it can be extracted from the C<App::Staticperl> distribution
126F<bin/staticperl>, without any installation. 130tarball as F<bin/staticperl>, without any installation. The
131newest (possibly alpha) version can also be downloaded from
132L<http://staticperl.schmorp.de/staticperl>.
127 133
128F<staticperl> interprets the first argument as a command to execute, 134F<staticperl> interprets the first argument as a command to execute,
129optionally followed by any parameters. 135optionally followed by any parameters.
130 136
131There are two command categories: the "phase 1" commands which deal with 137There are two command categories: the "phase 1" commands which deal with
… …
152 158
153To force recompilation or reinstallation, you need to run F<staticperl 159To force recompilation or reinstallation, you need to run F<staticperl
154distclean> first. 160distclean> first.
155 161
156=over 4 162=over 4
163
164=item F<staticperl version>
165
166Prints some info about the version of the F<staticperl> script you are using.
157 167
158=item F<staticperl fetch> 168=item F<staticperl fetch>
159 169
160Runs only the download and unpack phase, unless this has already happened. 170Runs only the download and unpack phase, unless this has already happened.
161 171
… …
311 321
312All this step does is potentially reduce the number of files already 322All this step does is potentially reduce the number of files already
313selected or found in phase 1. 323selected or found in phase 1.
314 324
315=item 3. find all modules (== F<.pm> files), gather their static archives 325=item 3. find all modules (== F<.pm> files), gather their static archives
316(F<.a>) and AutoLoader splitfiles (F<.ix> and F<.al> files) and find any 326(F<.a>) and AutoLoader splitfiles (F<.ix> and F<.al> files), find any
317extra libraries they need for linking (F<extralibs.ld>). 327extra libraries they need for linking (F<extralibs.ld>) and optionally
328evaluate any F<.packlist> files.
318 329
319This step is required to link against XS extensions and also adds files 330This step is required to link against XS extensions and also adds files
320required for L<AutoLoader> to do it's job. 331required for L<AutoLoader> to do it's job.
321 332
322=back 333=back
… …
453(using a C<require>) before anything else when the new perl is 464(using a C<require>) before anything else when the new perl is
454initialised. This can be used to modify C<@INC> or anything else before 465initialised. This can be used to modify C<@INC> or anything else before
455the perl interpreter executes scripts given on the command line (or via 466the perl interpreter executes scripts given on the command line (or via
456C<-e>). This works even in an embedded interpreter. 467C<-e>). This works even in an embedded interpreter.
457 468
469=item --usepacklist
470
471Read F<.packlist> files for each distribution that happens to match a
472module name you specified. Sounds weird, and it is, so expect semantics to
473change somehow in the future.
474
475The idea is that most CPAN distributions have a F<.pm> file that matches
476the name of the distribution (which is rather reasonable after all).
477
478If this switch is enabled, then if any of the F<.pm> files that have been
479selected match an install distribution, then all F<.pm>, F<.pl>, F<.al>
480and F<.ix> files installed by this distribution are also included.
481
482For example, using this switch, when the L<URI> module is specified, then
483all L<URI> submodules that have been installed via the CPAN distribution
484are included as well, so you don't have to manually specify them.
485
458=item --incglob pattern 486=item --incglob pattern
459 487
460This goes through all library directories and tries to match any F<.pm> 488This goes through all library directories and tries to match any F<.pm>
461and F<.pl> files against the extended glob pattern (see below). If a file 489and F<.pl> files against the extended glob pattern (see below). If a file
462matches, it is added. This switch will automatically detect L<AutoLoader> 490matches, it is added. This switch will automatically detect L<AutoLoader>
… …
589 617
590=back 618=back
591 619
592=head2 F<STATICPERL> CONFIGURATION AND HOOKS 620=head2 F<STATICPERL> CONFIGURATION AND HOOKS
593 621
594During (each) startup, F<staticperl> tries to source the following shell 622During (each) startup, F<staticperl> tries to source some shell files to
623allow you to fine-tune/override configuration settings.
624
625In them you can override shell variables, or define shell functions
626("hooks") to be called at specific phases during installation. For
627example, you could define a C<postinstall> hook to install additional
628modules from CPAN each time you start from scratch.
629
630If the env variable C<$STATICPERLRC> is set, then F<staticperl> will try
631to source the file named with it only. Otherwise, it tries the following
595files in order: 632shell files in order:
596 633
597 /etc/staticperlrc 634 /etc/staticperlrc
598 ~/.staticperlrc 635 ~/.staticperlrc
599 $STATICPERL/rc 636 $STATICPERL/rc
600
601They can be used to override shell variables, or define functions to be
602called at specific phases.
603 637
604Note that the last file is erased during F<staticperl distclean>, so 638Note that the last file is erased during F<staticperl distclean>, so
605generally should not be used. 639generally should not be used.
606 640
607=head3 CONFIGURATION VARIABLES 641=head3 CONFIGURATION VARIABLES
… …
669 703
670More commonly, you would either activate 64 bit integer support 704More commonly, you would either activate 64 bit integer support
671(C<-Duse64bitint>), or disable large files support (-Uuselargefiles), to 705(C<-Duse64bitint>), or disable large files support (-Uuselargefiles), to
672reduce filesize further. 706reduce filesize further.
673 707
674=item C<PERL_CPPFLAGS>, C<PERL_OPTIMIZE>, C<PERL_LDFLAGS>, C<PERL_LIBS> 708=item C<PERL_CC>, C<PERL_CPPFLAGS>, C<PERL_OPTIMIZE>, C<PERL_LDFLAGS>, C<PERL_LIBS>
675 709
676These flags are passed to perl's F<Configure> script, and are generally 710These flags are passed to perl's F<Configure> script, and are generally
677optimised for small size (at the cost of performance). Since they also 711optimised for small size (at the cost of performance). Since they also
678contain subtle workarounds around various build issues, changing these 712contain subtle workarounds around various build issues, changing these
679usually requires understanding their default values - best look at the top 713usually requires understanding their default values - best look at the top
… …
682=back 716=back
683 717
684=head4 Variables you probably I<do not want> to override 718=head4 Variables you probably I<do not want> to override
685 719
686=over 4 720=over 4
721
722=item C<MAKE>
723
724The make command to use - default is C<make>.
687 725
688=item C<MKBUNDLE> 726=item C<MKBUNDLE>
689 727
690Where F<staticperl> writes the C<mkbundle> command to 728Where F<staticperl> writes the C<mkbundle> command to
691(default: F<$STATICPERL/mkbundle>). 729(default: F<$STATICPERL/mkbundle>).
… …
953 991
954If you want to handle IRIs or IDNs (L<AnyEvent::Util> punycode and idn 992If you want to handle IRIs or IDNs (L<AnyEvent::Util> punycode and idn
955functions), you also need to include C<"AnyEvent/Util/idna.pl"> and 993functions), you also need to include C<"AnyEvent/Util/idna.pl"> and
956C<"AnyEvent/Util/uts46data.pl">. 994C<"AnyEvent/Util/uts46data.pl">.
957 995
996Or you can use C<--usepacklist> and specify C<-MAnyEvent> to include
997everything.
998
958=item Carp 999=item Carp
959 1000
960Carp had (in older versions of perl) a dependency on L<Carp::Heavy>. As of 1001Carp had (in older versions of perl) a dependency on L<Carp::Heavy>. As of
961perl 5.12.2 (maybe earlier), this dependency no longer exists. 1002perl 5.12.2 (maybe earlier), this dependency no longer exists.
962 1003
… …
966turn might need L<"Config_heavy.pl">. Including the latter gives you 1007turn might need L<"Config_heavy.pl">. Including the latter gives you
967both. 1008both.
968 1009
969=item Term::ReadLine::Perl 1010=item Term::ReadLine::Perl
970 1011
971Also needs L<Term::ReadLine::readline>. 1012Also needs L<Term::ReadLine::readline>, or C<--usepacklist>.
972 1013
973=item URI 1014=item URI
974 1015
975URI implements schemes as separate modules - the generic URL scheme is 1016URI implements schemes as separate modules - the generic URL scheme is
976implemented in L<URI::_generic>, HTTP is implemented in L<URI::http>. If 1017implemented in L<URI::_generic>, HTTP is implemented in L<URI::http>. If
977you need to use any of these schemes, you should include these manually. 1018you need to use any of these schemes, you should include these manually,
1019or use C<--usepacklist>.
978 1020
979=back 1021=back
980 1022
981=head2 RECIPES 1023=head2 RECIPES
982 1024
… …
1015 PERL_CONFIGURE="$PERL_CONFIGURE -U$sym" 1057 PERL_CONFIGURE="$PERL_CONFIGURE -U$sym"
1016 done 1058 done
1017 } 1059 }
1018 1060
1019This mostly gains space when linking staticaly, as the functions will 1061This mostly gains space when linking staticaly, as the functions will
1020liekly not be linked in. The gain for dynamically-linked binaries is 1062likely not be linked in. The gain for dynamically-linked binaries is
1021smaller. 1063smaller.
1022 1064
1023Also, this leaves C<gethostbyname> in - not only is it actually used 1065Also, this leaves C<gethostbyname> in - not only is it actually used
1024often, the L<Socket> module also exposes it, so leaving it out usually 1066often, the L<Socket> module also exposes it, so leaving it out usually
1025gains little. Why Socket exposes a C function that is in the core already 1067gains little. Why Socket exposes a C function that is in the core already

Diff Legend

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