[ViewVC] Diff of: cvs/App-Staticperl/staticperl.pod

Comparing App-Staticperl/staticperl.pod (file contents):
Revision 1.27 by root, Tue Dec 21 19:32:34 2010 UTC vs.
Revision 1.31 by root, Thu Dec 23 14:16:25 2010 UTC

 Example: include AnyEvent and AnyEvent::Impl::Perl.
    staticperl mkbundle --use AnyEvent --use AnyEvent::Impl::Perl
-Sometimes you want to load old-style "perl libraries" (F<.pl> files), or
+Sometimes you want to load old-style "perl libraries" (F<.pl> files),
-maybe other weirdly named files. To do that, you need to quote the name in
+or maybe other weirdly named files. To do that, you need to quote
-single or double quotes. When given on the command line, you probably need
+the name in single or double quotes (this is because F<staticperl>
-to quote once more to avoid your shell interpreting it. Common cases that
+I<literally> just adds the string after the C<require> - which acts
-need this are F<Config_heavy.pl> and F<utf8_heavy.pl>.
+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<Config_heavy.pl> and
+F<utf8_heavy.pl>.
 Example: include the required files for F<perl -V> to work in all its
 glory (F<Config.pm> is included automatically by this).
    # bourne shell
    staticperl mkbundle --use '"Config_heavy.pl"'
    # bundle specification file
    use "Config_heavy.pl"
-The C<-M>module syntax is included as an alias that might be easier to
+The C<-M>module syntax is included as a convenience that might be easier
-remember than C<--use>. Or maybe it confuses people. Time will tell. Or
+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
-maybe not. Sigh.
+not. Sigh.
 =item C<--eval> "perl code" | C<-e> "perl code"
 Sometimes it is easier (or necessary) to specify dependencies using perl
 code, or maybe one of the modules you use need a special use statement. In
 This is very useful to include "everything":
    --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'
 =item C<--add> F<file> | C<--add> "F<file> alias"
 Adds the given (perl) file into the bundle (and optionally call it
 "alias"). The F<file> 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<file> will be used as the
+will use for C<@INC> searches, otherwise the F<file> will be used as the
 internal name.
 This switch is used to include extra files into the bundle.
 Example: embed the file F<httpd> in the current directory as F<httpd.pm>
 =item Step 2: filter all files using C<--include> and C<--exclude> options.
 After all candidate files and modules are added, they are I<filtered>
 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
 to be included - no new files are added during this step.
 that are added automatically. Only one (F<.packlist> files) is currently
 optional and can be influenced, the others are always included:
 =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
 change somehow in the future.
 Last not least, if you need accurate line numbers in error messages,
 or in the unlikely case where C<pod> is too slow, or some module gets
 mistreated, you can specify C<none> 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<perl> and will be left in the current working
 directory. The bundle files will be removed.
 it will be even smaller than the standard perl interpreter as none of the
 modules of the base distribution (such as L<Fcntl>) will be included.
    staticperl mkperl -Mcommon::sense
-=item --app name
+=item C<--app> F<name>
 After writing out the bundle files, try to link a new standalone
 program. It will be called C<name>, and the bundle files get removed after
 linking it.
 Example: create a standalone perl binary called F<./myexe> that will
 execute F<appfile> when it is started.
    staticperl mkbundle --app myexe --boot appfile
-=item --static
+=item C<--static>
 Add C<-static> to F<bundle.ldopts>, which means a fully static (if
 supported by the OS) executable will be created. This is not immensely
 useful when just creating the bundle files, but is most useful when
 linking a binary with the C<--perl> or C<--app> options.
 systems based on GNU libc don't really support it in a very usable
 fashion either. Try uClibc if you want to create fully statically linked
 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.
 This will have no effect unless the library is actually linked against,
 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
    # ldopts might now contain:
    # -lm -Wl,-Bstatic -lcrypt -Wl,-Bdynamic -lpthread
 =item Patterns not starting with F</> will be anchored at the end of the path.
 That is, F<idna.pl> will match any file called F<idna.pl> 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</unicore/*.pl> would match all F<.pl> files directly inside
 C</unicore>, not any deeper level F<.pl> files. Or in other words, F<*>
 will not match slashes.
 Returns the list of all paths embedded in this binary.
 =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<http://buildroot.uclibc.org/>).
 Buildroot is primarily meant to set up a cross-compile environment (which
 handling for those files), so including them on demand by your application
 only might pay off.
 To simply include the whole unicode database, use:
-   --incglob '/unicore/*.pl'
+   --incglob '/unicore/**.pl'
 =item AnyEvent
 AnyEvent needs a backend implementation that it will load in a delayed
 fashion. The L<AnyEvent::Impl::Perl> backend is the default choice
 If you want to handle IRIs or IDNs (L<AnyEvent::Util> punycode and idn
 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
 Carp had (in older versions of perl) a dependency on L<Carp::Heavy>. As of
 turn might need L<"Config_heavy.pl">. Including the latter gives you
 both.
 =item Term::ReadLine::Perl
-Also needs L<Term::ReadLine::readline>, or C<--usepacklist>.
+Also needs L<Term::ReadLine::readline>, or C<--usepacklists>.
 =item URI
 URI implements schemes as separate modules - the generic URL scheme is
 implemented in L<URI::_generic>, HTTP is implemented in L<URI::http>. If
 you need to use any of these schemes, you should include these manually,
-or use C<--usepacklist>.
+or use C<--usepacklists>.
 =back
 =head2 RECIPES
 =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 --strip ppi --incglob '*'
+   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.
+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<bigperl|http://staticperl.schmorp.de/bigperl.html> uses this approach.
-=item Getting rid of netdb function
+=item Getting rid of netdb functions
 The perl core has lots of netdb functions (C<getnetbyname>, C<getgrent>
 and so on) that few applications use. You can avoid compiling them in by
 putting the following fragment into a C<preconfigure> hook:
       do
          PERL_CONFIGURE="$PERL_CONFIGURE -U$sym"
       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.
 Also, this leaves C<gethostbyname> in - not only is it actually used
 often, the L<Socket> module also exposes it, so leaving it out usually

Diff Legend

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

Comparing App-Staticperl/staticperl.pod (file contents): Revision 1.27 by root, Tue Dec 21 19:32:34 2010 UTC vs. Revision 1.31 by root, Thu Dec 23 14:16:25 2010 UTC

Diff Legend

Comparing App-Staticperl/staticperl.pod (file contents):
Revision 1.27 by root, Tue Dec 21 19:32:34 2010 UTC vs.
Revision 1.31 by root, Thu Dec 23 14:16:25 2010 UTC