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

Comparing App-Staticperl/staticperl.pod (file contents):
Revision 1.39 by root, Sat Apr 2 11:00:34 2011 UTC vs.
Revision 1.58 by root, Sun Jun 16 04:38:38 2013 UTC

 =head1 NAME
-staticperl - perl, libc, 100 modules, all in one 500kb file
+staticperl - perl, libc, 100 modules, all in one standalone 500kb file
 =head1 SYNOPSIS
    staticperl help      # print the embedded documentation
    staticperl fetch     # fetch and unpack perl sources
    staticperl install   # build and then install perl
    staticperl clean     # clean most intermediate files (restart at configure)
    staticperl distclean # delete everything installed by this script
    staticperl perl ...  # invoke the perlinterpreter
    staticperl cpan      # invoke CPAN shell
-   staticperl instmod path...        # install unpacked modules
+   staticperl instsrc 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
 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.
+Coro and so on. Or any other choice of modules (and some other size :).
 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/>.
 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
+the future, but right now, you have to resolve 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
 =item F<staticperl cpan> [args...]
 Starts an interactive CPAN shell that you can use to install further
 modules. Installs the perl first if necessary, but apart from that,
 no magic is involved: you could just as well run it manually via
-F<~/.staticperl/perl/bin/cpan>.
+F<~/.staticperl/perl/bin/cpan>, except that F<staticperl> additionally
+sets the environment variable C<$PERL> to the path of the perl
+interpreter, which is handy in subshells.
 Any additional arguments are simply passed to the F<cpan> command.
 =item F<staticperl instcpan> module...
    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.
-=head3 BUNDLE CREATION WORKFLOW / STATICPELR MKBUNDLE OPTIONS
+=head3 BUNDLE CREATION WORKFLOW / STATICPERL MKBUNDLE OPTIONS
 F<staticperl mkbundle> works by first assembling a list of candidate
 files and modules to include, then filtering them by include/exclude
 patterns. The remaining modules (together with their direct dependencies,
 such as link libraries and L<AutoLoader> files) are then converted into
    # then later, in perl, use
    use myfiles::file1;
    require myfiles::file2;
    my $res = do "myfiles/file3.pl";
-=item C<--binadd> F<file> | C<--add> "F<file> alias"
+=item C<--addbin> F<file> | C<--addbin> "F<file> alias"
 Just like C<--add>, except that it treats the file as binary and adds it
 without any postprocessing (perl files might get stripped to reduce their
 size).
-If you specify an alias you should probably add a C<&> prefix to avoid
+If you specify an alias you should probably add a C</> prefix to avoid
-clashing with embedded perl files (whose paths never start with C<&>),
+clashing with embedded perl files (whose paths never start with C</>),
-and/or use a special directory prefix, such as C<&res/name>.
+and/or use a special directory prefix, such as C</res/name>.
-You can later get a copy of these files by calling C<staticperl::find
+You can later get a copy of these files by calling C<static::find
 "alias">.
 An alternative way to embed binary files is to convert them to perl and
 use C<do> to get the contents - this method is a bit cumbersome, but works
-both inside and outside of a staticperl bundle:
+both inside and outside of a staticperl bundle, without extra ado:
    # a "binary" file, call it "bindata.pl"
    <<'SOME_MARKER'
    binary data NOT containing SOME_MARKER
    SOME_MARKER
    # load the binary
    chomp (my $data = do "bindata.pl");
+=item C<--allow-dynamic>
+By default, when F<mkbundle> hits a dynamic perl extension (e.g. a F<.so>
+or F<.dll> file), it will stop with a fatal error.
+When this option is enabled, F<mkbundle> packages the shared
+object into the bundle instead, with a prefix of F<!>
+(e.g. F<!auto/List/Util/Util.so>). What you do with that is currently up
+to you, F<staticperl> has no special support for this at the moment, apart
+from working around the lack of availability of F<PerlIO::scalar> while
+bootstrapping, at a speed cost.
+One way to deal with this is to write all files starting with F<!> into
+some directory and then C<unshift> that path onto C<@INC>.
+#TODO: example
 =back
 =item Step 2: filter all files using C<--include> and C<--exclude> options.
 standalone applications, and this option removes those known to cause
 trouble.
 Specifically, these are removed:
