[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.67 by root, Fri Aug 4 03:58:52 2023 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
…		…
124		124
125	=head1 THE F<STATICPERL> SCRIPT	125	=head1 THE F<STATICPERL> SCRIPT
126		126
127	This module installs a script called F<staticperl> into your perl	127	This module installs a script called F<staticperl> into your perl
128	binary directory. The script is fully self-contained, and can be	128	binary directory. The script is fully self-contained, and can be
129	used without perl (for example, in an uClibc chroot environment). In	129	used without perl (for example, in an uClibc/dietlibc/musl chroot
130	fact, it can be extracted from the C<App::Staticperl> distribution	130	environment). In fact, it can be extracted from the C<App::Staticperl>
131	tarball as F<bin/staticperl>, without any installation. The	131	distribution tarball as F<bin/staticperl>, without any installation. The
132	newest (possibly alpha) version can also be downloaded from	132	newest (possibly alpha) version can also be downloaded from
133	L<http://staticperl.schmorp.de/staticperl>.	133	L<http://staticperl.schmorp.de/staticperl>.
134		134
135	F<staticperl> interprets the first argument as a command to execute,	135	F<staticperl> interprets the first argument as a command to execute,
136	optionally followed by any parameters.	136	optionally followed by any parameters.
…		…
189	Wipes the perl installation directory (usually F<~/.staticperl/perl>) and	189	Wipes the perl installation directory (usually F<~/.staticperl/perl>) and
190	installs the perl distribution, potentially after building it first.	190	installs the perl distribution, potentially after building it first.
191		191
192	=item F<staticperl perl> [args...]	192	=item F<staticperl perl> [args...]
193		193
194	Invokes the compiled perl interpreter with the given args. Basically the	194	Invokes the compiled perl interpreter with the given
195	same as starting perl directly (usually via F<~/.staticperl/bin/perl>),	195	arguments. Basically the same as starting perl directly (usually via
196	but beats typing the path sometimes.	196	F<~/.staticperl/bin/perl>), but beats typing the path sometimes.
197		197
198	Example: check that the Gtk2 module is installed and loadable.	198	Example: check that the Gtk2 module is installed and loadable.
199		199
200	staticperl perl -MGtk2 -e0	200	staticperl perl -MGtk2 -e0
201		201
…		…
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 post-processing (perl files might get stripped to reduce their
552	size).	552	size).
553		553
554	If you specify an alias you should probably add a C</> prefix to avoid	554	If you specify an alias you should probably add a C</> prefix to avoid
555	clashing with embedded perl files (whose paths never start with C</>),	555	clashing with embedded perl files (whose paths never start with C</>),
556	and/or use a special directory prefix, such as C</res/name>.	556	and/or use a special directory prefix, such as C</res/name>.
…		…
583	bootstrapping, at a speed cost.	583	bootstrapping, at a speed cost.
584		584
585	One way to deal with this is to write all files starting with F<!> into	585	One way to deal with this is to write all files starting with F<!> into
586	some directory and then C<unshift> that path onto C<@INC>.	586	some directory and then C<unshift> that path onto C<@INC>.
587		587
588	#TODO: example	588	(TODO for future self: write and insert a suitable example here, if
		589	somebody requests it).
589		590
590	=back	591	=back
591		592
592	=item Step 2: filter all files using C<--include> and C<--exclude> options.	593	=item Step 2: filter all files using C<--include> and C<--exclude> options.
593		594
…		…
704	Last not least, if you need accurate line numbers in error messages,	705	Last not least, if you need accurate line numbers in error messages,
705	or in the unlikely case where C<pod> is too slow, or some module gets	706	or in the unlikely case where C<pod> is too slow, or some module gets
706	mistreated, you can specify C<none> to not mangle included perl sources in	707	mistreated, you can specify C<none> to not mangle included perl sources in
707	any way.	708	any way.
708		709
		710	=item C<--compress> C<none>\|C<lzf>
		711
		712	Compress each included library file with C<lzf> (default), or do not
		713	compress (C<none>). LZF compression typically halves the size of the
		714	included library data at almost no overhead, but is counterproductive if
		715	you are using another compression solution such as C<UPX>, so it can be
		716	disabled.
		717
