--- App-Staticperl/staticperl.pod 2011/02/10 08:58:36 1.34 +++ App-Staticperl/staticperl.pod 2011/04/02 11:00:34 1.39 @@ -11,6 +11,7 @@ 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 instcpan modulename... # install modules from CPAN @@ -22,7 +23,7 @@ staticperl install # fetch, configure, build and install perl staticperl cpan # run interactive cpan shell - staticperl mkperl -M '"Config_heavy.pl"' # build a perl that supports -V + staticperl mkperl -MConfig_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 @@ -141,7 +142,7 @@ =head2 PHASE 1 COMMANDS: INSTALLING PERL The most important command is F, which does basically -everything. The default is to download and install perl 5.12.2 and a few +everything. The default is to download and install perl 5.12.3 and a few modules required by F itself, but all this can (and should) be changed - see L, below. @@ -188,6 +189,16 @@ 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 @@ -254,7 +265,7 @@ staticperl instcpan AnyEvent::HTTPD # now build the perl - staticperl mkperl -M'"Config_heavy.pl"' -MAnyEvent::Impl::Perl \ + staticperl mkperl -MConfig_heavy.pl -MAnyEvent::Impl::Perl \ -MAnyEvent::HTTPD -MURI::http \ --add 'eg/httpd httpd.pm' @@ -383,31 +394,62 @@ =item C<--use> F | C<-M>F -Include the named module and trace direct dependencies. This is done by -C'ing the module from a fresh package in a subprocess and tracing -which other modules and files it actually loads. +Include the named module or perl library and trace direct +dependencies. This is done by loading the module in a subprocess and +tracing which other modules and files it actually loads. Example: include AnyEvent and AnyEvent::Impl::Perl. staticperl mkbundle --use AnyEvent --use AnyEvent::Impl::Perl -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 quotes (this is because F -I just adds the string after the C - which acts -different when confronted with quoted vs. unquoted strings). 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. +Sometimes you want to load old-style "perl libraries" (F<.pl> files), or +maybe other weirdly named files. To support this, the C<--use> option +actually tries to do what you mean, depending on the string you specify: + +=over 4 + +=item a possibly valid module name, e.g. F, F, +F. + +If the string contains no quotes, no F and no F<.>, then C<--use> +assumes that it is a normal module name. It will create a new package and +evaluate a C in it, i.e. it will load the package and do a +default import. + +The import step is done because many modules trigger more dependencies +when something is imported than without. + +=item anything that contains F or F<.> characters, +e.g. F, F. + +The string will be quoted and passed to require, as if you used C. Nothing will be imported. + +=item "path" or 'path', e.g. C<"utf8_heavy.pl">. + +If you enclose the name into single or double quotes, then the quotes will +be removed and the resulting string will be passed to require. This syntax +is form compatibility with older versions of staticperl and should not be +used anymore. + +=back + +Example: C AnyEvent::Socket, once using C (importing the +symbols), and once via C, not importing any symbols. The first +form is preferred as many modules load some extra dependencies when asked +to export symbols. + + staticperl mkbundle -MAnyEvent::Socket # use + import + staticperl mkbundle -MAnyEvent/Socket.pm # require only Example: include the required files for F to work in all its -glory (F is included automatically by this). +glory (F is included automatically by the dependency tracker). - # bourne shell - staticperl mkbundle --use '"Config_heavy.pl"' + # shell command + staticperl mkbundle -MConfig_heavy.pl # bundle specification file - use "Config_heavy.pl" + use Config_heavy.pl The C<-M>module syntax is included as a convenience that might be easier to remember than C<--use> - it's the same switch as perl itself uses @@ -471,7 +513,7 @@ Adds the given (perl) file into the bundle (and optionally call it "alias"). The F is either an absolute path or a path relative to the current directory. If an alias is specified, then this is the name it will -use for C<@INC> searches, otherwise the path F<&file> will be used as the +use for C<@INC> searches, otherwise the path F will be used as the internal name. This switch is used to include extra files into the bundle. @@ -485,7 +527,7 @@ Example: add a file F from the current directory. - staticperl mkperl --add initcode + staticperl mkperl --add 'initcode &initcode' # can be accessed via "do '&initcode'" @@ -683,6 +725,29 @@ staticperl mkbundle --app myexe --boot appfile +=item C<--ignore-env> + +Generates extra code to unset some environment variables before +initialising/running perl. Perl supports a lot of environment variables +that might alter execution in ways that might be undesirablre for +standalone applications, and this option removes those known to cause +trouble. + +Specifically, these are removed: + +C and C can cause underaible +output, C, C, C and +C can alter execution significantly, and C, +C and C can affect input and output. + +The variables C and C are always ignored because the +startup code used by F overrides C<@INC> in all cases. + +This option will not make your program more secure (unless you are +running with elevated privileges), but it will reduce the surprise effect +when a user has these environment variables set and doesn't expect your +standalone program to act like a perl interpreter. + =item C<--static> Add C<-static> to F, which means a fully static (if @@ -827,9 +892,9 @@ =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). +The perl version to install - default is currently C<5.12.3>, but C<5.8.9> +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 @@ -888,6 +953,10 @@ shell functions that are called at specific times. To provide your own commands, just define the corresponding function. +The actual order in which hooks are invoked during a full install +from scratch is C, C, C, +C, C. + Example: install extra modules from CPAN and from some directories at F time. @@ -903,20 +972,25 @@ =item preconfigure -Called just before running F<./Configur> in the perl source +Called just before running F<./Configure> 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 patchconfig + +Called after running F<./Configure> in the perl source directory to create +F<./config.sh>, but before running F<./Configure -S> to actually apply the +config. Current working directory is the perl source directory. + +Can be used to tailor/patch F or do any other modifications. + =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) -or do any other modifications. - =item postbuild Called after building, but before installing perl. Current working @@ -1132,7 +1206,7 @@ for unicode character ranges in regexes) is implemented in the C<"utf8_heavy.pl"> library: - -M'"utf8_heavy.pl"' + -Mutf8_heavy.pl Many Unicode properties in turn are defined in separate modules, such as C<"unicore/Heavy.pl"> and more specific data tables such as @@ -1161,6 +1235,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 @@ -1172,6 +1250,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>.