--- App-Staticperl/staticperl.pod 2010/12/07 09:27:54 1.10 +++ App-Staticperl/staticperl.pod 2010/12/08 23:01:30 1.15 @@ -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,6 +25,8 @@ 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 @@ -83,6 +86,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 +194,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 +249,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 +327,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 @@ -417,7 +460,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: @@ -443,18 +486,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). @@ -464,25 +495,37 @@ 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. @@ -544,13 +587,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 @@ -709,10 +760,11 @@ 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 or C. +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 -