--- App-Staticperl/staticperl.pod 2010/12/10 15:25:24 1.19
+++ App-Staticperl/staticperl.pod 2010/12/21 19:14:56 1.26
@@ -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.
@@ -143,18 +149,27 @@
staticperl install
-Is normally all you need: It installs the perl interpreter in
+is normally all you need: It installs the perl interpreter in
F<~/.staticperl/perl>. It downloads, configures, builds and installs the
perl interpreter if required.
-Most of the following commands simply run one or more steps of this
-sequence.
+Most of the following F subcommands simply run one or more
+steps of this sequence.
+
+If it fails, then most commonly because the compiler options I selected
+are not supported by your compiler - either edit the F script
+yourself or create F<~/.staticperl> shell script where your set working
+C etc. variables.
To force recompilation or reinstallation, you need to run F first.
=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.
@@ -201,11 +216,12 @@
Deletes the perl source directory (and potentially cleans up other
intermediate files). This can be used to clean up files only needed for
-building perl, without removing the installed perl interpreter, or to
-force a re-build from scratch.
+building perl, without removing the installed perl interpreter.
At the moment, it doesn't delete downloaded tarballs.
+The exact semantics of this command will probably change.
+
=item F
This wipes your complete F<~/.staticperl> directory. Be careful with this,
@@ -264,13 +280,45 @@
# run it
./app
+Here are the three phase 2 commands:
+
+=over 4
+
+=item F args...
+
+The "default" bundle command - it interprets the given bundle options and
+writes out F, F, F and F
+files, useful for embedding.
+
+=item F args...
+
+Creates a bundle just like F (in fact, it's the same
+as invoking F args...), but then compiles and
+links a new perl interpreter that embeds the created bundle, then deletes
+all intermediate files.
+
+=item F filename args...
+
+Does the same as F (in fact, it's the same as
+invoking F filename args...), but then compiles
+and links a new standalone application that simply initialises the perl
+interpreter.
+
+The difference to F is that the standalone application
+does not act like a perl interpreter would - in fact, by default it would
+just do nothing and exit immediately, so you should specify some code to
+be executed via the F<--boot> option.
+
+=back
+
=head3 OPTION PROCESSING
All options can be given as arguments on the command line (typically
using long (e.g. C<--verbose>) or short option (e.g. C<-v>) style). Since
-specifying a lot of modules can make the command line very cumbersome,
-you can put all long options into a "bundle specification file" (with or
-without C<--> prefix) and specify this bundle file instead.
+specifying a lot of modules can make the command line very cumbersome, you
+can put all long options into a "bundle specification file" (one option
+per line, with or without C<--> prefix) and specify this bundle file
+instead.
For example, the command given earlier could also look like this:
@@ -285,47 +333,22 @@
add eg/httpd httpd.pm
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
+order given on the command line.
-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 :)
+=head3 BUNDLE CREATION WORKFLOW
-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.
+F works by first assembling a list of candidate
+files and modules to include, then filtering them by include/exclude
+patterns. The remaining modules (together with their direct depdendencies,
+such as link libraries and AutoLoader files) are then converted into
+bundle files suitable for embedding. Afterwards, F
+can optionally build a new perl interpreter or a standalone application.
=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) and find any
-extra libraries they need for linking (F).
-
-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.
+=item Step 0: Generic argument processing.
-=head3 MKBUNDLE OPTIONS
+The following options influence F itself.
=over 4
@@ -337,67 +360,27 @@
Decreases the verbosity level by one.
-=item --strip none|pod|ppi
-
-Specify the stripping method applied to reduce the file of the perl
-sources included.
-
-The default is C, which uses the L module to remove all
-pod documentation, which is very fast and reduces file size a lot.
-
-The C method uses L to parse and condense the perl sources. This
-saves a lot more than just L, and is generally safer,
-but is also a lot slower (some files take almost a minute to strip -
-F maintains a cache of stripped files to speed up subsequent
-runs for this reason). Note that this method doesn't optimise for raw file
-size, but for best compression (that means that the uncompressed file size
-is a bit larger, but the files compress better, e.g. with F).
-
-Last not least, if you need accurate line numbers in error messages,
-or in the unlikely case where C is too slow, or some module gets
-mistreated, you can specify C to not mangle included perl sources in
-any way.
-
-=item --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
-directory. The bundle files will be removed.
-
-This switch is automatically used when F is invoked with the
-C command (instead of C):
-
- # build a new ./perl with only common::sense in it - very small :)
- staticperl mkperl -Mcommon::sense
-
-=item --app name
-
-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
-linking it.
+=item any other argument
-The difference to the (mutually exclusive) C<--perl> option is that the
-binary created by this option will not try to act as a perl interpreter -
-instead it will simply initialise the perl interpreter, clean it up and
-exit.
+Any other argument is interpreted as a bundle specification file, which
+supports most long options (without extra quoting), one option per line.
-This switch is automatically used when F is invoked with the
-C command (instead of C):
+=back
-To let it do something useful you I add some boot code, e.g. with
-the C<--boot> option.
+=item Step 1: gather candidate files and modules
-Example: create a standalone perl binary that will execute F when
-it is started.
+In this step, modules, perl libraries (F<.pl> files) and other files are
+selected for inclusion in the bundle. The relevant options are executed
+in order (this makes a difference mostly for C<--eval>, which can rely on
+earlier C<--use> options to have been executed).
- staticperl mkbundle --app myexe --boot appfile
+=over 4
-=item --use module | -Mmodule
+=item C<--use> F | C<-M>F
-Include the named module and all direct dependencies. This is done by
+Include the named module and trace direct dependencies. This is done by
C'ing the module in a subprocess and tracing which other modules
-and files it actually loads. If the module uses L, then all
-splitfiles will be included as well.
+and files it actually loads.
Example: include AnyEvent and AnyEvent::Impl::Perl.
@@ -418,17 +401,17 @@
# bundle specification file
use "Config_heavy.pl"
-The C<-Mmodule> syntax is included as an alias that might be easier to
-remember than C