709	=item C<--perl>	718	=item C<--perl>
710		719
711	After writing out the bundle files, try to link a new perl interpreter. It	720	After writing out the bundle files, try to link a new perl interpreter. It
712	will be called F<perl> and will be left in the current working	721	will be called F<perl> and will be left in the current working
713	directory. The bundle files will be removed.	722	directory. The bundle files will be removed.
…		…
746		755
747	=item C<--ignore-env>	756	=item C<--ignore-env>
748		757
749	Generates extra code to unset some environment variables before	758	Generates extra code to unset some environment variables before
750	initialising/running perl. Perl supports a lot of environment variables	759	initialising/running perl. Perl supports a lot of environment variables
751	that might alter execution in ways that might be undesirablre for	760	that might alter execution in ways that might be undesirable for
752	standalone applications, and this option removes those known to cause	761	standalone applications, and this option removes those known to cause
753	trouble.	762	trouble.
754		763
755	Specifically, these are removed:	764	Specifically, these are removed:
756		765
757	C<PERL_HASH_SEED_DEBUG> and C<PERL_DEBUG_MSTATS> can cause underaible	766	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	767	output, C<PERL5OPT>, C<PERL_DESTRUCT_LEVEL>, C<PERL_HASH_SEED> and
759	C<PERL_SIGNALS> can alter execution significantly, and C<PERL_UNICODE>,	768	C<PERL_SIGNALS> can alter execution significantly, and C<PERL_UNICODE>,
760	C<PERLIO_DEBUG> and C<PERLIO> can affect input and output.	769	C<PERLIO_DEBUG> and C<PERLIO> can affect input and output.
761		770
762	The variables C<PERL_LIB> and C<PERL5_LIB> are always ignored because the	771	The variables C<PERL_LIB> and C<PERL5_LIB> are always ignored because the
…		…
777	The default is to link the new binary dynamically (that means all perl	786	The default is to link the new binary dynamically (that means all perl
778	modules are linked statically, but all external libraries are still	787	modules are linked statically, but all external libraries are still
779	referenced dynamically).	788	referenced dynamically).
780		789
781	Keep in mind that Solaris doesn't support static linking at all, and	790	Keep in mind that Solaris doesn't support static linking at all, and
782	systems based on GNU libc don't really support it in a very usable	791	systems based on GNU libc don't really support it in a very usable fashion
783	fashion either. Try uClibc if you want to create fully statically linked	792	either. Try dietlibc or musl if you want to create fully statically linked
784	executables, or try the C<--staticlib> option to link only some libraries	793	executables, or try the C<--staticlib> option to link only some libraries
785	statically.	794	statically.
786		795
787	=item C<--staticlib> libname	796	=item C<--staticlib> libname
788		797
…		…
800	staticperl mkperl -MIO::AIO --staticlib crypt	809	staticperl mkperl -MIO::AIO --staticlib crypt
801		810
802	# ldopts might now contain:	811	# ldopts might now contain:
803	# -lm -Wl,-Bstatic -lcrypt -Wl,-Bdynamic -lpthread	812	# -lm -Wl,-Bstatic -lcrypt -Wl,-Bdynamic -lpthread
804		813
		814	=item C<--extra-cflags> string
		815
		816	Specifies extra compiler flags, used when compiling the bundle file. The
		817	flags are appended to all the existing flags, so can be sued to override
		818	settings.
		819
		820	=item C<--extra-ldflags> string
		821
		822	Specifies extra linker flags, used when linking the bundle.
		823
		824	=item C<--extra-libs> string
		825
		826	Extra linker flags, appended at the end when linking. The difference to
		827	C<--extra-ldflags> is that the ldflags are appended to the flags, before
		828	the objects and libraries, and the extra libs are added at the end.
		829
