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

Comparing App-Staticperl/staticperl.pod (file contents):
Revision 1.19 by root, Fri Dec 10 15:25:24 2010 UTC vs.
Revision 1.25 by root, Tue Dec 21 12:59:29 2010 UTC

 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,
 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:
 =over 4
 often as necessary.
 =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
+binary directory. The script is fully self-contained, and can be
-without perl (for example, in an uClibc chroot environment). In fact,
+used without perl (for example, in an uClibc chroot environment). In
-it can be extracted from the C<App::Staticperl> distribution tarball as
+fact, it can be extracted from the C<App::Staticperl> distribution
-F<bin/staticperl>, without any installation.
+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.
 There are two command categories: the "phase 1" commands which deal with
 The command
    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
+Most of the following F<staticperl> subcommands simply run one or more
-sequence.
+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.
 =item F<staticperl clean>
 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
+building perl, without removing the installed perl interpreter.
-force a re-build from scratch.
 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,
 it nukes your perl download, perl sources, perl distribution and any
                     -MAnyEvent::Impl::Perl -MAnyEvent::HTTPD -MURI::http
    # 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,
+specifying a lot of modules can make the command line very cumbersome, you
-you can put all long options into a "bundle specification file" (with or
+can put all long options into a "bundle specification file" (one option
-without C<--> prefix) and specify this bundle file instead.
+per line, with or without C<--> prefix) and specify this bundle file
+instead.
 For example, the command given earlier could also look like this:
    staticperl mkperl httpd.bundle
    use AnyEvent::HTTPD
    use URI::http
    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>
+order given on the command line.
-options at the moment).
 =head3 PACKAGE SELECTION WORKFLOW
 F<staticperl mkbundle> has a number of options to control package
 selection. This section describes how they interact with each other. Also,
 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
+(F<.a>) and AutoLoader splitfiles (F<.ix> and F<.al> files), find any
-extra libraries they need for linking (F<extralibs.ld>).
+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.
 =back
 (using a C<require>) before anything else when the new perl is
 initialised. This can be used to modify C<@INC> or anything else before
 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>
 and F<.pl> files against the extended glob pattern (see below). If a file
 matches, it is added. This switch will automatically detect L<AutoLoader>
 =back
 =head2 F<STATICPERL> CONFIGURATION AND HOOKS
-During (each) startup, F<staticperl> tries to source the following shell
+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
-files in order:
+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.
 =head3 CONFIGURATION VARIABLES
 More commonly, you would either activate 64 bit integer support
 (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
+usually requires understanding their default values - best look at
-of the F<staticperl> script for more info on these.
+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
 =head4 Variables you probably I<do not want> to override
 =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
 (default: F<$STATICPERL/mkbundle>).
 If you want to handle IRIs or IDNs (L<AnyEvent::Util> punycode and idn
 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
 perl 5.12.2 (maybe earlier), this dependency no longer exists.
 turn might need L<"Config_heavy.pl">. Including the latter gives you
 both.
 =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
 =head2 RECIPES
          PERL_CONFIGURE="$PERL_CONFIGURE -U$sym"
       done
    }
 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
 often, the L<Socket> module also exposes it, so leaving it out usually
 gains little. Why Socket exposes a C function that is in the core already

Diff Legend

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

Comparing App-Staticperl/staticperl.pod (file contents): Revision 1.19 by root, Fri Dec 10 15:25:24 2010 UTC vs. Revision 1.25 by root, Tue Dec 21 12:59:29 2010 UTC

Diff Legend

Comparing App-Staticperl/staticperl.pod (file contents):
Revision 1.19 by root, Fri Dec 10 15:25:24 2010 UTC vs.
Revision 1.25 by root, Tue Dec 21 12:59:29 2010 UTC