--- App-Staticperl/staticperl.pod	2010/12/06 21:30:05	1.8
+++ App-Staticperl/staticperl.pod	2010/12/07 09:08:06	1.9
@@ -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>