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.61 by root, Fri Oct 16 02:43:37 2015 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
882=item C<STATICPERL> 901=item C<STATICPERL>
883 902
884The directory where staticperl stores all its files 903The directory where staticperl stores all its files
885(default: F<~/.staticperl>). 904(default: F<~/.staticperl>).
886 905
906=item C<DLCACHE>
907
908The path to a directory (will be created if it doesn't exist) where
909downloaded perl sources are being cached, to avoid downloading them
910again. The default is empty, which means there is no cache.
911
912=item C<PERL_VERSION>
913
914The perl version to install - C<5.12.5> is a good choice for small builds,
915but C<5.8.9> is also a good choice (5.8.9 is much smaller than 5.12.5), if
916it builds on your system.
917
918You can also set this variable to the absolute URL of a tarball (F<.tar>,
919F<.tar.gz>, F<.tar.bz2>, F<.tar.lzma> or F<.tar.xz>), or to the absolute
920path of an unpacked perl source tree, which will be copied.
921
922The default is currently
923F<http://stableperl.schmorp.de/dist/latest.tar.gz>, i.e. the latest
924stableperl release.
925
887=item C<PERL_MM_USE_DEFAULT>, C<EV_EXTRA_DEFS>, ... 926=item C<PERL_MM_USE_DEFAULT>, C<EV_EXTRA_DEFS>, ...
888 927
889Usually set to C<1> to make modules "less inquisitive" during their 928Usually set to C<1> to make modules "less inquisitive" during their
890installation, you can set any environment variable you want - some modules 929installation. You can set (and export!) any environment variable you want
891(such as L<Coro> or L<EV>) use environment variables for further tweaking. 930- some modules (such as L<Coro> or L<EV>) use environment variables for
892 931further 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 932
899=item C<PERL_PREFIX> 933=item C<PERL_PREFIX>
900 934
901The prefix where perl gets installed (default: F<$STATICPERL/perl>), 935The directory where perl gets installed (default: F<$STATICPERL/perl>),
902i.e. where the F<bin> and F<lib> subdirectories will end up. 936i.e. where the F<bin> and F<lib> subdirectories will end up. Previous
937contents will be removed on installation.
903 938
904=item C<PERL_CONFIGURE> 939=item C<PERL_CONFIGURE>
905 940
906Additional Configure options - these are simply passed to the perl 941Additional Configure options - these are simply passed to the perl
907Configure script. For example, if you wanted to enable dynamic loading, 942Configure 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 957the top of the F<staticperl> script for more info on these, and use a
923F<~/.staticperlrc> to override them. 958F<~/.staticperlrc> to override them.
924 959
925Most of the variables override (or modify) the corresponding F<Configure> 960Most of the variables override (or modify) the corresponding F<Configure>
926variable, except C<PERL_CCFLAGS>, which gets appended. 961variable, except C<PERL_CCFLAGS>, which gets appended.
962
963The default for C<PERL_OPTIMIZE> is C<-Os> (assuming gcc), and for
964C<PERL_LIBS> is C<-lm -lcrypt>, which should be good for most (but not
965all) systems.
966
967For other compilers or more customised optimisation settings, you need to
968adjust these, e.g. in your F<~/.staticperlrc>.
969
970With gcc on x86 and amd64, you can get more space-savings by using:
971
972 -Os -ffunction-sections -fdata-sections -finline-limit=8 -mpush-args
973 -mno-inline-stringops-dynamically -mno-align-stringops
974
975And on x86 and pentium3 and newer (basically everything you might ever
976want to run on), adding these is even better for space-savings (use
977-mtune=core2 or something newer for much faster code, too):
978
979 -fomit-frame-pointer -march=pentium3 -mtune=i386
927 980
928=back 981=back
929 982
930=head4 Variables you probably I<do not want> to override 983=head4 Variables you probably I<do not want> to override
931 984
1110 1163
1111=back 1164=back
1112 1165
1113=head1 RUNTIME FUNCTIONALITY 1166=head1 RUNTIME FUNCTIONALITY
1114 1167
1115Binaries created with C<mkbundle>/C<mkperl> contain extra functions, which 1168Binaries created with C<mkbundle>/C<mkperl> contain extra functionality,
1116are required to access the bundled perl sources, but might be useful for 1169mostly related to the extra files bundled in the binary (the virtual
1117other purposes. 1170filesystem). All of this data is statically compiled into the binary, and
1171accessing means copying it from a read-only section of your binary. Data
1172pages in this way is usually freed by the operating system, as it isn't
1173use more the onace.
1174
1175=head2 VIRTUAL FILESYSTEM
1176
1177Every bundle has a virtual filesystem. The only information stored in it
1178is the path and contents of each file that was bundled.
1179
1180=head3 LAYOUT
1181
1182Any path starting with an ampersand (F<&>) or exclamation mark (F<!>) are
1183reserved by F<staticperl>. They must only be used as described in this
1184section.
1185
1186=over 4
1187
1188=item !
1189
1190All files that typically cannot be loaded from memory (such as dynamic
1191objects or shared libraries), but have to reside in the filesystem, are
1192prefixed with F<!>. Typically these files get written out to some
1193(semi-)temporary directory shortly after program startup, or before being
1194used.
1195
1196=item !boot
1197
1198The bootstrap file, if specified during bundling.
1199
1200=item !auto/
1201
1202Shared objects or dlls corresponding to dynamically-linked perl extensions
1203are stored with an F<!auto/> prefix.
1204
1205=item !lib/
1206
1207External shared libraries are stored in this directory.
1208
1209=item any letter
1210
1211Any path starting with a letter is a perl library file. For example,
1212F<Coro/AIO.pm> corresponds to the file loaded by C<use Coro::AIO>, and
1213F<Coro/jit.pl> corresponds to C<require "Coro/jit.pl">.
1214
1215Obviously, module names shouldn't start with any other characters than
1216letters :)
1217
1218=back
1219
1220=head3 FUNCTIONS
1221
1222=over 4
1223
1224=item $file = static::find $path
1225
1226Returns the data associated with the given C<$path>
1227(e.g. C<Digest/MD5.pm>, C<auto/POSIX/autosplit.ix>).
1228
1229Returns C<undef> if the file isn't embedded.
1230
1231=item @paths = static::list
1232
1233Returns the list of all paths embedded in this binary.
1234
1235=back
1236
1237=head2 EXTRA FEATURES
1118 1238
1119In addition, for the embedded loading of perl files to work, F<staticperl> 1239In addition, for the embedded loading of perl files to work, F<staticperl>
1120overrides the C<@INC> array. 1240overrides the C<@INC> array.
1121 1241
1122=over 4 1242=head1 FULLY STATIC BINARIES - ALPINE LINUX
1123 1243
1124=item $file = staticperl::find $path 1244This section once contained a way to build fully static (including
1245uClibc) binaries with buildroot. Unfortunately, buildroot no longer
1246supports a compiler, so I recommend using alpine linux instead
1247(L<http://alpinelinux.org/>). Get yourself a VM (e.g. with qemu), run an
1248older alpine linux verison in it (e.g. 2.4), copy staticperl inside and
1249use it.
1125 1250
1126Returns the data associated with the given C<$path> 1251The 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 1252quite dependent on kernel versions, so the newest version of alpine linux
1128the UNIX path relative to the perl library directory. 1253might need a newer kernel then you might want for, if you plan to run your
1129 1254binaries 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 1255
1193=head1 RECIPES / SPECIFIC MODULES 1256=head1 RECIPES / SPECIFIC MODULES
1194 1257
1195This section contains some common(?) recipes and information about 1258This section contains some common(?) recipes and information about
1196problems with some common modules or perl constructs that require extra 1259problems with some common modules or perl constructs that require extra
1258C<MAN3PODS> to be empty via the C<PERL_MM_OPT> environment variable. 1321C<MAN3PODS> to be empty via the C<PERL_MM_OPT> environment variable.
1259 1322
1260=item Gtk2 1323=item Gtk2
1261 1324
1262See Pango, same problems, same solution. 1325See Pango, same problems, same solution.
1326
1327=item Net::SSLeay
1328
1329This module hasn't been significantly updated since OpenSSL is called
1330OpenSSL, and fails to properly link against dependent libraries, most
1331commonly, it forgets to specify -ldl when linking.
1332
1333On GNU/Linux systems this usually goes undetected, as perl usually links
1334against -ldl itself and OpenSSL just happens to pick it up that way, by
1335chance.
1336
1337For static builds, you either have to configure -ldl manually, or you
1338cna use the following snippet in your C<postinstall> hook which patches
1339Net::SSLeay after installation, which happens to work most of the time:
1340
1341 postinstall() {
1342 # first install it
1343 instcpan Net::SSLeay
1344 # then add -ldl for future linking
1345 chmod u+w "$PERL_PREFIX"/lib/auto/Net/SSLeay/extralibs.ld
1346 echo " -ldl" >>"$PERL_PREFIX"/lib/auto/Net/SSLeay/extralibs.ld
1347 }
1263 1348
1264=item Pango 1349=item Pango
1265 1350
1266In addition to the C<MAN3PODS> problem in Glib, Pango also routes around 1351In addition to the C<MAN3PODS> problem in Glib, Pango also routes around
1267L<ExtUtils::MakeMaker> by compiling its files on its own. F<staticperl> 1352L<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 1420gains little. Why Socket exposes a C function that is in the core already
1336is anybody's guess. 1421is anybody's guess.
1337 1422
1338=back 1423=back
1339 1424
1425=head1 ADDITIONAL RESOURCES
1426
1427Some guy has made a repository on github
1428(L<https://github.com/gh0stwizard/staticperl-modules>) with some modules
1429patched to build with staticperl.
1430
1340=head1 AUTHOR 1431=head1 AUTHOR
1341 1432
1342 Marc Lehmann <schmorp@schmorp.de> 1433 Marc Lehmann <schmorp@schmorp.de>
1343 http://software.schmorp.de/pkg/staticperl.html 1434 http://software.schmorp.de/pkg/staticperl.html
1435

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines