--- App-Staticperl/staticperl.pod 2010/12/10 02:35:54 1.18
+++ App-Staticperl/staticperl.pod 2010/12/13 18:08:01 1.23
@@ -42,6 +42,10 @@
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.
+
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:
@@ -120,10 +124,12 @@
=head1 THE F SCRIPT
This module installs a script called F into your perl
-binary directory. The script is fully self-contained, and can be used
-without perl (for example, in an uClibc chroot environment). In fact,
-it can be extracted from the C distribution tarball as
-F, without any installation.
+binary directory. The script is fully self-contained, and can be
+used without perl (for example, in an uClibc chroot environment). In
+fact, it can be extracted from the C distribution
+tarball as F, without any installation. The
+newest (possibly alpha) version can also be downloaded from
+L.
F interprets the first argument as a command to execute,
optionally followed by any parameters.
@@ -155,6 +161,10 @@
=over 4
+=item F
+
+Prints some info about the version of the F script you are using.
+
=item F
Runs only the download and unpack phase, unless this has already happened.
@@ -288,6 +298,44 @@
order given on the command line (that affects the C<--use> and C<--eval>
options at the moment).
+=head3 PACKAGE SELECTION WORKFLOW
+
+F 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 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) and optionally
+evaluate any F<.packlist> files.
+
+This step is required to link against XS extensions and also adds files
+required for L 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
+or application binary will be linked.
+
=head3 MKBUNDLE OPTIONS
=over 4
@@ -418,6 +466,23 @@
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 module is specified, then
+all L 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>
@@ -554,16 +619,22 @@
=head2 F CONFIGURATION AND HOOKS
-During (each) startup, F tries to source the following shell
-files in order:
+During (each) startup, F 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 hook to install additional
+modules from CPAN each time you start from scratch.
+
+If the env variable C<$STATICPERLRC> is set, then F will try
+to source the file named with it only. Otherwise, it tries the following
+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, so
generally should not be used.
@@ -634,7 +705,7 @@
(C<-Duse64bitint>), or disable large files support (-Uuselargefiles), to
reduce filesize further.
-=item C, C, C, C
+=item C, C, C, C, C
These flags are passed to perl's F script, and are generally
optimised for small size (at the cost of performance). Since they also
@@ -648,6 +719,10 @@
=over 4
+=item C
+
+The make command to use - default is C.
+
=item C
Where F writes the C command to
@@ -918,6 +993,9 @@
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. As of
@@ -931,13 +1009,14 @@
=item Term::ReadLine::Perl
-Also needs L.
+Also needs L, or C<--usepacklist>.
=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.
+you need to use any of these schemes, you should include these manually,
+or use C<--usepacklist>.
=back
@@ -980,7 +1059,7 @@
}
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 in - not only is it actually used