--- App-Staticperl/staticperl.pod	2010/12/10 15:25:24	1.19
+++ App-Staticperl/staticperl.pod	2010/12/21 12:59:29	1.25
@@ -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<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:
@@ -120,10 +124,12 @@
 =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
-without perl (for example, in an uClibc chroot environment). In fact,
-it can be extracted from the C<App::Staticperl> distribution tarball as
-F<bin/staticperl>, 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<App::Staticperl> distribution
+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.
@@ -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<staticperl> 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<staticperl> script
+yourself or create F<~/.staticperl> shell script where your set working
+C<PERL_CCFLAGS> etc. variables.
 
 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.
@@ -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<staticperl distclean>
 
 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<staticperl mkbundle> args...
+
+The "default" bundle command - it interprets the given bundle options and
+writes out F<bundle.h>, F<bundle.c>, F<bundle.ccopts> and F<bundle.ldopts>
+files, useful for embedding.
+
+=item F<staticperl mkperl> args...
+
+Creates a bundle just like F<staticperl mkbundle> (in fact, it's the same
+as invoking F<staticperl mkbundle --perl> args...), but then compiles and
+links a new perl interpreter that embeds the created bundle, then deletes
+all intermediate files.
+
+=item F<staticperl mkapp> filename args...
+
+Does the same as F<staticperl mkbundle> (in fact, it's the same as
+invoking F<staticperl mkbundle --app> filename args...), but then compiles
+and links a new standalone application that simply initialises the perl
+interpreter.
+
+The difference to F<staticperl mkperl> 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,8 +333,7 @@
    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).
+order given on the command line.
 
 =head3 PACKAGE SELECTION WORKFLOW
 
@@ -313,8 +360,9 @@
 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<extralibs.ld>).
+(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.
@@ -455,6 +503,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<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>
@@ -591,16 +656,22 @@
 
 =head2 F<STATICPERL> CONFIGURATION AND HOOKS
 
-During (each) startup, F<staticperl> tries to source the following shell
-files in order:
+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
+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.
 
@@ -671,13 +742,17 @@
 (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_CCFLAGS>, 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
-of the F<staticperl> script for more info on these.
+usually requires understanding their default values - best look at
+the top of the F<staticperl> script for more info on these, and use a
+F<~/.staticperlrc> to override them.
+
+Most of the variables override (or modify) the corresponding F<Configure>
+variable, except C<PERL_CCFLAGS>, which gets appended.
 
 =back
 
@@ -685,6 +760,10 @@
 
 =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
@@ -955,6 +1034,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<Carp::Heavy>. As of
@@ -968,13 +1050,14 @@
 
 =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
 
@@ -1017,7 +1100,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<gethostbyname> in - not only is it actually used