[ViewVC] Diff of: cvs/App-Staticperl/staticperl.pod

Comparing App-Staticperl/staticperl.pod (file contents):
Revision 1.59 by root, Mon Jul 6 23:33:15 2015 UTC vs.
Revision 1.67 by root, Fri Aug 4 03:58:52 2023 UTC

 =head1 THE F<STATICPERL> SCRIPT
 This module installs a script called F<staticperl> into your perl
 binary directory. The script is fully self-contained, and can be
-used without perl (for example, in an uClibc chroot environment). In
+used without perl (for example, in an uClibc/dietlibc/musl chroot
-fact, it can be extracted from the C<App::Staticperl> distribution
+environment). In fact, it can be extracted from the C<App::Staticperl>
-tarball as F<bin/staticperl>, without any installation. The
+distribution tarball as F<bin/staticperl>, without any installation. The
 newest (possibly alpha) version can also be downloaded from
 L<http://staticperl.schmorp.de/staticperl>.
 F<staticperl> interprets the first argument as a command to execute,
 optionally followed by any parameters.
 Wipes the perl installation directory (usually F<~/.staticperl/perl>) and
 installs the perl distribution, potentially after building it first.
 =item F<staticperl perl> [args...]
-Invokes the compiled perl interpreter with the given args. Basically the
+Invokes the compiled perl interpreter with the given
-same as starting perl directly (usually via F<~/.staticperl/bin/perl>),
+arguments. Basically the same as starting perl directly (usually via
-but beats typing the path sometimes.
+F<~/.staticperl/bin/perl>), but beats typing the path sometimes.
 Example: check that the Gtk2 module is installed and loadable.
    staticperl perl -MGtk2 -e0
    my $res = do "myfiles/file3.pl";
 =item C<--addbin> F<file> | C<--addbin> "F<file> alias"
 Just like C<--add>, except that it treats the file as binary and adds it
