ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/App-Staticperl/staticperl.pod
(Generate patch)

Comparing App-Staticperl/staticperl.pod (file contents):
Revision 1.43 by root, Sun Jun 26 17:26:52 2011 UTC vs.
Revision 1.63 by root, Tue Mar 19 15:24:49 2019 UTC

1=head1 NAME 1=head1 NAME
2 2
3staticperl - perl, libc, 100 modules, all in one 500kb file 3staticperl - perl, libc, 100 modules, all in one standalone 500kb file
4 4
5=head1 SYNOPSIS 5=head1 SYNOPSIS
6 6
7 staticperl help # print the embedded documentation 7 staticperl help # print the embedded documentation
8 staticperl fetch # fetch and unpack perl sources 8 staticperl fetch # fetch and unpack perl sources
11 staticperl install # build and then install perl 11 staticperl install # build and then install perl
12 staticperl clean # clean most intermediate files (restart at configure) 12 staticperl clean # clean most intermediate files (restart at configure)
13 staticperl distclean # delete everything installed by this script 13 staticperl distclean # delete everything installed by this script
14 staticperl perl ... # invoke the perlinterpreter 14 staticperl perl ... # invoke the perlinterpreter
15 staticperl cpan # invoke CPAN shell 15 staticperl cpan # invoke CPAN shell
16 staticperl instmod path... # install unpacked modules 16 staticperl instsrc path... # install unpacked modules
17 staticperl instcpan modulename... # install modules from CPAN 17 staticperl instcpan modulename... # install modules from CPAN
18 staticperl mkbundle <bundle-args...> # see documentation 18 staticperl mkbundle <bundle-args...> # see documentation
19 staticperl mkperl <bundle-args...> # see documentation 19 staticperl mkperl <bundle-args...> # see documentation
20 staticperl mkapp appname <bundle-args...> # see documentation 20 staticperl mkapp appname <bundle-args...> # see documentation
21 21
84With F<staticperl>, the burden is mostly with the developer - only direct 84With F<staticperl>, the burden is mostly with the developer - only direct
85compile-time dependencies and L<AutoLoader> are handled automatically. 85compile-time dependencies and L<AutoLoader> are handled automatically.
86This means the modules to include often need to be tweaked manually. 86This means the modules to include often need to be tweaked manually.
87 87
88All this does not preclude more permissive modes to be implemented in 88All this does not preclude more permissive modes to be implemented in
89the future, but right now, you have to resolve state hidden dependencies 89the future, but right now, you have to resolve hidden dependencies
90manually. 90manually.
91 91
92=item * PAR works out of the box, F<staticperl> does not. 92=item * PAR works out of the box, F<staticperl> does not.
93 93
94Maintaining your own custom perl build can be a pain in the ass, and while 94Maintaining your own custom perl build can be a pain in the ass, and while
202=item F<staticperl cpan> [args...] 202=item F<staticperl cpan> [args...]
203 203
204Starts an interactive CPAN shell that you can use to install further 204Starts an interactive CPAN shell that you can use to install further
205modules. Installs the perl first if necessary, but apart from that, 205modules. Installs the perl first if necessary, but apart from that,
206no magic is involved: you could just as well run it manually via 206no magic is involved: you could just as well run it manually via
207F<~/.staticperl/perl/bin/cpan>. 207F<~/.staticperl/perl/bin/cpan>, except that F<staticperl> additionally
208sets the environment variable C<$PERL> to the path of the perl
209interpreter, which is handy in subshells.
208 210
209Any additional arguments are simply passed to the F<cpan> command. 211Any additional arguments are simply passed to the F<cpan> command.
210 212
211=item F<staticperl instcpan> module... 213=item F<staticperl instcpan> module...
212 214
346 add eg/httpd httpd.pm 348 add eg/httpd httpd.pm
347 349
348All options that specify modules or files to be added are processed in the 350All options that specify modules or files to be added are processed in the
349order given on the command line. 351order given on the command line.
350 352
351=head3 BUNDLE CREATION WORKFLOW / STATICPELR MKBUNDLE OPTIONS 353=head3 BUNDLE CREATION WORKFLOW / STATICPERL MKBUNDLE OPTIONS
352 354
353F<staticperl mkbundle> works by first assembling a list of candidate 355F<staticperl mkbundle> works by first assembling a list of candidate
354files and modules to include, then filtering them by include/exclude 356files and modules to include, then filtering them by include/exclude
355patterns. The remaining modules (together with their direct dependencies, 357patterns. The remaining modules (together with their direct dependencies,
356such as link libraries and L<AutoLoader> files) are then converted into 358such as link libraries and L<AutoLoader> files) are then converted into
541 # then later, in perl, use 543 # then later, in perl, use
542 use myfiles::file1; 544 use myfiles::file1;
543 require myfiles::file2; 545 require myfiles::file2;
544 my $res = do "myfiles/file3.pl"; 546 my $res = do "myfiles/file3.pl";
545 547
546=item C<--binadd> F<file> | C<--add> "F<file> alias" 548=item C<--addbin> F<file> | C<--addbin> "F<file> alias"
547 549
548Just like C<--add>, except that it treats the file as binary and adds it 550Just like C<--add>, except that it treats the file as binary and adds it
549without any postprocessing (perl files might get stripped to reduce their 551without any postprocessing (perl files might get stripped to reduce their
550size). 552size).
551 553
552If you specify an alias you should probably add a C<&> prefix to avoid 554If you specify an alias you should probably add a C</> prefix to avoid
553clashing with embedded perl files (whose paths never start with C<&>), 555clashing with embedded perl files (whose paths never start with C</>),
554and/or use a special directory prefix, such as C<&res/name>. 556and/or use a special directory prefix, such as C</res/name>.
555 557
556You can later get a copy of these files by calling C<staticperl::find 558You can later get a copy of these files by calling C<static::find
557"alias">. 559"alias">.
558 560
559An alternative way to embed binary files is to convert them to perl and 561An alternative way to embed binary files is to convert them to perl and
560use C<do> to get the contents - this method is a bit cumbersome, but works 562use C<do> to get the contents - this method is a bit cumbersome, but works
561both inside and outside of a staticperl bundle: 563both inside and outside of a staticperl bundle, without extra ado:
562 564
563 # a "binary" file, call it "bindata.pl" 565 # a "binary" file, call it "bindata.pl"
564 <<'SOME_MARKER' 566 <<'SOME_MARKER'
565 binary data NOT containing SOME_MARKER 567 binary data NOT containing SOME_MARKER
566 SOME_MARKER 568 SOME_MARKER
567 569
568 # load the binary 570 # load the binary
569 chomp (my $data = do "bindata.pl"); 571 chomp (my $data = do "bindata.pl");
572
573=item C<--allow-dynamic>
574
575By default, when F<mkbundle> hits a dynamic perl extension (e.g. a F<.so>
576or F<.dll> file), it will stop with a fatal error.
577
578When this option is enabled, F<mkbundle> packages the shared
579object into the bundle instead, with a prefix of F<!>
580(e.g. F<!auto/List/Util/Util.so>). What you do with that is currently up
581to you, F<staticperl> has no special support for this at the moment, apart
582from working around the lack of availability of F<PerlIO::scalar> while
583bootstrapping, at a speed cost.
584
585One way to deal with this is to write all files starting with F<!> into
586some directory and then C<unshift> that path onto C<@INC>.
587
588#TODO: example
570 589
571=back 590=back
572 591
573=item Step 2: filter all files using C<--include> and C<--exclude> options. 592=item Step 2: filter all files using C<--include> and C<--exclude> options.
574 593
733standalone applications, and this option removes those known to cause 752standalone applications, and this option removes those known to cause
734trouble. 753trouble.
735 754
736Specifically, these are removed: 755Specifically, these are removed:
737 756
738C<PERL_HASH_SEED_DEBUG> and C<PERL_DEBUG_MSTATS> can cause underaible 757C<PERL_HASH_SEED_DEBUG> and C<PERL_DEBUG_MSTATS> can cause undesirable
739output, C<PERL5OPT>, C<PERL_DESTRUCT_LEVEL>, C<PERL_HASH_SEED> and 758output, C<PERL5OPT>, C<PERL_DESTRUCT_LEVEL>, C<PERL_HASH_SEED> and
740C<PERL_SIGNALS> can alter execution significantly, and C<PERL_UNICODE>, 759C<PERL_SIGNALS> can alter execution significantly, and C<PERL_UNICODE>,
741C<PERLIO_DEBUG> and C<PERLIO> can affect input and output. 760C<PERLIO_DEBUG> and C<PERLIO> can affect input and output.
742 761
743The variables C<PERL_LIB> and C<PERL5_LIB> are always ignored because the 762The variables C<PERL_LIB> and C<PERL5_LIB> are always ignored because the
781 staticperl mkperl -MIO::AIO --staticlib crypt 800 staticperl mkperl -MIO::AIO --staticlib crypt
782 801
783 # ldopts might now contain: 802 # ldopts might now contain:
784 # -lm -Wl,-Bstatic -lcrypt -Wl,-Bdynamic -lpthread 803 # -lm -Wl,-Bstatic -lcrypt -Wl,-Bdynamic -lpthread
785 804
805=item C<--extra-cflags> string
806
807Specifies extra compiler flags, used when compiling the bundle file. The
808flags are appended to all the existing flags, so can be sued to override
809settings.
810
811=item C<--extra-ldflags> string
812
813Specifies extra linker flags, used when linking the bundle.
814
815=item C<--extra-libs> string
816
817Extra linker flags, appended at the end when linking. The difference to
818C<--extra-ldflags> is that the ldflags are appended to the flags, before
819the objects and libraries, and the extra libs are added at the end.
820
786=back 821=back
787 822
788=back 823=back
789 824
790=head3 EXTENDED GLOB PATTERNS 825=head3 EXTENDED GLOB PATTERNS
890downloaded perl sources are being cached, to avoid downloading them 925downloaded perl sources are being cached, to avoid downloading them
891again. The default is empty, which means there is no cache. 926again. The default is empty, which means there is no cache.
892 927
893=item C<PERL_VERSION> 928=item C<PERL_VERSION>
894 929
895The perl version to install - default is currently C<5.12.3>, but C<5.8.9> 930The perl version to install - C<5.12.5> is a good choice for small builds,
896is also a good choice (5.8.9 is much smaller than 5.12.3, while 5.10.1 is 931but C<5.8.9> is also a good choice (5.8.9 is much smaller than 5.12.5), if
897about as big as 5.12.3). 932it builds on your system.
933
934You can also set this variable to the absolute URL of a tarball (F<.tar>,
935F<.tar.gz>, F<.tar.bz2>, F<.tar.lzma> or F<.tar.xz>), or to the absolute
936path of an unpacked perl source tree, which will be copied.
937
938The default is currently
939F<http://stableperl.schmorp.de/dist/latest.tar.gz>, i.e. the latest
940stableperl release.
898 941
899=item C<PERL_MM_USE_DEFAULT>, C<EV_EXTRA_DEFS>, ... 942=item C<PERL_MM_USE_DEFAULT>, C<EV_EXTRA_DEFS>, ...
900 943
901Usually set to C<1> to make modules "less inquisitive" during their 944Usually set to C<1> to make modules "less inquisitive" during their
902installation, you can set any environment variable you want - some modules 945installation. You can set (and export!) any environment variable you want
903(such as L<Coro> or L<EV>) use environment variables for further tweaking. 946- some modules (such as L<Coro> or L<EV>) use environment variables for
947further tweaking.
904 948
905=item C<PERL_PREFIX> 949=item C<PERL_PREFIX>
906 950
907The prefix where perl gets installed (default: F<$STATICPERL/perl>), 951The directory where perl gets installed (default: F<$STATICPERL/perl>),
908i.e. where the F<bin> and F<lib> subdirectories will end up. 952i.e. where the F<bin> and F<lib> subdirectories will end up. Previous
953contents will be removed on installation.
909 954
910=item C<PERL_CONFIGURE> 955=item C<PERL_CONFIGURE>
911 956
912Additional Configure options - these are simply passed to the perl 957Additional Configure options - these are simply passed to the perl
913Configure script. For example, if you wanted to enable dynamic loading, 958Configure script. For example, if you wanted to enable dynamic loading,
929F<~/.staticperlrc> to override them. 974F<~/.staticperlrc> to override them.
930 975
931Most of the variables override (or modify) the corresponding F<Configure> 976Most of the variables override (or modify) the corresponding F<Configure>
932variable, except C<PERL_CCFLAGS>, which gets appended. 977variable, except C<PERL_CCFLAGS>, which gets appended.
933 978
934You should have a look near the beginning of the F<staticperl> script - 979The default for C<PERL_OPTIMIZE> is C<-Os> (assuming gcc), and for
935staticperl tries to default C<PERL_OPTIMIZE> to some psace-saving options 980C<PERL_LIBS> is C<-lm -lcrypt>, which should be good for most (but not
936suitable for newer gcc versions. For other compilers or older versions you 981all) systems.
982
983For other compilers or more customised optimisation settings, you need to
937need to adjust these, for example, in your F<~/.staticperlrc>. 984adjust these, e.g. in your F<~/.staticperlrc>.
985
986With gcc on x86 and amd64, you can get more space-savings by using:
987
988 -Os -ffunction-sections -fdata-sections -finline-limit=8 -mpush-args
989 -mno-inline-stringops-dynamically -mno-align-stringops
990
991And on x86 and pentium3 and newer (basically everything you might ever
992want to run on), adding these is even better for space-savings (use
993-mtune=core2 or something newer for much faster code, too):
994
995 -fomit-frame-pointer -march=pentium3 -mtune=i386
938 996
939=back 997=back
940 998
941=head4 Variables you probably I<do not want> to override 999=head4 Variables you probably I<do not want> to override
942 1000
1121 1179
1122=back 1180=back
1123 1181
1124=head1 RUNTIME FUNCTIONALITY 1182=head1 RUNTIME FUNCTIONALITY
1125 1183
1126Binaries created with C<mkbundle>/C<mkperl> contain extra functions, which 1184Binaries created with C<mkbundle>/C<mkperl> contain extra functionality,
1127are required to access the bundled perl sources, but might be useful for 1185mostly related to the extra files bundled in the binary (the virtual
1128other purposes. 1186filesystem). All of this data is statically compiled into the binary, and
1187accessing means copying it from a read-only section of your binary. Data
1188pages in this way are usually freed by the operating system, as they aren't
1189used more then once.
1190
1191=head2 VIRTUAL FILESYSTEM
1192
1193Every bundle has a virtual filesystem. The only information stored in it
1194is the path and contents of each file that was bundled.
1195
1196=head3 LAYOUT
1197
1198Any path starting with an ampersand (F<&>) or exclamation mark (F<!>) are
1199reserved by F<staticperl>. They must only be used as described in this
1200section.
1201
1202=over 4
1203
1204=item !
1205
1206All files that typically cannot be loaded from memory (such as dynamic
1207objects or shared libraries), but have to reside in the filesystem, are
1208prefixed with F<!>. Typically these files get written out to some
1209(semi-)temporary directory shortly after program startup, or before being
1210used.
1211
1212=item !boot
1213
1214The bootstrap file, if specified during bundling.
1215
1216=item !auto/
1217
1218Shared objects or dlls corresponding to dynamically-linked perl extensions
1219are stored with an F<!auto/> prefix.
1220
1221=item !lib/
1222
1223External shared libraries are stored in this directory.
1224
1225=item any letter
1226
1227Any path starting with a letter is a perl library file. For example,
1228F<Coro/AIO.pm> corresponds to the file loaded by C<use Coro::AIO>, and
1229F<Coro/jit.pl> corresponds to C<require "Coro/jit.pl">.
1230
1231Obviously, module names shouldn't start with any other characters than
1232letters :)
1233
1234=back
1235
1236=head3 FUNCTIONS
1237
1238=over 4
1239
1240=item $file = static::find $path
1241
1242Returns the data associated with the given C<$path>
1243(e.g. C<Digest/MD5.pm>, C<auto/POSIX/autosplit.ix>).
1244
1245Returns C<undef> if the file isn't embedded.
1246
1247=item @paths = static::list
1248
1249Returns the list of all paths embedded in this binary.
1250
1251=back
1252
1253=head2 EXTRA FEATURES
1129 1254
1130In addition, for the embedded loading of perl files to work, F<staticperl> 1255In addition, for the embedded loading of perl files to work, F<staticperl>
1131overrides the C<@INC> array. 1256overrides the C<@INC> array.
1132 1257
1133=over 4 1258=head1 FULLY STATIC BINARIES - ALPINE LINUX
1134 1259
1135=item $file = staticperl::find $path 1260This section once contained a way to build fully static (including
1261uClibc) binaries with buildroot. Unfortunately, buildroot no longer
1262supports a compiler, so I recommend using alpine linux instead
1263(L<http://alpinelinux.org/>). Get yourself a VM (e.g. with qemu), run an
1264older alpine linux verison in it (e.g. 2.4), copy staticperl inside and
1265use it.
1136 1266
1137Returns the data associated with the given C<$path> 1267The reason you might want an older alpine linux is that uClibc can be
1138(e.g. C<Digest/MD5.pm>, C<auto/POSIX/autosplit.ix>), which is basically 1268quite dependent on kernel versions, so the newest version of alpine linux
1139the UNIX path relative to the perl library directory. 1269might need a newer kernel then you might want for, if you plan to run your
1140 1270binaries on on other kernels.
1141Returns C<undef> if the file isn't embedded.
1142
1143=item @paths = staticperl::list
1144
1145Returns the list of all paths embedded in this binary.
1146
1147=back
1148
1149=head1 FULLY STATIC BINARIES - UCLIBC AND BUILDROOT
1150
1151To make truly static (Linux-) libraries, you might want to have a look at
1152buildroot (L<http://buildroot.uclibc.org/>).
1153
1154Buildroot is primarily meant to set up a cross-compile environment (which
1155is not so useful as perl doesn't quite like cross compiles), but it can also compile
1156a chroot environment where you can use F<staticperl>.
1157
1158To do so, download buildroot, and enable "Build options => development
1159files in target filesystem" and optionally "Build options => gcc
1160optimization level (optimize for size)". At the time of writing, I had
1161good experiences with GCC 4.4.x but not GCC 4.5.
1162
1163To minimise code size, I used C<-pipe -ffunction-sections -fdata-sections
1164-finline-limit=8 -fno-builtin-strlen -mtune=i386>. The C<-mtune=i386>
1165doesn't decrease codesize much, but it makes the file much more
1166compressible (and the execution a lot slower...).
1167
1168If you don't need Coro or threads, you can go with "linuxthreads.old" (or
1169no thread support). For Coro, it is highly recommended to switch to a
1170uClibc newer than 0.9.31 (at the time of this writing, I used the 20101201
1171snapshot) and enable NPTL, otherwise Coro needs to be configured with the
1172ultra-slow pthreads backend to work around linuxthreads bugs (it also uses
1173twice the address space needed for stacks).
1174
1175If you use C<linuxthreads.old>, then you should also be aware that
1176uClibc shares C<errno> between all threads when statically linking. See
1177L<http://lists.uclibc.org/pipermail/uclibc/2010-June/044157.html> for a
1178workaround (and L<https://bugs.uclibc.org/2089> for discussion).
1179
1180C<ccache> support is also recommended, especially if you want
1181to play around with buildroot options. Enabling the C<miniperl>
1182package will probably enable all options required for a successful
1183perl build. F<staticperl> itself additionally needs either C<wget>
1184(recommended, for CPAN) or C<curl>.
1185
1186As for shells, busybox should provide all that is needed, but the default
1187busybox configuration doesn't include F<comm> which is needed by perl -
1188either make a custom busybox config, or compile coreutils.
1189
1190For the latter route, you might find that bash has some bugs that keep
1191it from working properly in a chroot - either use dash (and link it to
1192F</bin/sh> inside the chroot) or link busybox to F</bin/sh>, using it's
1193built-in ash shell.
1194
1195Finally, you need F</dev/null> inside the chroot for many scripts to work
1196- either F<cp /dev/null output/target/dev> or bind-mounting your F</dev>
1197will provide this.
1198
1199After you have compiled and set up your buildroot target, you can copy
1200F<staticperl> from the C<App::Staticperl> distribution or from your
1201perl F<bin> directory (if you installed it) into the F<output/target>
1202filesystem, chroot inside and run it.
1203 1271
1204=head1 RECIPES / SPECIFIC MODULES 1272=head1 RECIPES / SPECIFIC MODULES
1205 1273
1206This section contains some common(?) recipes and information about 1274This section contains some common(?) recipes and information about
1207problems with some common modules or perl constructs that require extra 1275problems with some common modules or perl constructs that require extra
1269C<MAN3PODS> to be empty via the C<PERL_MM_OPT> environment variable. 1337C<MAN3PODS> to be empty via the C<PERL_MM_OPT> environment variable.
1270 1338
1271=item Gtk2 1339=item Gtk2
1272 1340
1273See Pango, same problems, same solution. 1341See Pango, same problems, same solution.
1342
1343=item Net::SSLeay
1344
1345This module hasn't been significantly updated since OpenSSL is called
1346OpenSSL, and fails to properly link against dependent libraries, most
1347commonly, it forgets to specify -ldl when linking.
1348
1349On GNU/Linux systems this usually goes undetected, as perl usually links
1350against -ldl itself and OpenSSL just happens to pick it up that way, by
1351chance.
1352
1353For static builds, you either have to configure -ldl manually, or you
1354cna use the following snippet in your C<postinstall> hook which patches
1355Net::SSLeay after installation, which happens to work most of the time:
1356
1357 postinstall() {
1358 # first install it
1359 instcpan Net::SSLeay
1360 # then add -ldl for future linking
1361 chmod u+w "$PERL_PREFIX"/lib/auto/Net/SSLeay/extralibs.ld
1362 echo " -ldl" >>"$PERL_PREFIX"/lib/auto/Net/SSLeay/extralibs.ld
1363 }
1274 1364
1275=item Pango 1365=item Pango
1276 1366
1277In addition to the C<MAN3PODS> problem in Glib, Pango also routes around 1367In addition to the C<MAN3PODS> problem in Glib, Pango also routes around
1278L<ExtUtils::MakeMaker> by compiling its files on its own. F<staticperl> 1368L<ExtUtils::MakeMaker> by compiling its files on its own. F<staticperl>
1346gains little. Why Socket exposes a C function that is in the core already 1436gains little. Why Socket exposes a C function that is in the core already
1347is anybody's guess. 1437is anybody's guess.
1348 1438
1349=back 1439=back
1350 1440
1441=head1 ADDITIONAL RESOURCES
1442
1443Some guy has made a repository on github
1444(L<https://github.com/gh0stwizard/staticperl-modules>) with some modules
1445patched to build with staticperl.
1446
1351=head1 AUTHOR 1447=head1 AUTHOR
1352 1448
1353 Marc Lehmann <schmorp@schmorp.de> 1449 Marc Lehmann <schmorp@schmorp.de>
1354 http://software.schmorp.de/pkg/staticperl.html 1450 http://software.schmorp.de/pkg/staticperl.html
1451

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines