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

Comparing App-Staticperl/staticperl.pod (file contents):
Revision 1.37 by root, Thu Feb 24 07:01:46 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.
 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
 =over 4
 =head3 OVERRIDABLE HOOKS
 In addition to environment variables, it is possible to provide some
 shell functions that are called at specific times. To provide your own
 commands, just define the corresponding function.
+The actual order in which hooks are invoked during a full install
+from scratch is C<preconfigure>, C<patchconfig>, C<postconfigure>,
+C<postbuild>, C<postinstall>.
 Example: install extra modules from CPAN and from some directories
 at F<staticperl install> time.
    postinstall() {
 =over 4
 =item preconfigure
-Called just before running F<./Configur> in the perl source
+Called just before running F<./Configure> 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 patchconfig
+Called after running F<./Configure> in the perl source directory to create
+F<./config.sh>, but before running F<./Configure -S> to actually apply the
+config. Current working directory is the perl source directory.
+Can be used to tailor/patch F<config.sh> or do any other modifications.
 =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<sh Configure -S>)
-or do any other modifications.
 =item postbuild
 Called after building, but before installing perl. Current working
 directory is the perl source directory.
 =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.37 by root, Thu Feb 24 07:01:46 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.37 by root, Thu Feb 24 07:01:46 2011 UTC vs.
Revision 1.50 by root, Wed Jul 13 17:47:40 2011 UTC