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

Comparing App-Staticperl/staticperl.pod (file contents):
Revision 1.49 by root, Wed Jul 13 15:23:13 2011 UTC vs.
Revision 1.64 by root, Thu Mar 21 16:41:36 2019 UTC

…		…
1	=head1 NAME	1	=head1 NAME
2		2
3	staticperl - perl, libc, 100 modules, all in one 500kb file	3	staticperl - 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
…		…
348	add eg/httpd httpd.pm	348	add eg/httpd httpd.pm
349		349
350	All options that specify modules or files to be added are processed in the	350	All options that specify modules or files to be added are processed in the
351	order given on the command line.	351	order given on the command line.
352		352
353	=head3 BUNDLE CREATION WORKFLOW / STATICPELR MKBUNDLE OPTIONS	353	=head3 BUNDLE CREATION WORKFLOW / STATICPERL MKBUNDLE OPTIONS
354		354
355	F<staticperl mkbundle> works by first assembling a list of candidate	355	F<staticperl mkbundle> works by first assembling a list of candidate
356	files and modules to include, then filtering them by include/exclude	356	files and modules to include, then filtering them by include/exclude
357	patterns. The remaining modules (together with their direct dependencies,	357	patterns. The remaining modules (together with their direct dependencies,
358	such as link libraries and L<AutoLoader> files) are then converted into	358	such as link libraries and L<AutoLoader> files) are then converted into
…		…
543	# then later, in perl, use	543	# then later, in perl, use
544	use myfiles::file1;	544	use myfiles::file1;
545	require myfiles::file2;	545	require myfiles::file2;
546	my $res = do "myfiles/file3.pl";	546	my $res = do "myfiles/file3.pl";
547		547
548	=item C<--binadd> F<file> \| C<--add> "F<file> alias"	548	=item C<--addbin> F<file> \| C<--addbin> "F<file> alias"
549		549
550	Just like C<--add>, except that it treats the file as binary and adds it	550	Just like C<--add>, except that it treats the file as binary and adds it
551	without any postprocessing (perl files might get stripped to reduce their	551	without any postprocessing (perl files might get stripped to reduce their
552	size).	552	size).
553		553
…		…
752	standalone applications, and this option removes those known to cause	752	standalone applications, and this option removes those known to cause
753	trouble.	753	trouble.
754		754
755	Specifically, these are removed:	755	Specifically, these are removed:
756		756
757	C<PERL_HASH_SEED_DEBUG> and C<PERL_DEBUG_MSTATS> can cause underaible	757	C<PERL_HASH_SEED_DEBUG> and C<PERL_DEBUG_MSTATS> can cause undesirable
758	output, C<PERL5OPT>, C<PERL_DESTRUCT_LEVEL>, C<PERL_HASH_SEED> and	758	output, C<PERL5OPT>, C<PERL_DESTRUCT_LEVEL>, C<PERL_HASH_SEED> and
759	C<PERL_SIGNALS> can alter execution significantly, and C<PERL_UNICODE>,	759	C<PERL_SIGNALS> can alter execution significantly, and C<PERL_UNICODE>,
760	C<PERLIO_DEBUG> and C<PERLIO> can affect input and output.	760	C<PERLIO_DEBUG> and C<PERLIO> can affect input and output.
761		761
762	The variables C<PERL_LIB> and C<PERL5_LIB> are always ignored because the	762	The variables C<PERL_LIB> and C<PERL5_LIB> are always ignored because the
…		…
800	staticperl mkperl -MIO::AIO --staticlib crypt	800	staticperl mkperl -MIO::AIO --staticlib crypt
801		801
802	# ldopts might now contain:	802	# ldopts might now contain:
803	# -lm -Wl,-Bstatic -lcrypt -Wl,-Bdynamic -lpthread	803	# -lm -Wl,-Bstatic -lcrypt -Wl,-Bdynamic -lpthread
804		804
		805	=item C<--extra-cflags> string
		806
		807	Specifies extra compiler flags, used when compiling the bundle file. The
		808	flags are appended to all the existing flags, so can be sued to override
		809	settings.
		810
		811	=item C<--extra-ldflags> string
		812
		813	Specifies extra linker flags, used when linking the bundle.
		814
		815	=item C<--extra-libs> string
		816
		817	Extra linker flags, appended at the end when linking. The difference to
		818	C<--extra-ldflags> is that the ldflags are appended to the flags, before
		819	the objects and libraries, and the extra libs are added at the end.
		820
