[ViewVC] Diff of: cvs/App-Staticperl/staticperl.pod

Comparing App-Staticperl/staticperl.pod (file contents):
Revision 1.10 by root, Tue Dec 7 09:27:54 2010 UTC vs.
Revision 1.15 by root, Wed Dec 8 23:01:30 2010 UTC

    staticperl cpan      # invoke CPAN shell
    staticperl instmod path...        # install unpacked modules
    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:
    staticperl install   # fetch, configure, build and install perl
    staticperl cpan      # run interactive cpan shell
    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
 Maintaining your own custom perl build can be a pain in the ass, and while
 F<staticperl> tries to make this easy, it still requires a custom perl
 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?
 Simple: F<staticperl> downloads, compile and installs a perl version of
 command by specifying all the directories with modules in them that you
 want to have built.
 =item F<staticperl clean>
-Runs F<make distclean> in the perl source directory (and potentially
+Deletes the perl source directory (and potentially cleans up other
-cleans up other intermediate files). This can be used to clean up
+intermediate files). This can be used to clean up files only needed for
-intermediate files without removing the installed perl interpreter.
+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>
 This wipes your complete F<~/.staticperl> directory. Be careful with this,
 it nukes your perl download, perl sources, perl distribution and any
 (required by L<AnyEvent::HTTPD>) implements various URI schemes as extra
 modules - since L<AnyEvent::HTTPD> only needs C<http> URIs, we only need
 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
 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,
 C<mkperl> command (instead of C<mkbundle>):
    # 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
 C<require>'ing the module in a subprocess and tracing which other modules
 and files it actually loads. If the module uses L<AutoLoader>, then all
 Any other argument is interpreted as a bundle specification file, which
 supports most long options (without extra quoting), one option per line.
 =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:
    /etc/staticperlrc
 =item C<EMAIL>
 The e-mail address of the person who built this binary. Has no good
 default, so should be specified by you.
+=item C<CPAN>
+The URL of the CPAN mirror to use (e.g. L<http://mirror.netcologne.de/cpan/>).
+=item C<EXTRA_MODULES>
+Additional modules installed during F<staticperl install>. Here you can
+set which modules you want have to installed from CPAN.
+Example: I really really need EV, AnyEvent, Coro and AnyEvent::AIO.
+   EXTRA_MODULES="EV AnyEvent Coro AnyEvent::AIO"
+Note that you can also use a C<postinstall> hook to achieve this, and
+more.
 =back
 =head4 Variables you might I<want> to override
 =over 4
+=item C<STATICPERL>
+The directory where staticperl stores all its files
+(default: F<~/.staticperl>).
+=item C<PERL_MM_USE_DEFAULT>, C<EV_EXTRA_DEFS>, ...
+Usually set to C<1> to make modules "less inquisitive" during their
+installation, you can set any environment variable you want - some modules
+(such as L<Coro> or L<EV>) use environment variables for further tweaking.
-=item C<PERLVER>
+=item C<PERL_VERSION>
 The perl version to install - default is currently C<5.12.2>, but C<5.8.9>
 is also a good choice (5.8.9 is much smaller than 5.12.2, while 5.10.1 is
 about as big as 5.12.2).
-=item C<CPAN>
-The URL of the CPAN mirror to use (e.g. L<http://mirror.netcologne.de/cpan/>).
-=item C<EXTRA_MODULES>
-Additional modules installed during F<staticperl install>. Here you can
-set which modules you want have to installed from CPAN.
-Example: I really really need EV, AnyEvent, Coro and IO::AIO.
-   EXTRA_MODULES="EV AnyEvent Coro IO::AIO"
-Note that you can also use a C<postinstall> hook to achieve this, and
-more.
-=item C<PERL_MM_USE_DEFAULT>, C<EV_EXTRA_DEFS>, ...
-Usually set to C<1> to make modules "less inquisitive" during their
-installation, you can set any environment variable you want - some modules
-(such as L<Coro> or L<EV>) use environment variables for further tweaking.
-=item C<STATICPERL>
-The directory where staticperl stores all its files
-(default: F<~/.staticperl>).
-=item C<PREFIX>
+=item C<PERL_PREFIX>
 The prefix where perl gets installed (default: F<$STATICPERL/perl>),
 i.e. where the F<bin> and F<lib> subdirectories will end up.
 =item C<PERL_CONFIGURE>
       instcpan Anyevent::AIO AnyEvent::HTTPD
    }
 =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
+Could be used to tailor/patch config.sh (followed by F<sh Configure -S>)
-do any other modifications.
+or do any other modifications.
 =item postbuild
 Called after building, but before installing perl. Current working
 directory is the perl source directory.
 If you use C<linuxthreads.old>, then you should also be aware that
 uClibc shares C<errno> between all threads when statically linking. See
 L<http://lists.uclibc.org/pipermail/uclibc/2010-June/044157.html> for a
 workaround (And L<https://bugs.uclibc.org/2089> for discussion).
-C<ccache> support is also recommended, especially if you want to
+C<ccache> support is also recommended, especially if you want
-play around with buildroot options. Enabling the C<miniperl> package
+to play around with buildroot options. Enabling the C<miniperl>
-will probably enable all options required for a successful perl
+package will probably enable all options required for a successful
-build. F<staticperl> itself additionally needs either C<wget> or C<curl>.
+perl build. F<staticperl> itself additionally needs either C<wget>
+(recommended, for CPAN) or C<curl>.
 As for shells, busybox should provide all that is needed, but the default
 busybox configuration doesn't include F<comm> which is needed by perl -
 either make a custom busybox config, or compile coreutils.

Diff Legend

-–
+Removed lines
-+
+Added lines
-<
+Changed lines
->
+Changed lines

Comparing App-Staticperl/staticperl.pod (file contents): Revision 1.10 by root, Tue Dec 7 09:27:54 2010 UTC vs. Revision 1.15 by root, Wed Dec 8 23:01:30 2010 UTC

Diff Legend

Comparing App-Staticperl/staticperl.pod (file contents):
Revision 1.10 by root, Tue Dec 7 09:27:54 2010 UTC vs.
Revision 1.15 by root, Wed Dec 8 23:01:30 2010 UTC