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

Comparing App-Staticperl/staticperl.pod (file contents):
Revision 1.18 by root, Fri Dec 10 02:35:54 2010 UTC vs.
Revision 1.23 by root, Mon Dec 13 18:08:01 2010 UTC

 With F<uClibc> and F<upx> on x86, you can create a single 500kb binary
 that contains perl and 100 modules such as POSIX, AnyEvent, EV, IO::AIO,
 Coro and so on. Or any other choice of modules.
+To see how this turns out, you can try out smallperl and bigperl, two
+pre-built static and compressed perl binaries with many and even more
+modules: just follow the links at L<http://staticperl.schmorp.de/>.
 The created files do not need write access to the file system (like PAR
 does). In fact, since this script is in many ways similar to PAR::Packer,
 here are the differences:
 =over 4
 often as necessary.
 =head1 THE F<STATICPERL> SCRIPT
 This module installs a script called F<staticperl> into your perl
-binary directory. The script is fully self-contained, and can be used
+binary directory. The script is fully self-contained, and can be
-without perl (for example, in an uClibc chroot environment). In fact,
+used without perl (for example, in an uClibc chroot environment). In
-it can be extracted from the C<App::Staticperl> distribution tarball as
+fact, it can be extracted from the C<App::Staticperl> distribution
-F<bin/staticperl>, without any installation.
+tarball as F<bin/staticperl>, without any installation. The
+newest (possibly alpha) version can also be downloaded from
+L<http://staticperl.schmorp.de/staticperl>.
 F<staticperl> interprets the first argument as a command to execute,
 optionally followed by any parameters.
 There are two command categories: the "phase 1" commands which deal with
 To force recompilation or reinstallation, you need to run F<staticperl
 distclean> first.
 =over 4
+=item F<staticperl version>
+Prints some info about the version of the F<staticperl> script you are using.
 =item F<staticperl fetch>
 Runs only the download and unpack phase, unless this has already happened.
 All options that specify modules or files to be added are processed in the
 order given on the command line (that affects the C<--use> and C<--eval>
 options at the moment).
+=head3 PACKAGE SELECTION WORKFLOW
+F<staticperl mkbundle> has a number of options to control package
+selection. This section describes how they interact with each other. Also,
+since I am still a newbie w.r.t. these issues, maybe future versions of
+F<staticperl> will change this, so watch out :)
+The idiom "in order" means "in order that they are specified on the
+commandline". If you use a bundle specification file, then the options
+will be processed as if they were given in place of the bundle file name.
+=over 4
+=item 1. apply all C<--use>, C<--eval>, C<--add>, C<--addbin> and
+C<--incglob> options, in order.
+In addition, C<--use> and C<--eval> dependencies will be added when the
+options are processed.
+=item 2. apply all C<--include> and C<--exclude> options, in order.
+All this step does is potentially reduce the number of files already
+selected or found in phase 1.
+=item 3. find all modules (== F<.pm> files), gather their static archives
+(F<.a>) and AutoLoader splitfiles (F<.ix> and F<.al> files), find any
+extra libraries they need for linking (F<extralibs.ld>) and optionally
+evaluate any F<.packlist> files.
+This step is required to link against XS extensions and also adds files
+required for L<AutoLoader> to do it's job.
+=back
+After this, all the files selected for bundling will be read and processed
+(stripped), the bundle files will be written, and optionally a new F<perl>
+or application binary will be linked.
 =head3 MKBUNDLE OPTIONS
 =over 4
 =item --verbose | -v
 (using a C<require>) before anything else when the new perl is
 initialised. This can be used to modify C<@INC> or anything else before
 the perl interpreter executes scripts given on the command line (or via
 C<-e>). This works even in an embedded interpreter.
