[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.17 by root, Thu Dec 9 08:55:52 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.
 =item * The generated executables don't need a writable filesystem.
 F<staticperl> loads all required files directly from memory. There is no
 need to unpack files into a temporary directory.
-=item * More control over included files.
+=item * More control over included files, more burden.
 PAR tries to be maintenance and hassle-free - it tries to include more
-files than necessary to make sure everything works out of the box. The
+files than necessary to make sure everything works out of the box. It
-extra files (such as the unicode database) can take substantial amounts of
+mostly succeeds at this, but he extra files (such as the unicode database)
-memory and file size.
+can take substantial amounts of memory and file size.
 With F<staticperl>, the burden is mostly with the developer - only direct
 compile-time dependencies and L<AutoLoader> are handled automatically.
 This means the modules to include often need to be tweaked manually.
+All this does not preclude more permissive modes to be implemented in
+the future, but right now, you have to resolve state hidden dependencies
+manually.
 =item * PAR works out of the box, F<staticperl> does not.
 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?
 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.
 After you have compiled and set up your buildroot target, you can copy
 F<staticperl> from the C<App::Staticperl> distribution or from your
 perl f<bin> directory (if you installed it) into the F<output/target>
 filesystem, chroot inside and run it.
+=head1 RECIPES / SPECIFIC MODULES
+This section contains some common(?) recipes and information about
+problems with some common modules or perl constructs that require extra
+files to be included.
+=head2 MODULES
+=over 4
+=item utf8
+Some functionality in the utf8 module, such as swash handling (used
+for unicode character ranges in regexes) is implemented in the
+C<"utf8_heavy.pl"> library.
+Many Unicode properties in turn are defined in separate modules,
+such as C<"unicore/Heavy.pl"> and more specific data tables such as
+C<"unicore/To/Digit.pl"> or C<"unicore/lib/Perl/Word.pl">. These
+tables are big (7MB uncompressed), so including them on demand by your
+applciation only might pay off.
+=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.
+=item Config
+The F<perl -V> switch (as well as many modules) needs L<Config>, which in
+turn might need L<"Config_heavy.pl">. Including the latter gives you
+both.
+=item AnyEvent
+AnyEvent needs a backend implementation that it will load in a delayed
+fashion. The L<AnyEvent::Impl::Perl> backend is the default choice
+for AnyEvent if it can't find anything else, and is usually a safe
+fallback. If you plan to use e.g. L<EV> (L<POE>...), then you need to
+include the L<AnyEvent::Impl::EV> (L<AnyEvent::Impl::POE>...) backend as
+well.
+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">.
+=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.
+=back
+=head2 RECIPES
+=over 4
+=item Getting rid of netdb function
+The perl core has lots of netdb functions (C<getnetbyname>, C<getgrent>
+and so on) that few applications use. You can avoid compiling them in by
+putting the following fragment into a C<preconfigure> hook:
+   preconfigure() {
+      for sym in \
+         d_getgrnam_r d_endgrent d_endgrent_r d_endhent \
+         d_endhostent_r d_endnent d_endnetent_r d_endpent \
+         d_endprotoent_r d_endpwent d_endpwent_r d_endsent \
+         d_endservent_r d_getgrent d_getgrent_r d_getgrgid_r \
+         d_getgrnam_r d_gethbyaddr d_gethent d_getsbyport \
+         d_gethostbyaddr_r d_gethostbyname_r d_gethostent_r \
+         d_getlogin_r d_getnbyaddr d_getnbyname d_getnent \
+         d_getnetbyaddr_r d_getnetbyname_r d_getnetent_r \
+         d_getpent d_getpbyname d_getpbynumber d_getprotobyname_r \
+         d_getprotobynumber_r d_getprotoent_r d_getpwent \
+         d_getpwent_r d_getpwnam_r d_getpwuid_r d_getsent \
+         d_getservbyname_r d_getservbyport_r d_getservent_r \
+         d_getspnam_r d_getsbyname
+         # d_gethbyname
+      do
+         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
+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
+is anybody's guess.
+=back
 =head1 AUTHOR
  Marc Lehmann <schmorp@schmorp.de>
  http://software.schmorp.de/pkg/staticperl.html

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.17 by root, Thu Dec 9 08:55:52 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.17 by root, Thu Dec 9 08:55:52 2010 UTC