--- App-Staticperl/staticperl.pod 2011/03/18 19:49:04 1.38 +++ App-Staticperl/staticperl.pod 2011/07/13 17:47:40 1.50 @@ -11,8 +11,9 @@ 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 # see documentation staticperl mkperl # see documentation @@ -40,7 +41,7 @@ With F and F 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 @@ -85,7 +86,7 @@ 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 does not. @@ -188,12 +189,24 @@ Wipes the perl installation directory (usually F<~/.staticperl/perl>) and installs the perl distribution, potentially after building it first. +=item F [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 [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 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 command. @@ -538,16 +551,16 @@ 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 -clashing with embedded perl files (whose paths never start with C<&>), -and/or use a special directory prefix, such as C<&res/name>. +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), +and/or use a special directory prefix, such as C. -You can later get a copy of these files by calling C. An alternative way to embed binary files is to convert them to perl and use C 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' @@ -557,6 +570,23 @@ # load the binary chomp (my $data = do "bindata.pl"); +=item C<--allow-dynamic> + +By default, when F 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 packages the shared +object into the bundle instead, with a prefix of F +(e.g. F). What you do with that is currently up +to you, F has no special support for this at the moment, apart +from working around the lack of availability of F 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 that path onto C<@INC>. + +#TODO: example + =back =item Step 2: filter all files using C<--include> and C<--exclude> options. @@ -873,11 +903,11 @@ The directory where staticperl stores all its files (default: F<~/.staticperl>). -=item C, C, ... +=item C -Usually set to C<1> to make modules "less inquisitive" during their -installation, you can set any environment variable you want - some modules -(such as L or L) use environment variables for further tweaking. +The path to a directory (will be created if it doesn't exist) where +downloaded perl sources are being cached, to avoid downloading them +again. The default is empty, which means there is no cache. =item C @@ -885,6 +915,13 @@ 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, C, ... + +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 or L) use environment variables for +further tweaking. + =item C The prefix where perl gets installed (default: F<$STATICPERL/perl>), @@ -914,6 +951,11 @@ Most of the variables override (or modify) the corresponding F variable, except C, which gets appended. +You should have a look near the beginning of the F script - +staticperl tries to default C 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 to override @@ -1101,29 +1143,80 @@ =head1 RUNTIME FUNCTIONALITY -Binaries created with C/C contain extra functions, which -are required to access the bundled perl sources, but might be useful for -other purposes. +Binaries created with C/C contain extra functionality, +mostly related to the extra files bundled in the binary (the virtual +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. They must only be used as described in this +section. -In addition, for the embedded loading of perl files to work, F -overrides the C<@INC> array. +=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 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 corresponds to the file loaded by C, and +F corresponds to C. + +Obviously, module names shouldn't start with any other characters than +letters :) + +=back + +=head3 FUNCTIONS =over 4 -=item $file = staticperl::find $path +=item $file = static::find $path Returns the data associated with the given C<$path> -(e.g. C, C), which is basically -the UNIX path relative to the perl library directory. +(e.g. C, C). Returns C if the file isn't embedded. -=item @paths = staticperl::list +=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 +overrides the C<@INC> array. + =head1 FULLY STATIC BINARIES - UCLIBC AND BUILDROOT To make truly static (Linux-) libraries, you might want to have a look at @@ -1141,7 +1234,7 @@ 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 @@ -1153,7 +1246,7 @@ If you use C, then you should also be aware that uClibc shares C between all threads when statically linking. See L for a -workaround (And L for discussion). +workaround (and L for discussion). C support is also recommended, especially if you want to play around with buildroot options. Enabling the C @@ -1171,12 +1264,12 @@ built-in ash shell. Finally, you need F inside the chroot for many scripts to work -- F or bind-mounting your F will -both provide this. +- either F or bind-mounting your F +will provide this. After you have compiled and set up your buildroot target, you can copy F from the C distribution or from your -perl f directory (if you installed it) into the F +perl F directory (if you installed it) into the F filesystem, chroot inside and run it. =head1 RECIPES / SPECIFIC MODULES @@ -1224,6 +1317,10 @@ 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. As of @@ -1235,6 +1332,23 @@ 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 tries to work around this by forcing C and +C to be empty via the C environment variable. + +=item Gtk2 + +See Pango, same problems, same solution. + +=item Pango + +In addition to the C problem in Glib, Pango also routes around +L by compiling its files on its own. F +tries to patch L to route around Pango. + =item Term::ReadLine::Perl Also needs L, or C<--usepacklists>.