-C<PERL_HASH_SEED_DEBUG> and C<PERL_DEBUG_MSTATS> can cause underaible
+C<PERL_HASH_SEED_DEBUG> and C<PERL_DEBUG_MSTATS> can cause undesirable
 output, C<PERL5OPT>, C<PERL_DESTRUCT_LEVEL>, C<PERL_HASH_SEED> and
 C<PERL_SIGNALS> can alter execution significantly, and C<PERL_UNICODE>,
 C<PERLIO_DEBUG> and C<PERLIO> can affect input and output.
 The variables C<PERL_LIB> and C<PERL5_LIB> are always ignored because the
 =item C<STATICPERL>
 The directory where staticperl stores all its files
 (default: F<~/.staticperl>).
-=item C<PERL_MM_USE_DEFAULT>, C<EV_EXTRA_DEFS>, ...
+=item C<DLCACHE>
-Usually set to C<1> to make modules "less inquisitive" during their
+The path to a directory (will be created if it doesn't exist) where
-installation, you can set any environment variable you want - some modules
+downloaded perl sources are being cached, to avoid downloading them
-(such as L<Coro> or L<EV>) use environment variables for further tweaking.
+again. The default is empty, which means there is no cache.
 =item C<PERL_VERSION>
 The perl version to install - default is currently C<5.12.3>, but C<5.8.9>
 is also a good choice (5.8.9 is much smaller than 5.12.3, while 5.10.1 is
 about as big as 5.12.3).
+=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 (and export!) any environment variable you want
+- some modules (such as L<Coro> or L<EV>) use environment variables for
+further tweaking.
 =item C<PERL_PREFIX>
-The prefix where perl gets installed (default: F<$STATICPERL/perl>),
+The directory where perl gets installed (default: F<$STATICPERL/perl>),
-i.e. where the F<bin> and F<lib> subdirectories will end up.
+i.e. where the F<bin> and F<lib> subdirectories will end up. Previous
+contents will be removed on installation.
 =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,
 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.
+The default for C<PERL_OPTIMIZE> is C<-Os> (assuming gcc), and for
+C<PERL_LIBS> is C<-lm -lcrypt>, which should be good for most (but not
+all) systems.
+For other compilers or more customised optimisation settings, you need to
+adjust these, e.g. in your F<~/.staticperlrc>.
+With gcc on x86 and amd64, you can get more space-savings by using:
+   -Os -ffunction-sections -fdata-sections -finline-limit=8 -mpush-args
+   -mno-inline-stringops-dynamically -mno-align-stringops
+And on x86 and pentium3 and newer (basically everything you might ever
+want to run on), adding these is even better for space-savings (use
+-mtune=core2 or something newer for much faster code, too):
+   -fomit-frame-pointer -march=pentium3 -mtune=i386
 =back
 =head4 Variables you probably I<do not want> to override
 =back
 =head1 RUNTIME FUNCTIONALITY
-Binaries created with C<mkbundle>/C<mkperl> contain extra functions, which
+Binaries created with C<mkbundle>/C<mkperl> contain extra functionality,
-are required to access the bundled perl sources, but might be useful for
+mostly related to the extra files bundled in the binary (the virtual
-other purposes.
+filesystem). All of this data is statically compiled into the binary, and
+accessing means copying it from a read-only section of your binary. Data
+pages in this way is usually freed by the operating system, as it isn't
+use more the onace.
+=head2 VIRTUAL FILESYSTEM
+Every bundle has a virtual filesystem. The only information stored in it
+is the path and contents of each file that was bundled.
+=head3 LAYOUT
+Any path starting with an ampersand (F<&>) or exclamation mark (F<!>) are
+reserved by F<staticperl>. They must only be used as described in this
+section.
+=over 4
+=item !
+All files that typically cannot be loaded from memory (such as dynamic
+objects or shared libraries), but have to reside in the filesystem, are
+prefixed with F<!>. Typically these files get written out to some
+(semi-)temporary directory shortly after program startup, or before being
+used.
+=item !boot
+The bootstrap file, if specified during bundling.
+=item !auto/
+Shared objects or dlls corresponding to dynamically-linked perl extensions
+are stored with an F<!auto/> prefix.
+=item !lib/
+External shared libraries are stored in this directory.
+=item any letter
+Any path starting with a letter is a perl library file. For example,
+F<Coro/AIO.pm> corresponds to the file loaded by C<use Coro::AIO>, and
+F<Coro/jit.pl> corresponds to C<require "Coro/jit.pl">.
+Obviously, module names shouldn't start with any other characters than
+letters :)
+=back
+=head3 FUNCTIONS
+=over 4
+=item $file = static::find $path
+Returns the data associated with the given C<$path>
+(e.g. C<Digest/MD5.pm>, C<auto/POSIX/autosplit.ix>).
+Returns C<undef> if the file isn't embedded.
+=item @paths = static::list
+Returns the list of all paths embedded in this binary.
+=back
+=head2 EXTRA FEATURES
 In addition, for the embedded loading of perl files to work, F<staticperl>
 overrides the C<@INC> array.
