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

Comparing App-Staticperl/staticperl.pod (file contents):
Revision 1.9 by root, Tue Dec 7 09:08:06 2010 UTC vs.
Revision 1.16 by root, Wed Dec 8 23:03:21 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
+This script helps you to create single-file perl interpreters
-a perl interpreter in your applications. Single-file means that it is
+or applications, or embedding a perl interpreter in your
-fully self-contained - no separate shared objects, no autoload fragments,
+applications. Single-file means that it is fully self-contained - no
-no .pm or .pl files are needed. And when linking statically, you can
+separate shared objects, no autoload fragments, no .pm or .pl files are
-create (or embed) a single file that contains perl interpreter, libc, all
+needed. And when linking statically, you can create (or embed) a single
-the modules you need and all the libraries you need.
+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,
 Coro and so on. Or any other choice of modules.
 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
    # specification file
    add file1 myfiles/file1
    add file2 myfiles/file2
    add file3 myfiles/file3
+=item --binadd "file" | --add "file alias"
+Just like C<--add>, except that it treats the file as binary and adds it
+without any processing.
+You should probably add a C</> prefix to avoid clashing with embedded
+perl files (whose paths do not start with C</>), and/or use a special
+directory, such as C</res/name>.
+You can later get a copy of these files by calling C<staticperl::find
+"alias">.
 =item --static
 When C<--perl> is also given, link statically instead of dynamically. The
 default is to link the new perl interpreter fully dynamic (that means all
 perl modules are linked statically, but all external libraries are still
 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>
+Additional Configure options - these are simply passed to the perl
+Configure script. For example, if you wanted to enable dynamic loading,
+you could pass C<-Dusedl>. To enable ithreads (Why would you want that
+insanity? Don't! Use L<forks> instead!) you would pass C<-Duseithreads>
+and so on.
+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>
 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
       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.
 =back
 =head1 FULLY STATIC BINARIES - BUILDROOT
-To make truly static (linux-) libraries, you might want to have a look at
+To make truly static (Linux-) libraries, you might want to have a look at
 buildroot (L<http://buildroot.uclibc.org/>).
 Buildroot is primarily meant to set up a cross-compile environment (which
 is not so useful as perl doesn't quite like cross compiles), but it can also compile
 a chroot environment where you can use F<staticperl>.
 uClibc newer than 0.9.31 (at the time of this writing, I used the 20101201
 snapshot) and enable NPTL, otherwise Coro needs to be configured with the
 ultra-slow pthreads backend to work around linuxthreads bugs (it also uses
 twice the address space needed for stacks).
+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.9 by root, Tue Dec 7 09:08:06 2010 UTC vs. Revision 1.16 by root, Wed Dec 8 23:03:21 2010 UTC

Diff Legend

Comparing App-Staticperl/staticperl.pod (file contents):
Revision 1.9 by root, Tue Dec 7 09:08:06 2010 UTC vs.
Revision 1.16 by root, Wed Dec 8 23:03:21 2010 UTC