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.39 by root, Sat Apr 2 11:00:34 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
39file that contains perl interpreter, libc, all the modules you need, all 39file that contains perl interpreter, libc, all the modules you need, all
40the libraries you need and of course your actual program. 40the libraries you need and of course your actual program.
41 41
42With F<uClibc> and F<upx> on x86, you can create a single 500kb binary 42With F<uClibc> and F<upx> on x86, you can create a single 500kb binary
43that contains perl and 100 modules such as POSIX, AnyEvent, EV, IO::AIO, 43that contains perl and 100 modules such as POSIX, AnyEvent, EV, IO::AIO,
44Coro and so on. Or any other choice of modules. 44Coro and so on. Or any other choice of modules (and some other size :).
45 45
46To see how this turns out, you can try out smallperl and bigperl, two 46To see how this turns out, you can try out smallperl and bigperl, two
47pre-built static and compressed perl binaries with many and even more 47pre-built static and compressed perl binaries with many and even more
48modules: just follow the links at L<http://staticperl.schmorp.de/>. 48modules: just follow the links at L<http://staticperl.schmorp.de/>.
49 49
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
882=item C<STATICPERL> 917=item C<STATICPERL>
883 918
884The directory where staticperl stores all its files 919The directory where staticperl stores all its files
885(default: F<~/.staticperl>). 920(default: F<~/.staticperl>).
886 921
922=item C<DLCACHE>
923
924The path to a directory (will be created if it doesn't exist) where
925downloaded perl sources are being cached, to avoid downloading them
926again. The default is empty, which means there is no cache.
927
928=item C<PERL_VERSION>
929
930The perl version to install - C<5.12.5> is a good choice for small builds,
931but C<5.8.9> is also a good choice (5.8.9 is much smaller than 5.12.5), if
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.
941
887=item C<PERL_MM_USE_DEFAULT>, C<EV_EXTRA_DEFS>, ... 942=item C<PERL_MM_USE_DEFAULT>, C<EV_EXTRA_DEFS>, ...
888 943
889Usually set to C<1> to make modules "less inquisitive" during their 944Usually set to C<1> to make modules "less inquisitive" during their
890installation, you can set any environment variable you want - some modules 945installation. You can set (and export!) any environment variable you want
891(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
892 947further tweaking.
893=item C<PERL_VERSION>
894
895The perl version to install - default is currently C<5.12.3>, but C<5.8.9>
896is also a good choice (5.8.9 is much smaller than 5.12.3, while 5.10.1 is
897about as big as 5.12.3).
898 948
899=item C<PERL_PREFIX> 949=item C<PERL_PREFIX>
900 950
901The prefix where perl gets installed (default: F<$STATICPERL/perl>), 951The directory where perl gets installed (default: F<$STATICPERL/perl>),
902i.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.
903 954
904=item C<PERL_CONFIGURE> 955=item C<PERL_CONFIGURE>
905 956
906Additional Configure options - these are simply passed to the perl 957Additional Configure options - these are simply passed to the perl
907Configure script. For example, if you wanted to enable dynamic loading, 958Configure script. For example, if you wanted to enable dynamic loading,
922the top of the F<staticperl> script for more info on these, and use a 973the top of the F<staticperl> script for more info on these, and use a
923F<~/.staticperlrc> to override them. 974F<~/.staticperlrc> to override them.
924 975
925Most of the variables override (or modify) the corresponding F<Configure> 976Most of the variables override (or modify) the corresponding F<Configure>
926variable, except C<PERL_CCFLAGS>, which gets appended. 977variable, except C<PERL_CCFLAGS>, which gets appended.
978
979The default for C<PERL_OPTIMIZE> is C<-Os> (assuming gcc), and for
980C<PERL_LIBS> is C<-lm -lcrypt>, which should be good for most (but not
981all) systems.
982
983For other compilers or more customised optimisation settings, you need to
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
927 996
928=back 997=back
929 998
930=head4 Variables you probably I<do not want> to override 999=head4 Variables you probably I<do not want> to override
931 1000
1110 1179
1111=back 1180=back
1112 1181
1113=head1 RUNTIME FUNCTIONALITY 1182=head1 RUNTIME FUNCTIONALITY
1114 1183
1115Binaries created with C<mkbundle>/C<mkperl> contain extra functions, which 1184Binaries created with C<mkbundle>/C<mkperl> contain extra functionality,
1116are required to access the bundled perl sources, but might be useful for 1185mostly related to the extra files bundled in the binary (the virtual
1117other 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
1118 1254
1119In 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>
1120overrides the C<@INC> array. 1256overrides the C<@INC> array.
1121 1257
1122=over 4 1258=head1 FULLY STATIC BINARIES - ALPINE LINUX
1123 1259
1124=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.
1125 1266
1126Returns the data associated with the given C<$path> 1267The reason you might want an older alpine linux is that uClibc can be
1127(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
1128the UNIX path relative to the perl library directory. 1269might need a newer kernel then you might want for, if you plan to run your
1129 1270binaries on on other kernels.
1130Returns C<undef> if the file isn't embedded.
1131
1132=item @paths = staticperl::list
1133
1134Returns the list of all paths embedded in this binary.
1135
1136=back
1137
1138=head1 FULLY STATIC BINARIES - UCLIBC AND BUILDROOT
1139
1140To make truly static (Linux-) libraries, you might want to have a look at
1141buildroot (L<http://buildroot.uclibc.org/>).
1142
1143Buildroot is primarily meant to set up a cross-compile environment (which
1144is not so useful as perl doesn't quite like cross compiles), but it can also compile
1145a chroot environment where you can use F<staticperl>.
1146
1147To do so, download buildroot, and enable "Build options => development
1148files in target filesystem" and optionally "Build options => gcc
1149optimization level (optimize for size)". At the time of writing, I had
1150good experiences with GCC 4.4.x but not GCC 4.5.
1151
1152To minimise code size, I used C<-pipe -ffunction-sections -fdata-sections
1153-finline-limit=8 -fno-builtin-strlen -mtune=i386>. The C<-mtune=i386>
1154doesn't decrease codesize much, but it makes the file much more
1155compressible.
1156
1157If you don't need Coro or threads, you can go with "linuxthreads.old" (or
1158no thread support). For Coro, it is highly recommended to switch to a
1159uClibc newer than 0.9.31 (at the time of this writing, I used the 20101201
1160snapshot) and enable NPTL, otherwise Coro needs to be configured with the
1161ultra-slow pthreads backend to work around linuxthreads bugs (it also uses
1162twice the address space needed for stacks).
1163
1164If you use C<linuxthreads.old>, then you should also be aware that
1165uClibc shares C<errno> between all threads when statically linking. See
1166L<http://lists.uclibc.org/pipermail/uclibc/2010-June/044157.html> for a
1167workaround (And L<https://bugs.uclibc.org/2089> for discussion).
1168
1169C<ccache> support is also recommended, especially if you want
1170to play around with buildroot options. Enabling the C<miniperl>
1171package will probably enable all options required for a successful
1172perl build. F<staticperl> itself additionally needs either C<wget>
1173(recommended, for CPAN) or C<curl>.
1174
1175As for shells, busybox should provide all that is needed, but the default
1176busybox configuration doesn't include F<comm> which is needed by perl -
1177either make a custom busybox config, or compile coreutils.
1178
1179For the latter route, you might find that bash has some bugs that keep
1180it from working properly in a chroot - either use dash (and link it to
1181F</bin/sh> inside the chroot) or link busybox to F</bin/sh>, using it's
1182built-in ash shell.
1183
1184Finally, you need F</dev/null> inside the chroot for many scripts to work
1185- F<cp /dev/null output/target/dev> or bind-mounting your F</dev> will
1186both provide this.
1187
1188After you have compiled and set up your buildroot target, you can copy
1189F<staticperl> from the C<App::Staticperl> distribution or from your
1190perl f<bin> directory (if you installed it) into the F<output/target>
1191filesystem, chroot inside and run it.
1192 1271
1193=head1 RECIPES / SPECIFIC MODULES 1272=head1 RECIPES / SPECIFIC MODULES
1194 1273
1195This section contains some common(?) recipes and information about 1274This section contains some common(?) recipes and information about
1196problems with some common modules or perl constructs that require extra 1275problems with some common modules or perl constructs that require extra
1258C<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.
1259 1338
1260=item Gtk2 1339=item Gtk2
1261 1340
1262See 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 }
1263 1364
1264=item Pango 1365=item Pango
1265 1366
1266In 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
1267L<ExtUtils::MakeMaker> by compiling its files on its own. F<staticperl> 1368L<ExtUtils::MakeMaker> by compiling its files on its own. F<staticperl>
1335gains 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
1336is anybody's guess. 1437is anybody's guess.
1337 1438
1338=back 1439=back
1339 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
1340=head1 AUTHOR 1447=head1 AUTHOR
1341 1448
1342 Marc Lehmann <schmorp@schmorp.de> 1449 Marc Lehmann <schmorp@schmorp.de>
1343 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