--- App-Staticperl/staticperl.pod	2010/12/06 21:21:44	1.7
+++ App-Staticperl/staticperl.pod	2010/12/07 09:08:06	1.9
@@ -1,6 +1,6 @@
 =head1 NAME
 
-staticperl - perl, libc, 50 modules, all in one 500kb file
+staticperl - perl, libc, 100 modules, all in one 500kb file
 
 =head1 SYNOPSIS
 
@@ -34,9 +34,9 @@
 create (or embed) a single file that contains perl interpreter, libc, all
 the modules you need and all the libraries you need.
 
-With F<uClibc> and F<upx> on x86, you can create a single 500kb binary that
-contains perl and 50 modules such as AnyEvent, EV, IO::AIO, Coro and so
-on. Or any other choice of modules.
+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.
 
 The created files do not need write access to the file system (like PAR
 does). In fact, since this script is in many ways similar to PAR::Packer,
@@ -289,9 +289,10 @@
 (that means that the uncompressed file size is a bit larger, but the files
 compress better, e.g. with F<upx>).
 
-Last not least, in the unlikely case where C<pod> is too slow, or some
-module gets mistreated, you can specify C<none> to not mangle included
-perl sources in any way.
+Last not least, if you need accurate line numbers in error messages,
+or in the unlikely case where C<pod> is too slow, or some module gets
+mistreated, you can specify C<none> to not mangle included perl sources in
+any way.
 
 =item --perl
 
@@ -550,6 +551,158 @@
 
 =back
 
+=head1 ANATOMY OF A BUNDLE
+
+When not building a new perl binary, C<mkbundle> will leave a number of
+files in the current working directory, which can be used to embed a perl
+interpreter in your program.
+
+Intimate knowledge of L<perlembed> and preferably some experience with
+embedding perl is highly recommended.
+
+C<mkperl> (or the C<--perl> option) basically does this to link the new
+interpreter (it also adds a main program to F<bundle.>):
+
+   $Config{cc} $(cat bundle.ccopts) -o perl bundle.c $(cat bundle.ldopts)
+
+=over 4
+
+=item bundle.h
+
+A header file that contains the prototypes of the few symbols "exported"
+by bundle.c, and also exposes the perl headers to the application.
+
+=over 4
+
+=item staticperl_init ()
+
+Initialises the perl interpreter. You can use the normal perl functions
+after calling this function, for example, to define extra functions or
+to load a .pm file that contains some initialisation code, or the main
+program function:
+
+   XS (xsfunction)
+   {
+     dXSARGS;
+
+     // now we have items, ST(i) etc.
+   }
+
+   static void
+   run_myapp(void)
+   {
+      staticperl_init ();
+      newXSproto ("myapp::xsfunction", xsfunction, __FILE__, "$$;$");
+      eval_pv ("require myapp::main", 1); // executes "myapp/main.pm"
+   }
+
+=item staticperl_xs_init (pTHX)
+
+Sometimes you need direct control over C<perl_parse> and C<perl_run>, in
+which case you do not want to use C<staticperl_init> but call them on your
+own.
+
+Then you need this function - either pass it directly as the C<xs_init>
+function to C<perl_parse>, or call it from your own C<xs_init> function.
+
+=item staticperl_cleanup ()
+
+In the unlikely case that you want to destroy the perl interpreter, here
+is the corresponding function.
+
+=item PerlInterpreter *staticperl
+
+The perl interpreter pointer used by staticperl. Not normally so useful,
+but there it is.
+
+=back
+
+=item bundle.ccopts
+
+Contains the compiler options required to compile at least F<bundle.c> and
+any file that includes F<bundle.h> - you should probably use it in your
+C<CFLAGS>.
+
+=item bundle.ldopts
+
+The linker options needed to link the final program.
+
+=back
+
+=head1 RUNTIME FUNCTIONALITY
+
+Binaries created with C<mkbundle>/C<mkperl> contain extra functions, which
+are required to access the bundled perl sources, but might be useful for
+other purposes.
+
+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 - BUILDROOT
+
+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>.
+
+To do so, download buildroot, and enable "Build options => development
+files in target filesystem" and optionally "Build options => gcc
+optimization level (optimize for size)". At the time of writing, I had
+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.
+
+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
+ultra-slow pthreads backend to work around linuxthreads bugs (it also uses
+twice the address space needed for stacks).
+
+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> 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.
+
+For the latter route, you might find that bash has some bugs that keep
+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
+both 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>
+filesystem, chroot inside and run it.
+
 =head1 AUTHOR
 
  Marc Lehmann <schmorp@schmorp.de>