-without any postprocessing (perl files might get stripped to reduce their
+without any post-processing (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>.
 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<unshift> that path onto C<@INC>.
-#TODO: example
+(TODO for future self: write and insert a suitable example here, if
+somebody requests it).
 =back
 =item Step 2: filter all files using C<--include> and C<--exclude> options.
 Last not least, if you need accurate line numbers in error messages,
 or in the unlikely case where C<pod> is too slow, or some module gets
 mistreated, you can specify C<none> to not mangle included perl sources in
 any way.
+=item C<--compress> C<none>|C<lzf>
+Compress each included library file with C<lzf> (default), or do not
+compress (C<none>). LZF compression typically halves the size of the
+included library data at almost no overhead, but is counterproductive if
+you are using another compression solution such as C<UPX>, so it can be
+disabled.
 =item C<--perl>
 After writing out the bundle files, try to link a new perl interpreter. It
 will be called F<perl> and will be left in the current working
 directory. The bundle files will be removed.
 =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
+that might alter execution in ways that might be undesirable for
 standalone applications, and this option removes those known to cause
 trouble.
 Specifically, these are removed:
 The default is to link the new binary dynamically (that means all perl
 modules are linked statically, but all external libraries are still
 referenced dynamically).
 Keep in mind that Solaris doesn't support static linking at all, and
-systems based on GNU libc don't really support it in a very usable
+systems based on GNU libc don't really support it in a very usable fashion
-fashion either. Try uClibc if you want to create fully statically linked
+either. Try dietlibc or musl if you want to create fully statically linked
 executables, or try the C<--staticlib> option to link only some libraries
 statically.
 =item C<--staticlib> libname
    staticperl mkperl -MIO::AIO --staticlib crypt
    # ldopts might now contain:
    # -lm -Wl,-Bstatic -lcrypt -Wl,-Bdynamic -lpthread
+=item C<--extra-cflags> string
+Specifies extra compiler flags, used when compiling the bundle file. The
+flags are appended to all the existing flags, so can be sued to override
+settings.
+=item C<--extra-ldflags> string
+Specifies extra linker flags, used when linking the bundle.
+=item C<--extra-libs> string
+Extra linker flags, appended at the end when linking. The difference to
+C<--extra-ldflags> is that the ldflags are appended to the flags, before
+the objects and libraries, and the extra libs are added at the end.
 =back
 =back
 =head3 EXTENDED GLOB PATTERNS
 In them you can override shell variables, or define shell functions
 ("hooks") to be called at specific phases during installation. For
 example, you could define a C<postinstall> hook to install additional
 modules from CPAN each time you start from scratch.
-If the env variable C<$STATICPERLRC> is set, then F<staticperl> will try
+If the environment variable C<$STATICPERLRC> is set, then F<staticperl>
-to source the file named with it only. Otherwise, it tries the following
+will try to source the file named with it only. Otherwise, it tries the
-shell files in order:
+following shell files in order:
    /etc/staticperlrc
    ~/.staticperlrc
    $STATICPERL/rc
 downloaded perl sources are being cached, to avoid downloading them
 again. The default is empty, which means there is no cache.
 =item C<PERL_VERSION>
-The perl version to install - default is currently C<5.12.3>, but C<5.8.9>
+The perl version to install - C<5.12.5> is a good choice for small builds,
-is also a good choice (5.8.9 is much smaller than 5.12.3, while 5.10.1 is
+but C<5.8.9> is also a good choice (5.8.9 is much smaller than 5.12.5), if
-about as big as 5.12.3).
+it builds on your system.
+You can also set this variable to the absolute URL of a tarball (F<.tar>,
+F<.tar.gz>, F<.tar.bz2>, F<.tar.lzma> or F<.tar.xz>), or to the absolute
+path of an unpacked perl source tree, which will be copied.
+The default is currently
+F<http://stableperl.schmorp.de/dist/latest.tar.gz>, i.e. the latest
+stableperl release.
 =item C<PERL_MM_USE_DEFAULT>, C<EV_EXTRA_DEFS>, ...
 Usually set to C<1> to make modules "less inquisitive" during their
 installation. You can set (and export!) any environment variable you want
 =item C<PERL_CONFIGURE>
 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<forks> instead!) you would pass C<-Duseithreads>
+insanity? Don't! Use L<Coro> or L<forks> instead!) you would pass
-and so on.
+C<-Duseithreads> and so on.
 More commonly, you would either activate 64 bit integer support
-(C<-Duse64bitint>), or disable large files support (-Uuselargefiles), to
+(C<-Duse64bitint>), or disable large files support (C<-Uuselargefiles>),
-reduce filesize further.
+to reduce file size further.
 =item C<PERL_CC>, C<PERL_CCFLAGS>, C<PERL_OPTIMIZE>, C<PERL_LDFLAGS>, C<PERL_LIBS>
 These flags are passed to perl's F<Configure> script, and are generally
 optimised for small size (at the cost of performance). Since they also
 F<~/.staticperlrc> to override them.
 Most of the variables override (or modify) the corresponding F<Configure>
 variable, except C<PERL_CCFLAGS>, which gets appended.
-The default for C<PERL_OPTIMIZE> is C<-Os> (assuming gcc), and for
+The default for C<PERL_OPTIMIZE> is C<-Os> (assuming gcc or compatible
-C<PERL_LIBS> is C<-lm -lcrypt>, which should be good for most (but not
+compilers), and for C<PERL_LIBS> is C<-lm -lcrypt>, which should be good
-all) systems.
+for most (but not all) systems.
 For other compilers or more customised optimisation settings, you need to
 adjust these, e.g. in your F<~/.staticperlrc>.
-With gcc on x86 and amd64, you can get more space-savings by using:
+With gcc on x86 and amd64, you can often get more space-savings by using:
    -Os -ffunction-sections -fdata-sections -finline-limit=8 -mpush-args
    -mno-inline-stringops-dynamically -mno-align-stringops
 And on x86 and pentium3 and newer (basically everything you might ever
 want to run on), adding these is even better for space-savings (use
--mtune=core2 or something newer for much faster code, too):
+C<-mtune=core2> or something newer for much faster code, too):
    -fomit-frame-pointer -march=pentium3 -mtune=i386
 =back
 Called after building, but before installing perl. Current working
 directory is the perl source directory.
 I have no clue what this could be used for - tell me.