805	=back	830	=back
806		831
807	=back	832	=back
808		833
809	=head3 EXTENDED GLOB PATTERNS	834	=head3 EXTENDED GLOB PATTERNS
…		…
852	In them you can override shell variables, or define shell functions	877	In them you can override shell variables, or define shell functions
853	("hooks") to be called at specific phases during installation. For	878	("hooks") to be called at specific phases during installation. For
854	example, you could define a C<postinstall> hook to install additional	879	example, you could define a C<postinstall> hook to install additional
855	modules from CPAN each time you start from scratch.	880	modules from CPAN each time you start from scratch.
856		881
857	If the env variable C<$STATICPERLRC> is set, then F<staticperl> will try	882	If the environment variable C<$STATICPERLRC> is set, then F<staticperl>
858	to source the file named with it only. Otherwise, it tries the following	883	will try to source the file named with it only. Otherwise, it tries the
859	shell files in order:	884	following shell files in order:
860		885
861	/etc/staticperlrc	886	/etc/staticperlrc
862	~/.staticperlrc	887	~/.staticperlrc
863	$STATICPERL/rc	888	$STATICPERL/rc
864		889
…		…
909	downloaded perl sources are being cached, to avoid downloading them	934	downloaded perl sources are being cached, to avoid downloading them
910	again. The default is empty, which means there is no cache.	935	again. The default is empty, which means there is no cache.
911		936
912	=item C<PERL_VERSION>	937	=item C<PERL_VERSION>
913		938
914	The perl version to install - default is currently C<5.12.3>, but C<5.8.9>	939	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	940	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).	941	it builds on your system.
		942
		943	You can also set this variable to the absolute URL of a tarball (F<.tar>,
		944	F<.tar.gz>, F<.tar.bz2>, F<.tar.lzma> or F<.tar.xz>), or to the absolute
		945	path of an unpacked perl source tree, which will be copied.
		946
		947	The default is currently
		948	F<http://stableperl.schmorp.de/dist/latest.tar.gz>, i.e. the latest
		949	stableperl release.
917		950
918	=item C<PERL_MM_USE_DEFAULT>, C<EV_EXTRA_DEFS>, ...	951	=item C<PERL_MM_USE_DEFAULT>, C<EV_EXTRA_DEFS>, ...
919		952
920	Usually set to C<1> to make modules "less inquisitive" during their	953	Usually set to C<1> to make modules "less inquisitive" during their
921	installation. You can set (and export!) any environment variable you want	954	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	955	- some modules (such as L<Coro> or L<EV>) use environment variables for
923	further tweaking.	956	further tweaking.
924		957
925	=item C<PERL_PREFIX>	958	=item C<PERL_PREFIX>
926		959
927	The prefix where perl gets installed (default: F<$STATICPERL/perl>),	960	The directory where perl gets installed (default: F<$STATICPERL/perl>),
928	i.e. where the F<bin> and F<lib> subdirectories will end up.	961	i.e. where the F<bin> and F<lib> subdirectories will end up. Previous
		962	contents will be removed on installation.
