--- App-Staticperl/staticperl.pod 2010/12/06 20:53:44 1.2 +++ App-Staticperl/staticperl.pod 2010/12/06 21:21:44 1.7 @@ -1,6 +1,6 @@ =head1 NAME -staticperl - perl, libc, 50 modules all in one 500kb file +staticperl - perl, libc, 50 modules, all in one 500kb file =head1 SYNOPSIS @@ -28,17 +28,17 @@ =head1 DESCRIPTION This script helps you creating single-file perl interpreters, or embedding -a pelr interpreter in your apps. Single-file means that it is fully -self-contained - no separate shared objects, no autoload fragments, no .pm -or .pl files are needed. And when linking statically, you can create (or -embed) a single file that contains perl interpreter, libc, all the modules -you need and all the libraries you need. +a perl interpreter in your applications. Single-file means that it is +fully self-contained - no separate shared objects, no autoload fragments, +no .pm or .pl files are needed. And when linking statically, you can +create (or embed) a single file that contains perl interpreter, libc, all +the modules you need and all the libraries you need. -With uclibc and upx on x86, you can create a single 500kb binary that +With F and F 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. -The created files do not need write access to the filesystem (like PAR +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, here are the differences: @@ -67,9 +67,10 @@ =item * More control over included files. -PAR tries to be maintainance and hassle-free - it tries to include more files -than necessary to make sure everything works out of the box. The extra files -(such as the unicode database) can take substantial amounts of memory and filesize. +PAR tries to be maintenance and hassle-free - it tries to include more +files than necessary to make sure everything works out of the box. The +extra files (such as the unicode database) can take substantial amounts of +memory and file size. With F, the burden is mostly with the developer - only direct compile-time dependencies and L are handled automatically. @@ -90,12 +91,12 @@ your choice in F<~/.staticperl>. You can add extra modules either by letting F install them for you automatically, or by using CPAN and doing it interactively. This usually takes 5-10 minutes, depending on -the speed of your computer and your internet conenction. +the speed of your computer and your internet connection. It is possible to do program development at this stage, too. Afterwards, you create a list of files and modules you want to include, -and then either build a new perl binary (that acts just like a normla perl +and then either build a new perl binary (that acts just like a normal perl except everything is compiled in), or you create bundle files (basically C sources you can use to embed all files into your project). @@ -136,7 +137,7 @@ Most of the following commands simply run one or more steps of this sequence. -To force recompilation or reinstalaltion, you need to run F first. =over 4 @@ -156,13 +157,13 @@ =item F -Wipes the perl installation directory (usually F<~/.staticperl/perl>) and installs -the perl distribution, potentially aftering building it first. +Wipes the perl installation directory (usually F<~/.staticperl/perl>) and +installs the perl distribution, potentially after building it first. =item F [args...] -Starts an interactive CPAN shell that you cna use to install further -modules. Installs the perl first if neccessary, but apart from that, +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>. @@ -179,7 +180,7 @@ =item F directory... In the unlikely case that you have unpacked perl modules around and want -to install from these instead of from CPAN, you cna do this using this +to install from these instead of from CPAN, you can do this using this command by specifying all the directories with modules in them that you want to have built. @@ -212,7 +213,7 @@ F<~/.staticperl/mkbundle>). F is a more conventional command and expect the argument -syntax commonly used on unix clones. For example, this command builds +syntax commonly used on UNIX clones. For example, this command builds a new F binary and includes F (for F), F, F and a custom F script (from F in this distribution): @@ -231,16 +232,17 @@ As you can see, things are not quite as trivial: the L module has a hidden dependency which is not even a perl module (F), L needs at least one event loop backend that we have to -specifymanually (here L), and the F module +specify manually (here L), and the F module (required by L) implements various URI schemes as extra modules - since L only needs C URIs, we only need -to include that module. +to include that module. I found out about these dependencies by carefully +watching any error messages about missing modules... =head3 OPTION PROCESSING -All options can be given as arguments on the commandline (typically using -long (e.g. C<--verbose>) or short option (e.g. C<-v>) style). Since -specifying a lot of modules can make the commandlien very cumbersome, +All options can be given as arguments on the command line (typically +using long (e.g. C<--verbose>) or short option (e.g. C<-v>) style). Since +specifying a lot of modules can make the command line very cumbersome, you can put all long options into a "bundle specification file" (with or without C<--> prefix) and specify this bundle file instead. @@ -257,7 +259,7 @@ add eg/httpd httpd.pm All options that specify modules or files to be added are processed in the -order given on the commandline (that affects the C<--use> and C<--eval> +order given on the command line (that affects the C<--use> and C<--eval> options at the moment). =head3 MKBUNDLE OPTIONS @@ -278,11 +280,14 @@ sources included. The default is C, which uses the L module to remove all -pod documenatiton, which is very fast and reduces filesize a lot. +pod documentation, which is very fast and reduces file size a lot. The C method uses L to parse and condense the perl sources. This -saves a lot more than just L, and is generally safer, but is -also a lot slower, so is best used for production builds. +saves a lot more than just L, and is generally safer, but +is also a lot slower, so is best used for production builds. Note that +this method doesn't optimise for raw file size, but for best compression +(that means that the uncompressed file size is a bit larger, but the files +compress better, e.g. with F). Last not least, in the unlikely case where C is too slow, or some module gets mistreated, you can specify C to not mangle included @@ -294,7 +299,7 @@ will be called F and will be left in the current working directory. The bundle files will be removed. -This switch is automatically ued when F is invoked with the +This switch is automatically used when F is invoked with the C command (instead of C): # build a new ./perl with only common::sense in it - very small :) @@ -313,7 +318,7 @@ Sometimes you want to load old-style "perl libraries" (F<.pl> files), or maybe other weirdly named files. To do that, you need to quote the name in -single or double quoutes. When given on the commandline, you probably need +single or double quotes. When given on the command line, you probably need to quote once more to avoid your shell interpreting it. Common cases that need this are F and F. @@ -340,7 +345,7 @@ Keep in mind that F will only C the modules named by the C<--use> option, so do not expect the symbols from modules you -C<--use>'d earlier on the commandlien to be available. +C<--use>'d earlier on the command line to be available. Example: force L to detect a backend and therefore include it in the final bundle. @@ -360,7 +365,7 @@ Include the given file in the bundle and arrange for it to be executed (using a C) before anything else when the new perl is initialised. This can be used to modify C<@INC> or anything else before -the perl interpreter executes scripts given on the commandline (or via +the perl interpreter executes scripts given on the command line (or via C<-e>). This works even in an embedded interpreter. =item --add "file" | --add "file alias" @@ -427,7 +432,7 @@ =back -=head4 Variables you I to override +=head4 Variables you might I to override =over 4 @@ -441,45 +446,45 @@ The URL of the CPAN mirror to use (e.g. L). -=item C, C, C, C - -These flags are passed to perl's F script, and are generally -optimised for small size (at the cost of performance). Since they also -contain subtle workarounds around various build issues, changing these -usually requires understanding their default values - best look at the top -of the F script for more info on these. +=item C -=item C +Additional modules installed during F. Here you can +set which modules you want have to installed from CPAN. -The directory where staticperl stores all its files -(default: F<~/.staticperl>). +Example: I really really need EV, AnyEvent, Coro and IO::AIO. -=item C + EXTRA_MODULES="EV AnyEvent Coro IO::AIO" -The prefix where perl get's installed (default: F<$STATICPERL/perl>), -i.e. where the F and F subdirectories will end up. +Note that you can also use a C hook to achieve this, and +more. -=item C, C, others +=item C, 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. -=item C +=item C -Additional modules installed during F. Here you can -set which modules you want have to installed from CPAN. +The directory where staticperl stores all its files +(default: F<~/.staticperl>). -Example: I really really need EV, AnyEvent, Coro and IO::AIO. +=item C - EXTRA_MODULES="EV AnyEvent Coro IO::AIO" +The prefix where perl gets installed (default: F<$STATICPERL/perl>), +i.e. where the F and F subdirectories will end up. -Note that you cna also use a C hook to achieve this, and -more. +=item C, C, C, C + +These flags are passed to perl's F script, and are generally +optimised for small size (at the cost of performance). Since they also +contain subtle workarounds around various build issues, changing these +usually requires understanding their default values - best look at the top +of the F script for more info on these. =back -=head4 Variables you I to override +=head4 Variables you probably I to override =over 4 @@ -499,17 +504,17 @@ In addition to environment variables, it is possible to provide some shell functions that are called at specific times. To provide your own -commands, justd efine the corresponding function. +commands, just define the corresponding function. Example: install extra modules from CPAN and from some directories at F time. postinstall() { - rm -rf lib/threads.* # weg mit Schaden + rm -rf lib/threads* # weg mit Schaden instcpan IO::AIO EV instsrc ~/src/AnyEvent instsrc ~/src/XML-Sablotron-1.0100001 - instcpan AnyEvent::HTTPD + instcpan Anyevent::AIO AnyEvent::HTTPD } =over 4