--- App-Staticperl/staticperl.pod 2011/07/13 17:47:40 1.50 +++ App-Staticperl/staticperl.pod 2023/08/04 03:58:52 1.67 @@ -1,6 +1,6 @@ =head1 NAME -staticperl - perl, libc, 100 modules, all in one 500kb file +staticperl - perl, libc, 100 modules, all in one standalone 500kb file =head1 SYNOPSIS @@ -126,9 +126,9 @@ This module installs a script called F 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 -fact, it can be extracted from the C distribution -tarball as F, without any installation. The +used without perl (for example, in an uClibc/dietlibc/musl chroot +environment). In fact, it can be extracted from the C +distribution tarball as F, without any installation. The newest (possibly alpha) version can also be downloaded from L. @@ -191,9 +191,9 @@ =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. +Invokes the compiled perl interpreter with the given +arguments. 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. @@ -350,7 +350,7 @@ All options that specify modules or files to be added are processed in the order given on the command line. -=head3 BUNDLE CREATION WORKFLOW / STATICPELR MKBUNDLE OPTIONS +=head3 BUNDLE CREATION WORKFLOW / STATICPERL MKBUNDLE OPTIONS F works by first assembling a list of candidate files and modules to include, then filtering them by include/exclude @@ -545,10 +545,10 @@ require myfiles::file2; my $res = do "myfiles/file3.pl"; -=item C<--binadd> F | C<--add> "F alias" +=item C<--addbin> F | C<--addbin> "F 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 @@ -585,7 +585,8 @@ One way to deal with this is to write all files starting with F into some directory and then C that path onto C<@INC>. -#TODO: example +(TODO for future self: write and insert a suitable example here, if +somebody requests it). =back @@ -706,6 +707,14 @@ mistreated, you can specify C to not mangle included perl sources in any way. +=item C<--compress> C|C + +Compress each included library file with C (default), or do not +compress (C). 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, so it can be +disabled. + =item C<--perl> After writing out the bundle files, try to link a new perl interpreter. It @@ -748,13 +757,13 @@ 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: -C and C can cause underaible +C and C can cause undesirable output, C, C, C and C can alter execution significantly, and C, C and C can affect input and output. @@ -779,8 +788,8 @@ 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 -fashion either. Try uClibc if you want to create fully statically linked +systems based on GNU libc don't really support it in a very usable fashion +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. @@ -802,6 +811,22 @@ # 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 @@ -854,9 +879,9 @@ example, you could define a C hook to install additional modules from CPAN each time you start from scratch. -If the env variable C<$STATICPERLRC> is set, then F will try -to source the file named with it only. Otherwise, it tries the following -shell files in order: +If the environment variable C<$STATICPERLRC> is set, then F +will try to source the file named with it only. Otherwise, it tries the +following shell files in order: /etc/staticperlrc ~/.staticperlrc @@ -911,9 +936,17 @@ =item C -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). +The perl version to install - C<5.12.5> is a good choice for small builds, +but C<5.8.9> is also a good choice (5.8.9 is much smaller than 5.12.5), if +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, i.e. the latest +stableperl release. =item C, C, ... @@ -924,20 +957,21 @@ =item C -The prefix where perl gets installed (default: F<$STATICPERL/perl>), -i.e. where the F and F subdirectories will end up. +The directory where perl gets installed (default: F<$STATICPERL/perl>), +i.e. where the F and F subdirectories will end up. Previous +contents will be removed on installation. =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. +insanity? Don't! Use L or 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. +(C<-Duse64bitint>), or disable large files support (C<-Uuselargefiles>), +to reduce file size further. =item C, C, C, C, C @@ -951,10 +985,23 @@ Most of the variables override (or modify) the corresponding F variable, except C, which gets appended. -You should have a look near the beginning of the F script - -staticperl tries to default C to some psace-saving options -suitable for newer gcc versions. For other compilers or older versions you -need to adjust these, for example, in your F<~/.staticperlrc>. +The default for C is C<-Os> (assuming gcc or compatible +compilers), and for C is C<-lm -lcrypt>, which should be good +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 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 +C<-mtune=core2> or something newer for much faster code, too): + + -fomit-frame-pointer -march=pentium3 -mtune=i386 =back @@ -1029,6 +1076,15 @@ 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>, @@ -1090,10 +1146,10 @@ eval_pv ("require myapp::main", 1); // executes "myapp/main.pm" } -When your bootcode already wants to access some XS functions at -compiletime, then you need to supply an C function pointer that -is called as soon as perl is initialised enough to define XS functions, -but before the preamble code is executed: +When your boot code already wants to access some XS functions at compile +time, then you need to supply an C function pointer that is +called as soon as perl is initialised enough to define XS functions, but +before the preamble code is executed: static void xs_init (pTHX) @@ -1147,8 +1203,8 @@ 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 -use more the onace. +pages in this way are usually freed by the operating system, as they aren't +used more then once. =head2 VIRTUAL FILESYSTEM @@ -1157,7 +1213,7 @@ =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. They must only be used as described in this section. @@ -1188,7 +1244,7 @@ Any path starting with a letter is a perl library file. For example, F corresponds to the file loaded by C, and -F corresponds to C. +F corresponds to C. Obviously, module names shouldn't start with any other characters than letters :) @@ -1217,60 +1273,19 @@ In addition, for the embedded loading of perl files to work, F overrides the C<@INC> array. -=head1 FULLY STATIC BINARIES - UCLIBC AND BUILDROOT +=head1 FULLY STATIC BINARIES - ALPINE LINUX -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 -is not so useful as perl doesn't quite like cross compiles), but it can also compile -a chroot environment where you can use F. - -To do so, download buildroot, and enable "Build options => development -files in target filesystem" and optionally "Build options => gcc -optimization level (optimize for size)". At the time of writing, I had -good experiences with GCC 4.4.x but not GCC 4.5. - -To minimise code size, I used C<-pipe -ffunction-sections -fdata-sections --finline-limit=8 -fno-builtin-strlen -mtune=i386>. The C<-mtune=i386> -doesn't decrease codesize much, but it makes the file much more -compressible (and the execution a lot slower...). - -If you don't need Coro or threads, you can go with "linuxthreads.old" (or -no thread support). For Coro, it is highly recommended to switch to a -uClibc newer than 0.9.31 (at the time of this writing, I used the 20101201 -snapshot) and enable NPTL, otherwise Coro needs to be configured with the -ultra-slow pthreads backend to work around linuxthreads bugs (it also uses -twice the address space needed for stacks). - -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 - -either make a custom busybox config, or compile coreutils. - -For the latter route, you might find that bash has some bugs that keep -it from working properly in a chroot - either use dash (and link it to -F inside the chroot) or link busybox to F, using it's -built-in ash shell. - -Finally, you need F inside the chroot for many scripts to work -- either F or bind-mounting your F -will provide this. - -After you have compiled and set up your buildroot target, you can copy -F from the C distribution or from your -perl F directory (if you installed it) into the F -filesystem, chroot inside and run it. +This section once contained a way to build fully static (including +uClibc) binaries with buildroot. Unfortunately, buildroot no longer +supports a compiler, so I recommend using alpine linux instead +(L). Get yourself a VM (e.g. with qemu), run an +older alpine linux verison in it (e.g. 2.4), copy staticperl inside and +use it. + +The reason you might want an older alpine linux is that uClibc can be +quite dependent on kernel versions, so the newest version of alpine linux +might need a newer kernel then you might want for, if you plan to run your +binaries on on other kernels. =head1 RECIPES / SPECIFIC MODULES @@ -1284,18 +1299,18 @@ =item utf8 -Some functionality in the utf8 module, such as swash handling (used -for unicode character ranges in regexes) is implemented in the -C<"utf8_heavy.pl"> library: +Some functionality in the C module, such as swash handling +(used for unicode character ranges in regexes) is implemented in the +C 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 -C<"unicore/To/Digit.pl"> or C<"unicore/lib/Perl/Word.pl">. These tables +such as C and more specific data tables such as +C or C. These tables are big (7MB uncompressed, although F contains special -handling for those files), so including them on demand by your application -only might pay off. +handling for those files), so including them only on demand in your +application might pay off. To simply include the whole unicode database, use: @@ -1343,6 +1358,28 @@ See Pango, same problems, same solution. +=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 C<-ldl> when linking. + +On GNU/Linux systems this usually goes undetected, as perl usually links +against C<-ldl> itself and OpenSSL just happens to pick it up that way, by +chance. + +For static builds, you either have to configure C<-ldl> manually, or you +can use the following snippet in your C hook which patches +Net::SSLeay after installation, which happens to work most of the time: + + postinstall() { + # first install it + instcpan Net::SSLeay + # then add -ldl for future linking + chmod u+w "$PERL_PREFIX"/lib/auto/Net/SSLeay/extralibs.ld + echo " -ldl" >>"$PERL_PREFIX"/lib/auto/Net/SSLeay/extralibs.ld + } + =item Pango In addition to the C problem in Glib, Pango also routes around @@ -1419,7 +1456,14 @@ =back +=head1 ADDITIONAL RESOURCES + +Some guy has made a repository on github +(L) with some modules +patched to build with staticperl. + =head1 AUTHOR Marc Lehmann http://software.schmorp.de/pkg/staticperl.html +