--- App-Staticperl/staticperl.pod 2010/12/07 09:08:06 1.9 +++ App-Staticperl/staticperl.pod 2010/12/08 23:03:21 1.16 @@ -16,6 +16,7 @@ staticperl instcpan modulename... # install modules from CPAN staticperl mkbundle # see documentation staticperl mkperl # see documentation + staticperl mkapp appname # see documentation Typical Examples: @@ -24,15 +25,18 @@ staticperl mkperl -M '"Config_heavy.pl"' # build a perl that supports -V staticperl mkperl -MAnyEvent::Impl::Perl -MAnyEvent::HTTPD -MURI -MURI::http # build a perl with the above modules linked in + staticperl mkapp myapp --boot mainprog mymodules + # build a binary "myapp" from mainprog and mymodules =head1 DESCRIPTION -This script helps you creating single-file perl interpreters, or embedding -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. +This script helps you to create single-file perl interpreters +or applications, or embedding 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, all +the libraries you need and of course your actual program. 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, @@ -83,6 +87,11 @@ build and possibly fiddling with some modules. PAR is likely to produce results faster. +Ok, PAR never has worked for me out of the box, and for some people, +F does work out of the box, as they don't count "fiddling with +module use lists" against it, but nevertheless, F is certainly +a bit more difficult to use. + =back =head1 HOW DOES IT WORK? @@ -186,9 +195,12 @@ =item F -Runs F in the perl source directory (and potentially -cleans up other intermediate files). This can be used to clean up -intermediate files without removing the installed perl interpreter. +Deletes the perl source directory (and potentially cleans up other +intermediate files). This can be used to clean up files only needed for +building perl, without removing the installed perl interpreter, or to +force a re-build from scratch. + +At the moment, it doesn't delete downloaded tarballs. =item F @@ -238,6 +250,16 @@ to include that module. I found out about these dependencies by carefully watching any error messages about missing modules... +Instead of building a new perl binary, you can also build a standalone +application: + + # build the app + staticperl mkapp app --boot eg/httpd \ + -MAnyEvent::Impl::Perl -MAnyEvent::HTTPD -MURI::http + + # run it + ./app + =head3 OPTION PROCESSING All options can be given as arguments on the command line (typically @@ -306,6 +328,28 @@ # build a new ./perl with only common::sense in it - very small :) staticperl mkperl -Mcommon::sense +=item --app name + +After writing out the bundle files, try to link a new standalone +program. It will be called C, and the bundle files get removed after +linking it. + +The difference to the (mutually exclusive) C<--perl> option is that the +binary created by this option will not try to act as a perl interpreter - +instead it will simply initialise the perl interpreter, clean it up and +exit. + +This switch is automatically used when F is invoked with the +C command (instead of C): + +To let it do something useful you I add some boot code, e.g. with +the C<--boot> option. + +Example: create a standalone perl binary that will execute F when +it is started. + + staticperl mkbundle --app myexe --boot appfile + =item --use module | -Mmodule Include the named module and all direct dependencies. This is done by @@ -385,6 +429,18 @@ add file2 myfiles/file2 add file3 myfiles/file3 +=item --binadd "file" | --add "file alias" + +Just like C<--add>, except that it treats the file as binary and adds it +without any processing. + +You should probably add a C prefix to avoid clashing with embedded +perl files (whose paths do not start with C), and/or use a special +directory, such as C. + +You can later get a copy of these files by calling C. + =item --static When C<--perl> is also given, link statically instead of dynamically. The @@ -405,7 +461,7 @@ =back -=head2 F CONFIGURATION AND HOOKS +=head2 F CONFIGURATION AND HOOKS During (each) startup, F tries to source the following shell files in order: @@ -431,18 +487,6 @@ The e-mail address of the person who built this binary. Has no good default, so should be specified by you. -=back - -=head4 Variables you might I to override - -=over 4 - -=item C - -The perl version to install - default is currently C<5.12.2>, but C<5.8.9> -is also a good choice (5.8.9 is much smaller than 5.12.2, while 5.10.1 is -about as big as 5.12.2). - =item C The URL of the CPAN mirror to use (e.g. L). @@ -452,29 +496,53 @@ Additional modules installed during F. Here you can set which modules you want have to installed from CPAN. -Example: I really really need EV, AnyEvent, Coro and IO::AIO. +Example: I really really need EV, AnyEvent, Coro and AnyEvent::AIO. - EXTRA_MODULES="EV AnyEvent Coro IO::AIO" + EXTRA_MODULES="EV AnyEvent Coro AnyEvent::AIO" Note that you can also use a C hook to achieve this, and more. +=back + +=head4 Variables you might I to override + +=over 4 + +=item C + +The directory where staticperl stores all its files +(default: F<~/.staticperl>). + =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 -The directory where staticperl stores all its files -(default: F<~/.staticperl>). +The perl version to install - default is currently C<5.12.2>, but C<5.8.9> +is also a good choice (5.8.9 is much smaller than 5.12.2, while 5.10.1 is +about as big as 5.12.2). -=item C +=item C The prefix where perl gets installed (default: F<$STATICPERL/perl>), i.e. where the F and F subdirectories will end up. +=item C + +Additional Configure options - these are simply passed to the perl +Configure script. For example, if you wanted to enable dynamic loading, +you could pass C<-Dusedl>. To enable ithreads (Why would you want that +insanity? Don't! Use L instead!) you would pass C<-Duseithreads> +and so on. + +More commonly, you would either activate 64 bit integer support +(C<-Duse64bitint>), or disable large files support (-Uuselargefiles), to +reduce filesize further. + =item C, C, C, C These flags are passed to perl's F script, and are generally @@ -520,13 +588,21 @@ =over 4 +=item preconfigure + +Called just before running F<./Configur> in the perl source +directory. Current working directory is the perl source directory. + +This can be used to set any C variables, which might be costly +to compute. + =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<./Configure -S>) or -do any other modifications. +Could be used to tailor/patch config.sh (followed by F) +or do any other modifications. =item postbuild @@ -656,7 +732,7 @@ =head1 FULLY STATIC BINARIES - BUILDROOT -To make truly static (linux-) libraries, you might want to have a look at +To make truly static (Linux-) libraries, you might want to have a look at buildroot (L). Buildroot is primarily meant to set up a cross-compile environment (which @@ -680,10 +756,16 @@ ultra-slow pthreads backend to work around linuxthreads bugs (it also uses twice the address space needed for stacks). -C support is also recommended, especially if you want to -play around with buildroot options. Enabling the C package -will probably enable all options required for a successful perl -build. F itself additionally needs either C or C. +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). + +C support is also recommended, especially if you want +to play around with buildroot options. Enabling the C +package will probably enable all options required for a successful +perl build. F itself additionally needs either C +(recommended, for CPAN) or C. As for shells, busybox should provide all that is needed, but the default busybox configuration doesn't include F which is needed by perl -