--- App-Staticperl/staticperl.pod 2010/12/21 19:32:34 1.27 +++ App-Staticperl/staticperl.pod 2010/12/23 14:16:25 1.31 @@ -391,11 +391,14 @@ staticperl mkbundle --use AnyEvent --use AnyEvent::Impl::Perl -Sometimes you want to load old-style "perl libraries" (F<.pl> files), or -maybe other weirdly named files. To do that, you need to quote the name in -single or double quotes. When given on the command line, you probably need -to quote once more to avoid your shell interpreting it. Common cases that -need this are F and F. +Sometimes you want to load old-style "perl libraries" (F<.pl> files), +or maybe other weirdly named files. To do that, you need to quote +the name in single or double quotes (this is because F +I just adds the string after the C - which acts +different when confronted with quoted vs. unquoted strings). When given on +the command line, you probably need to quote once more to avoid your shell +interpreting it. Common cases that need this are F and +F. Example: include the required files for F to work in all its glory (F is included automatically by this). @@ -406,9 +409,10 @@ # bundle specification file use "Config_heavy.pl" -The C<-M>module syntax is included as an alias that might be easier to -remember than C<--use>. Or maybe it confuses people. Time will tell. Or -maybe not. Sigh. +The C<-M>module syntax is included as a convenience that might be easier +to remember than C<--use> - it's the same switch as perl itself uses +to load modules. Or maybe it confuses people. Time will tell. Or maybe +not. Sigh. =item C<--eval> "perl code" | C<-e> "perl code" @@ -457,7 +461,7 @@ --incglob '*' It is also useful for including perl libraries, or trees of those, such as -the unicode database files needed by some perl builtins, the regex engine +the unicode database files needed by some perl built-ins, the regex engine and other modules. --incglob '/unicore/**.pl' @@ -467,7 +471,7 @@ Adds the given (perl) file into the bundle (and optionally call it "alias"). The F is either an absolute path or a path relative to the current directory. If an alias is specified, then this is the name it -will use for C<@INC> searches, otherfile the F will be used as the +will use for C<@INC> searches, otherwise the F will be used as the internal name. This switch is used to include extra files into the bundle. @@ -520,7 +524,7 @@ After all candidate files and modules are added, they are I by a combination of C<--include> and C<--exclude> patterns (there is an -implicit C<--include **> at the end, so if no filters are specified, all +implicit C<--include *> at the end, so if no filters are specified, all files are included). All that this step does is potentially reduce the number of files that are @@ -555,7 +559,7 @@ =over 4 -=item C<--usepacklist> +=item C<--usepacklists> Read F<.packlist> files for each distribution that happens to match a module name you specified. Sounds weird, and it is, so expect semantics to @@ -633,7 +637,7 @@ mistreated, you can specify C to not mangle included perl sources in any way. -=item --perl +=item C<--perl> After writing out the bundle files, try to link a new perl interpreter. It will be called F and will be left in the current working @@ -648,7 +652,7 @@ staticperl mkperl -Mcommon::sense -=item --app name +=item C<--app> F After writing out the bundle files, try to link a new standalone program. It will be called C, and the bundle files get removed after @@ -671,7 +675,7 @@ staticperl mkbundle --app myexe --boot appfile -=item --static +=item C<--static> Add C<-static> to F, which means a fully static (if supported by the OS) executable will be created. This is not immensely @@ -688,10 +692,10 @@ executables, or try the C<--staticlib> option to link only some libraries statically. -=item --staticlib libname +=item C<--staticlib> libname When not linking fully statically, this option allows you to link specific -libraries statically. What it does is simply replace all occurances of +libraries statically. What it does is simply replace all occurrences of C<-llibname> with the GCC-specific C<-Wl,-Bstatic -llibname -Wl,-Bdynamic> option. @@ -699,7 +703,7 @@ specifically, C<--staticlib> will not link against the named library unless it would be linked against anyway. -Example: link libcrypt statically into the binary. +Example: link libcrypt statically into the final binary. staticperl mkperl -MIO::AIO --staticlib crypt @@ -730,7 +734,7 @@ That is, F will match any file called F anywhere in the hierarchy, but not any directories of the same name. -=item A F<*> matches any single component. +=item A F<*> matches anything within a single path component. That is, F would match all F<.pl> files directly inside C, not any deeper level F<.pl> files. Or in other words, F<*> @@ -1031,7 +1035,7 @@ =back -=head1 FULLY STATIC BINARIES - BUILDROOT +=head1 FULLY STATIC BINARIES - UCLIBC AND BUILDROOT To make truly static (Linux-) libraries, you might want to have a look at buildroot (L). @@ -1113,7 +1117,7 @@ To simply include the whole unicode database, use: - --incglob '/unicore/*.pl' + --incglob '/unicore/**.pl' =item AnyEvent @@ -1128,7 +1132,7 @@ functions), you also need to include C<"AnyEvent/Util/idna.pl"> and C<"AnyEvent/Util/uts46data.pl">. -Or you can use C<--usepacklist> and specify C<-MAnyEvent> to include +Or you can use C<--usepacklists> and specify C<-MAnyEvent> to include everything. =item Carp @@ -1144,14 +1148,14 @@ =item Term::ReadLine::Perl -Also needs L, or C<--usepacklist>. +Also needs L, or C<--usepacklists>. =item URI URI implements schemes as separate modules - the generic URL scheme is implemented in L, HTTP is implemented in L. If you need to use any of these schemes, you should include these manually, -or use C<--usepacklist>. +or use C<--usepacklists>. =back @@ -1159,14 +1163,22 @@ =over 4 -=item Linking everything in +=item Just link everything in To link just about everything installed in the perl library into a new -perl, try this: +perl, try this (the first time this runs it will take a long time, as a +lot of files need to be parsed): + + staticperl mkperl -v --strip ppi --incglob '*' + +If you don't mind the extra megabytes, this can be a very effective way of +creating bundles without having to worry about forgetting any modules. - staticperl mkperl --strip ppi --incglob '*' +You get even more useful variants of this method by first selecting +everything, and then excluding stuff you are reasonable sure not to need - +L uses this approach. -=item Getting rid of netdb function +=item Getting rid of netdb functions The perl core has lots of netdb functions (C, C and so on) that few applications use. You can avoid compiling them in by @@ -1193,7 +1205,7 @@ done } -This mostly gains space when linking staticaly, as the functions will +This mostly gains space when linking statically, as the functions will likely not be linked in. The gain for dynamically-linked binaries is smaller.