805	=back	821	=back
806		822
807	=back	823	=back
808		824
809	=head3 EXTENDED GLOB PATTERNS	825	=head3 EXTENDED GLOB PATTERNS
…		…
909	downloaded perl sources are being cached, to avoid downloading them	925	downloaded perl sources are being cached, to avoid downloading them
910	again. The default is empty, which means there is no cache.	926	again. The default is empty, which means there is no cache.
911		927
912	=item C<PERL_VERSION>	928	=item C<PERL_VERSION>
913		929
914	The perl version to install - default is currently C<5.12.3>, but C<5.8.9>	930	The perl version to install - C<5.12.5> is a good choice for small builds,
915	is also a good choice (5.8.9 is much smaller than 5.12.3, while 5.10.1 is	931	but C<5.8.9> is also a good choice (5.8.9 is much smaller than 5.12.5), if
916	about as big as 5.12.3).	932	it builds on your system.
		933
		934	You can also set this variable to the absolute URL of a tarball (F<.tar>,
		935	F<.tar.gz>, F<.tar.bz2>, F<.tar.lzma> or F<.tar.xz>), or to the absolute
		936	path of an unpacked perl source tree, which will be copied.
		937
		938	The default is currently
		939	F<http://stableperl.schmorp.de/dist/latest.tar.gz>, i.e. the latest
		940	stableperl release.
917		941
918	=item C<PERL_MM_USE_DEFAULT>, C<EV_EXTRA_DEFS>, ...	942	=item C<PERL_MM_USE_DEFAULT>, C<EV_EXTRA_DEFS>, ...
919		943
920	Usually set to C<1> to make modules "less inquisitive" during their	944	Usually set to C<1> to make modules "less inquisitive" during their
921	installation. You can set (and export!) any environment variable you want	945	installation. You can set (and export!) any environment variable you want
922	- some modules (such as L<Coro> or L<EV>) use environment variables for	946	- some modules (such as L<Coro> or L<EV>) use environment variables for
923	further tweaking.	947	further tweaking.
924		948
925	=item C<PERL_PREFIX>	949	=item C<PERL_PREFIX>
926		950
927	The prefix where perl gets installed (default: F<$STATICPERL/perl>),	951	The directory where perl gets installed (default: F<$STATICPERL/perl>),
928	i.e. where the F<bin> and F<lib> subdirectories will end up.	952	i.e. where the F<bin> and F<lib> subdirectories will end up. Previous
		953	contents will be removed on installation.
929		954
930	=item C<PERL_CONFIGURE>	955	=item C<PERL_CONFIGURE>
931		956
932	Additional Configure options - these are simply passed to the perl	957	Additional Configure options - these are simply passed to the perl
933	Configure script. For example, if you wanted to enable dynamic loading,	958	Configure script. For example, if you wanted to enable dynamic loading,
…		…
949	F<~/.staticperlrc> to override them.	974	F<~/.staticperlrc> to override them.
950		975
951	Most of the variables override (or modify) the corresponding F<Configure>	976	Most of the variables override (or modify) the corresponding F<Configure>
952	variable, except C<PERL_CCFLAGS>, which gets appended.	977	variable, except C<PERL_CCFLAGS>, which gets appended.
953		978
954	You should have a look near the beginning of the F<staticperl> script -	979	The default for C<PERL_OPTIMIZE> is C<-Os> (assuming gcc), and for
955	staticperl tries to default C<PERL_OPTIMIZE> to some psace-saving options	980	C<PERL_LIBS> is C<-lm -lcrypt>, which should be good for most (but not
956	suitable for newer gcc versions. For other compilers or older versions you	981	all) systems.
		982
		983	For other compilers or more customised optimisation settings, you need to
