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

Comparing App-Staticperl/staticperl.pod (file contents):
Revision 1.38 by root, Fri Mar 18 19:49:04 2011 UTC vs.
Revision 1.50 by root, Wed Jul 13 17:47:40 2011 UTC

    staticperl configure # fetch and then configure perl
    staticperl build     # configure and then build perl
    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 install>
 Wipes the perl installation directory (usually F<~/.staticperl/perl>) and
 installs the perl distribution, potentially after building it first.
+=item F<staticperl perl> [args...]
+Invokes the compiled perl interpreter with the given args. Basically the
+same as starting perl directly (usually via F<~/.staticperl/bin/perl>),
+but beats typing the path sometimes.
+Example: check that the Gtk2 module is installed and loadable.
+   staticperl perl -MGtk2 -e0
 =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...
 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.
 =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>),
 i.e. where the F<bin> and F<lib> subdirectories will end up.
 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.
+You should have a look near the beginning of the F<staticperl> script -
+staticperl tries to default C<PERL_OPTIMIZE> to some psace-saving options
+suitable for newer gcc versions. For other compilers or older versions you
+need to adjust these, for example, in your F<~/.staticperlrc>.
 =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<"AnyEvent/Util/uts46data.pl">.
 Or you can use C<--usepacklists> and specify C<-MAnyEvent> to include
 everything.
+=item Cairo
+See Glib, same problem, same solution.
 =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 Glib
+Glib literally requires Glib to be installed already to build - it tries
+to fake this by running Glib out of the build directory before being
+built. F<staticperl> tries to work around this by forcing C<MAN1PODS> and
+C<MAN3PODS> to be empty via the C<PERL_MM_OPT> environment variable.
+=item Gtk2
+See Pango, same problems, same solution.
+=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>
+tries to patch L<ExtUtils::MM_Unix> to route around Pango.
 =item Term::ReadLine::Perl
 Also needs L<Term::ReadLine::readline>, or C<--usepacklists>.

Diff Legend

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

Comparing App-Staticperl/staticperl.pod (file contents): Revision 1.38 by root, Fri Mar 18 19:49:04 2011 UTC vs. Revision 1.50 by root, Wed Jul 13 17:47:40 2011 UTC

Diff Legend

Comparing App-Staticperl/staticperl.pod (file contents):
Revision 1.38 by root, Fri Mar 18 19:49:04 2011 UTC vs.
Revision 1.50 by root, Wed Jul 13 17:47:40 2011 UTC