-=over 4
-=item $file = staticperl::find $path
-Returns the data associated with the given C<$path>
-(e.g. C<Digest/MD5.pm>, C<auto/POSIX/autosplit.ix>), which is basically
-the UNIX path relative to the perl library directory.
-Returns C<undef> if the file isn't embedded.
-=item @paths = staticperl::list
-Returns the list of all paths embedded in this binary.
-=back
 =head1 FULLY STATIC BINARIES - UCLIBC AND BUILDROOT
 To make truly static (Linux-) libraries, you might want to have a look at
 buildroot (L<http://buildroot.uclibc.org/>).
 good experiences with GCC 4.4.x but not GCC 4.5.
 To minimise code size, I used C<-pipe -ffunction-sections -fdata-sections
 -finline-limit=8 -fno-builtin-strlen -mtune=i386>. The C<-mtune=i386>
 doesn't decrease codesize much, but it makes the file much more
-compressible.
+compressible (and the execution a lot slower...).
 If you don't need Coro or threads, you can go with "linuxthreads.old" (or
 no thread support). For Coro, it is highly recommended to switch to a
 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
 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).
+workaround (and L<https://bugs.uclibc.org/2089> for discussion).
 C<ccache> support is also recommended, especially if you want
 to play around with buildroot options. Enabling the C<miniperl>
 package will probably enable all options required for a successful
 perl build. F<staticperl> itself additionally needs either C<wget>
 it from working properly in a chroot - either use dash (and link it to
 F</bin/sh> inside the chroot) or link busybox to F</bin/sh>, using it's
 built-in ash shell.
 Finally, you need F</dev/null> inside the chroot for many scripts to work
-- F<cp /dev/null output/target/dev> or bind-mounting your F</dev> will
+- either F<cp /dev/null output/target/dev> or bind-mounting your F</dev>
-both provide this.
+will provide this.
 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>
+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
 C<MAN3PODS> to be empty via the C<PERL_MM_OPT> environment variable.
 =item Gtk2
 See Pango, same problems, same solution.
+=item Net::SSLeay
+This module hasn't been significantly updated since OpenSSL is called
+OpenSSL, and fails to properly link against dependent libraries, most
+commonly, it forgets to specify -ldl when linking.
+On GNU/Linux systems this usually goes undetected, as perl usually links
+against -ldl itself and OpenSSL just happens to pick it up that way, by
+chance.
+For static builds, you either have to configure -ldl manually, or you
+cna use the following snippet in your C<postinstall> hook which patches
+Net::SSLeay after installation, which happens to work most of the time:
+   postinstall() {
+      # first install it
+      instcpan Net::SSLeay
+      # then add -ldl for future linking
+      chmod u+w "$PERL_PREFIX"/lib/auto/Net/SSLeay/extralibs.ld
+      echo " -ldl" >>"$PERL_PREFIX"/lib/auto/Net/SSLeay/extralibs.ld
+   }
 =item Pango
 In addition to the C<MAN3PODS> problem in Glib, Pango also routes around
 L<ExtUtils::MakeMaker> by compiling its files on its own. F<staticperl>

Diff Legend

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

Comparing App-Staticperl/staticperl.pod (file contents): Revision 1.39 by root, Sat Apr 2 11:00:34 2011 UTC vs. Revision 1.58 by root, Sun Jun 16 04:38:38 2013 UTC

Diff Legend

Comparing App-Staticperl/staticperl.pod (file contents):
Revision 1.39 by root, Sat Apr 2 11:00:34 2011 UTC vs.
Revision 1.58 by root, Sun Jun 16 04:38:38 2013 UTC