957	need to adjust these, for example, in your F<~/.staticperlrc>.	984	adjust these, e.g. in your F<~/.staticperlrc>.
		985
		986	With 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
		991	And on x86 and pentium3 and newer (basically everything you might ever
		992	want 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
958		996
959	=back	997	=back
960		998
961	=head4 Variables you probably I<do not want> to override	999	=head4 Variables you probably I<do not want> to override
962		1000
…		…
1145		1183
1146	Binaries created with C<mkbundle>/C<mkperl> contain extra functionality,	1184	Binaries created with C<mkbundle>/C<mkperl> contain extra functionality,
1147	mostly related to the extra files bundled in the binary (the virtual	1185	mostly related to the extra files bundled in the binary (the virtual
1148	filesystem). All of this data is statically compiled into the binary, and	1186	filesystem). All of this data is statically compiled into the binary, and
1149	accessing means copying it from a read-only section of your binary. Data	1187	accessing means copying it from a read-only section of your binary. Data
1150	pages in this way is usually freed by the operating system, as it isn't	1188	pages in this way are usually freed by the operating system, as they aren't
1151	use more the onace.	1189	used more then once.
1152		1190
1153	=head2 VIRTUAL FILESYSTEM	1191	=head2 VIRTUAL FILESYSTEM
1154		1192
1155	Every bundle has a virtual filesystem. The only information stored in it	1193	Every bundle has a virtual filesystem. The only information stored in it
1156	is the path and contents of each file that was bundled.	1194	is the path and contents of each file that was bundled.
1157		1195
1158	=head3 LAYOUT	1196	=head3 LAYOUT
1159		1197
1160	Any path starting with an ampersand (F<&>) or exclamation mark (F<!>) are	1198	Any paths starting with an ampersand (F<&>) or exclamation mark (F<!>) are
1161	reserved by F<staticperl>. They must only be used as described in this	1199	reserved by F<staticperl>. They must only be used as described in this
1162	section.	1200	section.
1163		1201
1164	=over 4	1202	=over 4
1165		1203
…		…
1215	=head2 EXTRA FEATURES	1253	=head2 EXTRA FEATURES
1216		1254
1217	In addition, for the embedded loading of perl files to work, F<staticperl>	1255	In addition, for the embedded loading of perl files to work, F<staticperl>
1218	overrides the C<@INC> array.	1256	overrides the C<@INC> array.
1219		1257
1220	=head1 FULLY STATIC BINARIES - UCLIBC AND BUILDROOT	1258	=head1 FULLY STATIC BINARIES - ALPINE LINUX
1221		1259
1222	To make truly static (Linux-) libraries, you might want to have a look at	1260	This section once contained a way to build fully static (including
1223	buildroot (L<http://buildroot.uclibc.org/>).	1261	uClibc) binaries with buildroot. Unfortunately, buildroot no longer
		1262	supports a compiler, so I recommend using alpine linux instead
		1263	(L<http://alpinelinux.org/>). Get yourself a VM (e.g. with qemu), run an
		1264	older alpine linux verison in it (e.g. 2.4), copy staticperl inside and
		1265	use it.
1224		1266
1225	Buildroot is primarily meant to set up a cross-compile environment (which	1267	The reason you might want an older alpine linux is that uClibc can be
1226	is not so useful as perl doesn't quite like cross compiles), but it can also compile	1268	quite dependent on kernel versions, so the newest version of alpine linux
1227	a chroot environment where you can use F<staticperl>.	1269	might need a newer kernel then you might want for, if you plan to run your
1228		1270	binaries on on other kernels.
1229	To do so, download buildroot, and enable "Build options => development
1230	files in target filesystem" and optionally "Build options => gcc
1231	optimization level (optimize for size)". At the time of writing, I had
1232	good experiences with GCC 4.4.x but not GCC 4.5.
1233
1234	To minimise code size, I used C<-pipe -ffunction-sections -fdata-sections
1235	-finline-limit=8 -fno-builtin-strlen -mtune=i386>. The C<-mtune=i386>
1236	doesn't decrease codesize much, but it makes the file much more
1237	compressible (and the execution a lot slower...).
1238
1239	If you don't need Coro or threads, you can go with "linuxthreads.old" (or
1240	no thread support). For Coro, it is highly recommended to switch to a
1241	uClibc newer than 0.9.31 (at the time of this writing, I used the 20101201
1242	snapshot) and enable NPTL, otherwise Coro needs to be configured with the
1243	ultra-slow pthreads backend to work around linuxthreads bugs (it also uses
1244	twice the address space needed for stacks).
1245
1246	If you use C<linuxthreads.old>, then you should also be aware that
1247	uClibc shares C<errno> between all threads when statically linking. See
1248	L<http://lists.uclibc.org/pipermail/uclibc/2010-June/044157.html> for a
1249	workaround (and L<https://bugs.uclibc.org/2089> for discussion).
1250
1251	C<ccache> support is also recommended, especially if you want
1252	to play around with buildroot options. Enabling the C<miniperl>
1253	package will probably enable all options required for a successful
1254	perl build. F<staticperl> itself additionally needs either C<wget>
1255	(recommended, for CPAN) or C<curl>.
1256
1257	As for shells, busybox should provide all that is needed, but the default
1258	busybox configuration doesn't include F<comm> which is needed by perl -
1259	either make a custom busybox config, or compile coreutils.
1260
1261	For the latter route, you might find that bash has some bugs that keep
1262	it from working properly in a chroot - either use dash (and link it to
1263	F</bin/sh> inside the chroot) or link busybox to F</bin/sh>, using it's
1264	built-in ash shell.
1265
1266	Finally, you need F</dev/null> inside the chroot for many scripts to work
1267	- either F<cp /dev/null output/target/dev> or bind-mounting your F</dev>
1268	will provide this.
1269
1270	After you have compiled and set up your buildroot target, you can copy
1271	F<staticperl> from the C<App::Staticperl> distribution or from your
1272	perl F<bin> directory (if you installed it) into the F<output/target>
1273	filesystem, chroot inside and run it.
1274		1271
1275	=head1 RECIPES / SPECIFIC MODULES	1272	=head1 RECIPES / SPECIFIC MODULES
1276		1273
1277	This section contains some common(?) recipes and information about	1274	This section contains some common(?) recipes and information about
1278	problems with some common modules or perl constructs that require extra	1275	problems with some common modules or perl constructs that require extra
…		…
1292		1289
1293	Many Unicode properties in turn are defined in separate modules,	1290	Many Unicode properties in turn are defined in separate modules,
1294	such as C<"unicore/Heavy.pl"> and more specific data tables such as	1291	such as C<"unicore/Heavy.pl"> and more specific data tables such as
1295	C<"unicore/To/Digit.pl"> or C<"unicore/lib/Perl/Word.pl">. These tables	1292	C<"unicore/To/Digit.pl"> or C<"unicore/lib/Perl/Word.pl">. These tables
1296	are big (7MB uncompressed, although F<staticperl> contains special	1293	are big (7MB uncompressed, although F<staticperl> contains special
1297	handling for those files), so including them on demand by your application	1294	handling for those files), so including them only on demand in your
1298	only might pay off.	1295	application might pay off.
1299		1296
1300	To simply include the whole unicode database, use:	1297	To simply include the whole unicode database, use:
1301		1298
1302	--incglob '/unicore/**.pl'	1299	--incglob '/unicore/**.pl'
1303		1300
…		…
1340	C<MAN3PODS> to be empty via the C<PERL_MM_OPT> environment variable.	1337	C<MAN3PODS> to be empty via the C<PERL_MM_OPT> environment variable.
1341		1338
1342	=item Gtk2	1339	=item Gtk2
1343		1340
1344	See Pango, same problems, same solution.	1341	See Pango, same problems, same solution.
		1342
		1343	=item Net::SSLeay
		1344
		1345	This module hasn't been significantly updated since OpenSSL is called
		1346	OpenSSL, and fails to properly link against dependent libraries, most
		1347	commonly, it forgets to specify -ldl when linking.
		1348
		1349	On GNU/Linux systems this usually goes undetected, as perl usually links
		1350	against -ldl itself and OpenSSL just happens to pick it up that way, by
		1351	chance.
		1352
		1353	For static builds, you either have to configure -ldl manually, or you
		1354	cna use the following snippet in your C<postinstall> hook which patches
		1355	Net::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	}
1345		1364
1346	=item Pango	1365	=item Pango
1347		1366
1348	In addition to the C<MAN3PODS> problem in Glib, Pango also routes around	1367	In addition to the C<MAN3PODS> problem in Glib, Pango also routes around
1349	L<ExtUtils::MakeMaker> by compiling its files on its own. F<staticperl>	1368	L<ExtUtils::MakeMaker> by compiling its files on its own. F<staticperl>
…		…
1417	gains little. Why Socket exposes a C function that is in the core already	1436	gains little. Why Socket exposes a C function that is in the core already
1418	is anybody's guess.	1437	is anybody's guess.
1419		1438
1420	=back	1439	=back
1421		1440
		1441	=head1 ADDITIONAL RESOURCES
		1442
		1443	Some guy has made a repository on github
		1444	(L<https://github.com/gh0stwizard/staticperl-modules>) with some modules
		1445	patched to build with staticperl.
		1446
1422	=head1 AUTHOR	1447	=head1 AUTHOR
1423		1448
1424	Marc Lehmann <schmorp@schmorp.de>	1449	Marc Lehmann <schmorp@schmorp.de>
1425	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

Comparing App-Staticperl/staticperl.pod (file contents): Revision 1.49 by root, Wed Jul 13 15:23:13 2011 UTC vs. Revision 1.64 by root, Thu Mar 21 16:41:36 2019 UTC

Diff Legend

Comparing App-Staticperl/staticperl.pod (file contents):
Revision 1.49 by root, Wed Jul 13 15:23:13 2011 UTC vs.
Revision 1.64 by root, Thu Mar 21 16:41:36 2019 UTC