--- App-Staticperl/staticperl.pod	2010/12/07 10:40:39	1.11
+++ App-Staticperl/staticperl.pod	2010/12/08 23:03:21	1.16
@@ -16,6 +16,7 @@
    staticperl instcpan modulename... # install modules from CPAN
    staticperl mkbundle <bundle-args...> # see documentation
    staticperl mkperl <bundle-args...>   # see documentation
+   staticperl mkapp appname <bundle-args...> # see documentation
 
 Typical Examples:
 
@@ -24,15 +25,18 @@
    staticperl mkperl -M '"Config_heavy.pl"' # build a perl that supports -V
    staticperl mkperl -MAnyEvent::Impl::Perl -MAnyEvent::HTTPD -MURI -MURI::http
                         # build a perl with the above modules linked in
+   staticperl mkapp myapp --boot mainprog mymodules
+                        # build a binary "myapp" from mainprog and mymodules
 
 =head1 DESCRIPTION
 
-This script helps you creating single-file perl interpreters, or embedding
-a perl interpreter in your applications. Single-file means that it is
-fully self-contained - no separate shared objects, no autoload fragments,
-no .pm or .pl files are needed. And when linking statically, you can
-create (or embed) a single file that contains perl interpreter, libc, all
-the modules you need and all the libraries you need.
+This script helps you to create single-file perl interpreters
+or applications, or embedding a perl interpreter in your
+applications. Single-file means that it is fully self-contained - no
+separate shared objects, no autoload fragments, no .pm or .pl files are
+needed. And when linking statically, you can create (or embed) a single
+file that contains perl interpreter, libc, all the modules you need, all
+the libraries you need and of course your actual program.
 
 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,
@@ -83,6 +87,11 @@
 build and possibly fiddling with some modules. PAR is likely to produce
 results faster.
 
+Ok, PAR never has worked for me out of the box, and for some people,
+F<staticperl> does work out of the box, as they don't count "fiddling with
+module use lists" against it, but nevertheless, F<staticperl> is certainly
+a bit more difficult to use.
+
 =back
 
 =head1 HOW DOES IT WORK?
@@ -186,9 +195,12 @@
 
 =item F<staticperl clean>
 
-Runs F<make distclean> in the perl source directory (and potentially
-cleans up other intermediate files). This can be used to clean up
-intermediate files without removing the installed perl interpreter.
+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.
+
+At the moment, it doesn't delete downloaded tarballs.
 
 =item F<staticperl distclean>
 
@@ -238,6 +250,16 @@
 to include that module. I found out about these dependencies by carefully
 watching any error messages about missing modules...
 
+Instead of building a new perl binary, you can also build a standalone
+application:
+
+   # build the app
+   staticperl mkapp app --boot eg/httpd \
+                    -MAnyEvent::Impl::Perl -MAnyEvent::HTTPD -MURI::http
+
+   # run it
+   ./app
+
 =head3 OPTION PROCESSING
 
 All options can be given as arguments on the command line (typically
@@ -306,6 +328,28 @@
    # 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<name>, and the bundle files get removed after
+linking it.
+
+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.
+
+This switch is automatically used when F<staticperl> is invoked with the
+C<mkapp> command (instead of C<mkbundle>):
+
+To let it do something useful you I<must> add some boot code, e.g. with
+the C<--boot> option.
+
+Example: create a standalone perl binary that will execute F<appfile> when
+it is started.
+
+   staticperl mkbundle --app myexe --boot appfile
+
 =item --use module | -Mmodule
 
 Include the named module and all direct dependencies. This is done by
@@ -417,7 +461,7 @@
 
 =back
 
-=head2 F<STATCPERL> CONFIGURATION AND HOOKS
+=head2 F<STATICPERL> CONFIGURATION AND HOOKS
 
 During (each) startup, F<staticperl> tries to source the following shell
 files in order:
@@ -544,13 +588,21 @@
 
 =over 4
 
+=item preconfigure
+
+Called just before running F<./Configur> in the perl source
+directory. Current working directory is the perl source directory.
+
+This can be used to set any C<PERL_xxx> variables, which might be costly
+to compute.
+
 =item postconfigure
 
 Called after configuring, but before building perl. Current working
 directory is the perl source directory.
 
-Could be used to tailor/patch config.sh (followed by F<./Configure -S>) or
-do any other modifications.
+Could be used to tailor/patch config.sh (followed by F<sh Configure -S>)
+or do any other modifications.
 
 =item postbuild