--- App-Staticperl/staticperl.pod 2010/12/10 02:35:54 1.18
+++ App-Staticperl/staticperl.pod 2010/12/21 19:44:43 1.28
@@ -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,20 +280,54 @@
# 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 options can make the command line very long and
+unwieldy, 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:
+For example, the command given earlier to link a new F could also
+look like this:
staticperl mkperl httpd.bundle
-And all options could be in F:
-
+With all options stored in the F file (one option per line,
+everything after the option is an argument):
+
use "Config_heavy.pl"
use AnyEvent::Impl::Perl
use AnyEvent::HTTPD
@@ -285,92 +335,70 @@
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 MKBUNDLE OPTIONS
-
-=over 4
-
-=item --verbose | -v
+order given on the command line.
-Increases the verbosity level by one (the default is C<1>).
+=head3 BUNDLE CREATION WORKFLOW / STATICPELR MKBUNDLE OPTIONS
-=item --quiet | -q
-
-Decreases the verbosity level by one.
+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 dependencies,
+such as link libraries and L files) are then converted into
+bundle files suitable for embedding. F can then
+optionally build a new perl interpreter or a standalone application.
-=item --strip none|pod|ppi
+=over 4
-Specify the stripping method applied to reduce the file of the perl
-sources included.
+=item Step 0: Generic argument processing.
-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 following options influence F itself.
-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.
+=over 4
-=item --perl
+=item C<--verbose> | C<-v>
-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):
+Increases the verbosity level by one (the default is C<1>).
- # build a new ./perl with only common::sense in it - very small :)
- staticperl mkperl -Mcommon::sense
+=item C<--quiet> | C<-q>
-=item --app name
+Decreases the verbosity level by one.
-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 all options (without extra quoting), one option per line, in the
+format C