+=item postcpanconfig
+Called just after CPAN has been configured, but before it has been used to
+install anything. You can further change the configuration like this:
+   "$PERL_PREFIX"/bin/perl -MCPAN::MyConfig -MCPAN -e '
+      CPAN::Shell->o (conf => urllist => push => "'"$CPAN"'");
+   ' || fatal "error while initialising CPAN in postcpanconfig"
 =item postinstall
 Called after perl and any extra modules have been installed in C<$PREFIX>,
 but before setting the "installation O.K." flag.
       staticperl_init (0);
       newXSproto ("myapp::xsfunction", xsfunction, __FILE__, "$$;$");
       eval_pv ("require myapp::main", 1); // executes "myapp/main.pm"
    }
-When your bootcode already wants to access some XS functions at
+When your boot code already wants to access some XS functions at compile
-compiletime, then you need to supply an C<xs_init> function pointer that
+time, then you need to supply an C<xs_init> function pointer that is
-is called as soon as perl is initialised enough to define XS functions,
+called as soon as perl is initialised enough to define XS functions, but
-but before the preamble code is executed:
+before the preamble code is executed:
    static void
    xs_init (pTHX)
    {
      newXSproto ("myapp::xsfunction", xsfunction, __FILE__, "$$;$");
 Binaries created with C<mkbundle>/C<mkperl> 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
+pages in this way are usually freed by the operating system, as they aren't
-use more the onace.
+used more then once.
 =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
+Any paths starting with an ampersand (F<&>) or exclamation mark (F<!>) are
 reserved by F<staticperl>. They must only be used as described in this
 section.
 =over 4
 =item any letter
 Any path starting with a letter is a perl library file. For example,
 F<Coro/AIO.pm> corresponds to the file loaded by C<use Coro::AIO>, and
 F<Coro/jit.pl> corresponds to C<require "Coro/jit.pl">.
 Obviously, module names shouldn't start with any other characters than
 letters :)
 =back
 =over 4
 =item utf8
-Some functionality in the utf8 module, such as swash handling (used
+Some functionality in the C<utf8> module, such as swash handling
-for unicode character ranges in regexes) is implemented in the
+(used for unicode character ranges in regexes) is implemented in the
-C<"utf8_heavy.pl"> library:
+C<utf8_heavy.pl> library:
    -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
+such as C<unicore/Heavy.pl> and more specific data tables such as
-C<"unicore/To/Digit.pl"> or C<"unicore/lib/Perl/Word.pl">. These tables
+C<unicore/To/Digit.pl> or C<unicore/lib/Perl/Word.pl>. These tables
 are big (7MB uncompressed, although F<staticperl> contains special
-handling for those files), so including them on demand by your application
+handling for those files), so including them only on demand in your
-only might pay off.
+application might pay off.
 To simply include the whole unicode database, use:
    --incglob '/unicore/**.pl'
 =item Net::SSLeay
 This module hasn't been significantly updated since OpenSSL is called
 OpenSSL, and fails to properly link against dependent libraries, most
-commonly, it forgets to specify -ldl when linking.
+commonly, it forgets to specify C<-ldl> when linking.
 On GNU/Linux systems this usually goes undetected, as perl usually links
-against -ldl itself and OpenSSL just happens to pick it up that way, by
+against C<-ldl> itself and OpenSSL just happens to pick it up that way, by
 chance.
-For static builds, you either have to configure -ldl manually, or you
+For static builds, you either have to configure C<-ldl> manually, or you
-cna use the following snippet in your C<postinstall> hook which patches
+can use the following snippet in your C<postinstall> hook which patches
 Net::SSLeay after installation, which happens to work most of the time:
    postinstall() {
       # first install it
       instcpan Net::SSLeay

Diff Legend

-–
+Removed lines
-+
+Added lines
-<
+Changed lines
->
+Changed lines

Comparing App-Staticperl/staticperl.pod (file contents): Revision 1.59 by root, Mon Jul 6 23:33:15 2015 UTC vs. Revision 1.67 by root, Fri Aug 4 03:58:52 2023 UTC

Diff Legend

Comparing App-Staticperl/staticperl.pod (file contents):
Revision 1.59 by root, Mon Jul 6 23:33:15 2015 UTC vs.
Revision 1.67 by root, Fri Aug 4 03:58:52 2023 UTC