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

Comparing App-Staticperl/staticperl.pod (file contents):
Revision 1.53 by root, Wed Jan 11 19:20:57 2012 UTC vs.
Revision 1.63 by root, Tue Mar 19 15:24:49 2019 UTC

…		…
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
…		…
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,
…		…
1158		1183
1159	Binaries created with C<mkbundle>/C<mkperl> contain extra functionality,	1184	Binaries created with C<mkbundle>/C<mkperl> contain extra functionality,
1160	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
1161	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
1162	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
1163	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
1164	use more the onace.	1189	used more then once.
1165		1190
1166	=head2 VIRTUAL FILESYSTEM	1191	=head2 VIRTUAL FILESYSTEM
1167		1192
1168	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
1169	is the path and contents of each file that was bundled.	1194	is the path and contents of each file that was bundled.
…		…
1228	=head2 EXTRA FEATURES	1253	=head2 EXTRA FEATURES
1229		1254
1230	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>
1231	overrides the C<@INC> array.	1256	overrides the C<@INC> array.
1232		1257
1233	=head1 FULLY STATIC BINARIES - UCLIBC AND BUILDROOT	1258	=head1 FULLY STATIC BINARIES - ALPINE LINUX
1234		1259
1235	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
1236	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.
1237		1266
1238	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
1239	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
1240	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
1241		1270	binaries on on other kernels.
1242	To do so, download buildroot, and enable "Build options => development
1243	files in target filesystem" and optionally "Build options => gcc
1244	optimization level (optimize for size)". At the time of writing, I had
1245	good experiences with GCC 4.4.x but not GCC 4.5.
1246
1247	To minimise code size, I used C<-pipe -ffunction-sections -fdata-sections
1248	-finline-limit=8 -fno-builtin-strlen -mtune=i386>. The C<-mtune=i386>
1249	doesn't decrease codesize much, but it makes the file much more
1250	compressible (and the execution a lot slower...).
1251
1252	If you don't need Coro or threads, you can go with "linuxthreads.old" (or
1253	no thread support). For Coro, it is highly recommended to switch to a
1254	uClibc newer than 0.9.31 (at the time of this writing, I used the 20101201
1255	snapshot) and enable NPTL, otherwise Coro needs to be configured with the
1256	ultra-slow pthreads backend to work around linuxthreads bugs (it also uses
1257	twice the address space needed for stacks).
1258
1259	If you use C<linuxthreads.old>, then you should also be aware that
1260	uClibc shares C<errno> between all threads when statically linking. See
1261	L<http://lists.uclibc.org/pipermail/uclibc/2010-June/044157.html> for a
1262	workaround (and L<https://bugs.uclibc.org/2089> for discussion).
1263
1264	C<ccache> support is also recommended, especially if you want
1265	to play around with buildroot options. Enabling the C<miniperl>
1266	package will probably enable all options required for a successful
1267	perl build. F<staticperl> itself additionally needs either C<wget>
1268	(recommended, for CPAN) or C<curl>.
1269
1270	As for shells, busybox should provide all that is needed, but the default
1271	busybox configuration doesn't include F<comm> which is needed by perl -
1272	either make a custom busybox config, or compile coreutils.
1273
1274	For the latter route, you might find that bash has some bugs that keep
1275	it from working properly in a chroot - either use dash (and link it to
1276	F</bin/sh> inside the chroot) or link busybox to F</bin/sh>, using it's
1277	built-in ash shell.
1278
1279	Finally, you need F</dev/null> inside the chroot for many scripts to work
1280	- either F<cp /dev/null output/target/dev> or bind-mounting your F</dev>
1281	will provide this.
1282
1283	After you have compiled and set up your buildroot target, you can copy
1284	F<staticperl> from the C<App::Staticperl> distribution or from your
1285	perl F<bin> directory (if you installed it) into the F<output/target>
1286	filesystem, chroot inside and run it.
1287		1271
1288	=head1 RECIPES / SPECIFIC MODULES	1272	=head1 RECIPES / SPECIFIC MODULES
1289		1273
1290	This section contains some common(?) recipes and information about	1274	This section contains some common(?) recipes and information about
1291	problems with some common modules or perl constructs that require extra	1275	problems with some common modules or perl constructs that require extra
…		…
1353	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.
1354		1338
1355	=item Gtk2	1339	=item Gtk2
1356		1340
1357	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	}
1358		1364
1359	=item Pango	1365	=item Pango
1360		1366
1361	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
1362	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>
…		…
1430	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
1431	is anybody's guess.	1437	is anybody's guess.
1432		1438
1433	=back	1439	=back
1434		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
1435	=head1 AUTHOR	1447	=head1 AUTHOR
1436		1448
1437	Marc Lehmann <schmorp@schmorp.de>	1449	Marc Lehmann <schmorp@schmorp.de>
1438	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.53 by root, Wed Jan 11 19:20:57 2012 UTC vs. Revision 1.63 by root, Tue Mar 19 15:24:49 2019 UTC

Diff Legend

Comparing App-Staticperl/staticperl.pod (file contents):
Revision 1.53 by root, Wed Jan 11 19:20:57 2012 UTC vs.
Revision 1.63 by root, Tue Mar 19 15:24:49 2019 UTC