+=item --usepacklist
+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.
+The idea is that most CPAN distributions have a F<.pm> file that matches
+the name of the distribution (which is rather reasonable after all).
+If this switch is enabled, then if any of the F<.pm> files that have been
+selected match an install distribution, then all F<.pm>, F<.pl>, F<.al>
+and F<.ix> files installed by this distribution are also included.
+For example, using this switch, when the L<URI> module is specified, then
+all L<URI> submodules that have been installed via the CPAN distribution
+are included as well, so you don't have to manually specify them.
 =item --incglob pattern
 This goes through all library directories and tries to match any F<.pm>
 and F<.pl> files against the extended glob pattern (see below). If a file
 matches, it is added. This switch will automatically detect L<AutoLoader>
 =back
 =head2 F<STATICPERL> CONFIGURATION AND HOOKS
-During (each) startup, F<staticperl> tries to source the following shell
+During (each) startup, F<staticperl> tries to source some shell files to
+allow you to fine-tune/override configuration settings.
+In them you can override shell variables, or define shell functions
+("hooks") to be called at specific phases during installation. For
+example, you could define a C<postinstall> hook to install additional
+modules from CPAN each time you start from scratch.
+If the env variable C<$STATICPERLRC> is set, then F<staticperl> will try
+to source the file named with it only. Otherwise, it tries the following
-files in order:
+shell files in order:
    /etc/staticperlrc
    ~/.staticperlrc
    $STATICPERL/rc
-They can be used to override shell variables, or define functions to be
-called at specific phases.
 Note that the last file is erased during F<staticperl distclean>, so
 generally should not be used.
 =head3 CONFIGURATION VARIABLES
 More commonly, you would either activate 64 bit integer support
 (C<-Duse64bitint>), or disable large files support (-Uuselargefiles), to
 reduce filesize further.
-=item C<PERL_CPPFLAGS>, C<PERL_OPTIMIZE>, C<PERL_LDFLAGS>, C<PERL_LIBS>
+=item C<PERL_CC>, C<PERL_CPPFLAGS>, C<PERL_OPTIMIZE>, C<PERL_LDFLAGS>, C<PERL_LIBS>
 These flags are passed to perl's F<Configure> script, and are generally
 optimised for small size (at the cost of performance). Since they also
 contain subtle workarounds around various build issues, changing these
 usually requires understanding their default values - best look at the top
 =back
 =head4 Variables you probably I<do not want> to override
 =over 4
+=item C<MAKE>
+The make command to use - default is C<make>.
 =item C<MKBUNDLE>
 Where F<staticperl> writes the C<mkbundle> command to
 (default: F<$STATICPERL/mkbundle>).
 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
+everything.
 =item Carp
 Carp had (in older versions of perl) a dependency on L<Carp::Heavy>. As of
 perl 5.12.2 (maybe earlier), this dependency no longer exists.
 turn might need L<"Config_heavy.pl">. Including the latter gives you
 both.
 =item Term::ReadLine::Perl
-Also needs L<Term::ReadLine::readline>.
+Also needs L<Term::ReadLine::readline>, or C<--usepacklist>.
 =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.
+you need to use any of these schemes, you should include these manually,
+or use C<--usepacklist>.
 =back
 =head2 RECIPES
          PERL_CONFIGURE="$PERL_CONFIGURE -U$sym"
       done
    }
 This mostly gains space when linking staticaly, as the functions will
-liekly not be linked in. The gain for dynamically-linked binaries is
+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
 gains little. Why Socket exposes a C function that is in the core already

Diff Legend

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

Comparing App-Staticperl/staticperl.pod (file contents): Revision 1.18 by root, Fri Dec 10 02:35:54 2010 UTC vs. Revision 1.23 by root, Mon Dec 13 18:08:01 2010 UTC

Diff Legend

Comparing App-Staticperl/staticperl.pod (file contents):
Revision 1.18 by root, Fri Dec 10 02:35:54 2010 UTC vs.
Revision 1.23 by root, Mon Dec 13 18:08:01 2010 UTC