929		963
930	=item C<PERL_CONFIGURE>	964	=item C<PERL_CONFIGURE>
931		965
932	Additional Configure options - these are simply passed to the perl	966	Additional Configure options - these are simply passed to the perl
933	Configure script. For example, if you wanted to enable dynamic loading,	967	Configure script. For example, if you wanted to enable dynamic loading,
934	you could pass C<-Dusedl>. To enable ithreads (Why would you want that	968	you could pass C<-Dusedl>. To enable ithreads (Why would you want that
935	insanity? Don't! Use L<forks> instead!) you would pass C<-Duseithreads>	969	insanity? Don't! Use L<Coro> or L<forks> instead!) you would pass
936	and so on.	970	C<-Duseithreads> and so on.
937		971
938	More commonly, you would either activate 64 bit integer support	972	More commonly, you would either activate 64 bit integer support
939	(C<-Duse64bitint>), or disable large files support (-Uuselargefiles), to	973	(C<-Duse64bitint>), or disable large files support (C<-Uuselargefiles>),
940	reduce filesize further.	974	to reduce file size further.
941		975
942	=item C<PERL_CC>, C<PERL_CCFLAGS>, C<PERL_OPTIMIZE>, C<PERL_LDFLAGS>, C<PERL_LIBS>	976	=item C<PERL_CC>, C<PERL_CCFLAGS>, C<PERL_OPTIMIZE>, C<PERL_LDFLAGS>, C<PERL_LIBS>
943		977
944	These flags are passed to perl's F<Configure> script, and are generally	978	These flags are passed to perl's F<Configure> script, and are generally
945	optimised for small size (at the cost of performance). Since they also	979	optimised for small size (at the cost of performance). Since they also
…		…
949	F<~/.staticperlrc> to override them.	983	F<~/.staticperlrc> to override them.
950		984
951	Most of the variables override (or modify) the corresponding F<Configure>	985	Most of the variables override (or modify) the corresponding F<Configure>
952	variable, except C<PERL_CCFLAGS>, which gets appended.	986	variable, except C<PERL_CCFLAGS>, which gets appended.
953		987
954	You should have a look near the beginning of the F<staticperl> script -	988	The default for C<PERL_OPTIMIZE> is C<-Os> (assuming gcc or compatible
955	staticperl tries to default C<PERL_OPTIMIZE> to some psace-saving options	989	compilers), and for C<PERL_LIBS> is C<-lm -lcrypt>, which should be good
956	suitable for newer gcc versions. For other compilers or older versions you	990	for most (but not all) systems.
		991
		992	For other compilers or more customised optimisation settings, you need to
957	need to adjust these, for example, in your F<~/.staticperlrc>.	993	adjust these, e.g. in your F<~/.staticperlrc>.
		994
		995	With gcc on x86 and amd64, you can often get more space-savings by using:
		996
		997	-Os -ffunction-sections -fdata-sections -finline-limit=8 -mpush-args
		998	-mno-inline-stringops-dynamically -mno-align-stringops
		999
		1000	And on x86 and pentium3 and newer (basically everything you might ever
		1001	want to run on), adding these is even better for space-savings (use
		1002	C<-mtune=core2> or something newer for much faster code, too):
		1003
		1004	-fomit-frame-pointer -march=pentium3 -mtune=i386
958		1005
959	=back	1006	=back
960		1007
961	=head4 Variables you probably I<do not want> to override	1008	=head4 Variables you probably I<do not want> to override
962		1009
…		…
1027	Called after building, but before installing perl. Current working	1074	Called after building, but before installing perl. Current working
1028	directory is the perl source directory.	1075	directory is the perl source directory.
1029		1076
1030	I have no clue what this could be used for - tell me.	1077	I have no clue what this could be used for - tell me.
1031		1078
		1079	=item postcpanconfig
		1080
		1081	Called just after CPAN has been configured, but before it has been used to
		1082	install anything. You can further change the configuration like this:
		1083
		1084	"$PERL_PREFIX"/bin/perl -MCPAN::MyConfig -MCPAN -e '
		1085	CPAN::Shell->o (conf => urllist => push => "'"$CPAN"'");
		1086	' \|\| fatal "error while initialising CPAN in postcpanconfig"
		1087
1032	=item postinstall	1088	=item postinstall
1033		1089
1034	Called after perl and any extra modules have been installed in C<$PREFIX>,	1090	Called after perl and any extra modules have been installed in C<$PREFIX>,
1035	but before setting the "installation O.K." flag.	1091	but before setting the "installation O.K." flag.
1036		1092
…		…
1088	staticperl_init (0);	1144	staticperl_init (0);
1089	newXSproto ("myapp::xsfunction", xsfunction, __FILE__, "$$;$");	1145	newXSproto ("myapp::xsfunction", xsfunction, __FILE__, "$$;$");
1090	eval_pv ("require myapp::main", 1); // executes "myapp/main.pm"	1146	eval_pv ("require myapp::main", 1); // executes "myapp/main.pm"
1091	}	1147	}
1092		1148
1093	When your bootcode already wants to access some XS functions at	1149	When your boot code already wants to access some XS functions at compile
1094	compiletime, then you need to supply an C<xs_init> function pointer that	1150	time, then you need to supply an C<xs_init> function pointer that is
1095	is called as soon as perl is initialised enough to define XS functions,	1151	called as soon as perl is initialised enough to define XS functions, but
1096	but before the preamble code is executed:	1152	before the preamble code is executed:
1097		1153
1098	static void	1154	static void
1099	xs_init (pTHX)	1155	xs_init (pTHX)
1100	{	1156	{
1101	newXSproto ("myapp::xsfunction", xsfunction, __FILE__, "$$;$");	1157	newXSproto ("myapp::xsfunction", xsfunction, __FILE__, "$$;$");
…		…
1145		1201
1146	Binaries created with C<mkbundle>/C<mkperl> contain extra functionality,	1202	Binaries created with C<mkbundle>/C<mkperl> contain extra functionality,
1147	mostly related to the extra files bundled in the binary (the virtual	1203	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	1204	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	1205	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	1206	pages in this way are usually freed by the operating system, as they aren't
1151	use more the onace.	1207	used more then once.
1152		1208
1153	=head2 VIRTUAL FILESYSTEM	1209	=head2 VIRTUAL FILESYSTEM
1154		1210
1155	Every bundle has a virtual filesystem. The only information stored in it	1211	Every bundle has a virtual filesystem. The only information stored in it
1156	is the path and contents of each file that was bundled.	1212	is the path and contents of each file that was bundled.
1157		1213
1158	=head3 LAYOUT	1214	=head3 LAYOUT
1159		1215
1160	Any path starting with an ampersand (F<&>) or exclamation mark (F<!>) are	1216	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	1217	reserved by F<staticperl>. They must only be used as described in this
1162	section.	1218	section.
1163		1219
1164	=over 4	1220	=over 4
1165		1221
…		…
1186		1242
1187	=item any letter	1243	=item any letter
1188		1244
1189	Any path starting with a letter is a perl library file. For example,	1245	Any path starting with a letter is a perl library file. For example,
1190	F<Coro/AIO.pm> corresponds to the file loaded by C<use Coro::AIO>, and	1246	F<Coro/AIO.pm> corresponds to the file loaded by C<use Coro::AIO>, and
1191	F<Coro/jit.pl> corresponds to C<require "Coro/jit.pl">.	1247	F<Coro/jit.pl> corresponds to C<require "Coro/jit.pl">.
1192		1248
1193	Obviously, module names shouldn't start with any other characters than	1249	Obviously, module names shouldn't start with any other characters than
1194	letters :)	1250	letters :)
1195		1251
1196	=back	1252	=back
…		…
1215	=head2 EXTRA FEATURES	1271	=head2 EXTRA FEATURES
1216		1272
1217	In addition, for the embedded loading of perl files to work, F<staticperl>	1273	In addition, for the embedded loading of perl files to work, F<staticperl>
1218	overrides the C<@INC> array.	1274	overrides the C<@INC> array.
1219		1275
1220	=head1 FULLY STATIC BINARIES - UCLIBC AND BUILDROOT	1276	=head1 FULLY STATIC BINARIES - ALPINE LINUX
1221		1277
1222	To make truly static (Linux-) libraries, you might want to have a look at	1278	This section once contained a way to build fully static (including
1223	buildroot (L<http://buildroot.uclibc.org/>).	1279	uClibc) binaries with buildroot. Unfortunately, buildroot no longer
		1280	supports a compiler, so I recommend using alpine linux instead
		1281	(L<http://alpinelinux.org/>). Get yourself a VM (e.g. with qemu), run an
		1282	older alpine linux verison in it (e.g. 2.4), copy staticperl inside and
		1283	use it.
1224		1284
1225	Buildroot is primarily meant to set up a cross-compile environment (which	1285	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	1286	quite dependent on kernel versions, so the newest version of alpine linux
1227	a chroot environment where you can use F<staticperl>.	1287	might need a newer kernel then you might want for, if you plan to run your
1228		1288	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		1289
1275	=head1 RECIPES / SPECIFIC MODULES	1290	=head1 RECIPES / SPECIFIC MODULES
1276		1291
1277	This section contains some common(?) recipes and information about	1292	This section contains some common(?) recipes and information about
1278	problems with some common modules or perl constructs that require extra	1293	problems with some common modules or perl constructs that require extra
…		…
1282		1297
1283	=over 4	1298	=over 4
1284		1299
1285	=item utf8	1300	=item utf8
1286		1301
1287	Some functionality in the utf8 module, such as swash handling (used	1302	Some functionality in the C<utf8> module, such as swash handling
1288	for unicode character ranges in regexes) is implemented in the	1303	(used for unicode character ranges in regexes) is implemented in the
1289	C<"utf8_heavy.pl"> library:	1304	C<utf8_heavy.pl> library:
1290		1305
1291	-Mutf8_heavy.pl	1306	-Mutf8_heavy.pl
1292		1307
1293	Many Unicode properties in turn are defined in separate modules,	1308	Many Unicode properties in turn are defined in separate modules,
1294	such as C<"unicore/Heavy.pl"> and more specific data tables such as	1309	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	1310	C<unicore/To/Digit.pl> or C<unicore/lib/Perl/Word.pl>. These tables
1296	are big (7MB uncompressed, although F<staticperl> contains special	1311	are big (7MB uncompressed, although F<staticperl> contains special
1297	handling for those files), so including them on demand by your application	1312	handling for those files), so including them only on demand in your
1298	only might pay off.	1313	application might pay off.
1299		1314
1300	To simply include the whole unicode database, use:	1315	To simply include the whole unicode database, use:
1301		1316
1302	--incglob '/unicore/**.pl'	1317	--incglob '/unicore/**.pl'
1303		1318
…		…
1340	C<MAN3PODS> to be empty via the C<PERL_MM_OPT> environment variable.	1355	C<MAN3PODS> to be empty via the C<PERL_MM_OPT> environment variable.
1341		1356
1342	=item Gtk2	1357	=item Gtk2
1343		1358
1344	See Pango, same problems, same solution.	1359	See Pango, same problems, same solution.
		1360
		1361	=item Net::SSLeay
		1362
		1363	This module hasn't been significantly updated since OpenSSL is called
		1364	OpenSSL, and fails to properly link against dependent libraries, most
		1365	commonly, it forgets to specify C<-ldl> when linking.
		1366
		1367	On GNU/Linux systems this usually goes undetected, as perl usually links
		1368	against C<-ldl> itself and OpenSSL just happens to pick it up that way, by
		1369	chance.
		1370
		1371	For static builds, you either have to configure C<-ldl> manually, or you
		1372	can use the following snippet in your C<postinstall> hook which patches
		1373	Net::SSLeay after installation, which happens to work most of the time:
		1374
		1375	postinstall() {
		1376	# first install it
		1377	instcpan Net::SSLeay
		1378	# then add -ldl for future linking
		1379	chmod u+w "$PERL_PREFIX"/lib/auto/Net/SSLeay/extralibs.ld
		1380	echo " -ldl" >>"$PERL_PREFIX"/lib/auto/Net/SSLeay/extralibs.ld
		1381	}
1345		1382
1346	=item Pango	1383	=item Pango
1347		1384
1348	In addition to the C<MAN3PODS> problem in Glib, Pango also routes around	1385	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>	1386	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	1454	gains little. Why Socket exposes a C function that is in the core already
1418	is anybody's guess.	1455	is anybody's guess.
1419		1456
1420	=back	1457	=back
1421		1458
		1459	=head1 ADDITIONAL RESOURCES
		1460
		1461	Some guy has made a repository on github
		1462	(L<https://github.com/gh0stwizard/staticperl-modules>) with some modules
		1463	patched to build with staticperl.
		1464
1422	=head1 AUTHOR	1465	=head1 AUTHOR
1423		1466
1424	Marc Lehmann <schmorp@schmorp.de>	1467	Marc Lehmann <schmorp@schmorp.de>
1425	http://software.schmorp.de/pkg/staticperl.html	1468	http://software.schmorp.de/pkg/staticperl.html
		1469

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.67 by root, Fri Aug 4 03:58:52 2023 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.67 by root, Fri Aug 4 03:58:52 2023 UTC