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

Comparing App-Staticperl/staticperl.pod (file contents):
Revision 1.39 by root, Sat Apr 2 11:00:34 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
…		…
39	file that contains perl interpreter, libc, all the modules you need, all	39	file that contains perl interpreter, libc, all the modules you need, all
40	the libraries you need and of course your actual program.	40	the libraries you need and of course your actual program.
41		41
42	With F<uClibc> and F<upx> on x86, you can create a single 500kb binary	42	With F<uClibc> and F<upx> on x86, you can create a single 500kb binary
43	that contains perl and 100 modules such as POSIX, AnyEvent, EV, IO::AIO,	43	that contains perl and 100 modules such as POSIX, AnyEvent, EV, IO::AIO,
44	Coro and so on. Or any other choice of modules.	44	Coro and so on. Or any other choice of modules (and some other size :).
45		45
46	To see how this turns out, you can try out smallperl and bigperl, two	46	To see how this turns out, you can try out smallperl and bigperl, two
47	pre-built static and compressed perl binaries with many and even more	47	pre-built static and compressed perl binaries with many and even more
48	modules: just follow the links at L<http://staticperl.schmorp.de/>.	48	modules: just follow the links at L<http://staticperl.schmorp.de/>.
49		49
…		…
84	With F<staticperl>, the burden is mostly with the developer - only direct	84	With F<staticperl>, the burden is mostly with the developer - only direct
85	compile-time dependencies and L<AutoLoader> are handled automatically.	85	compile-time dependencies and L<AutoLoader> are handled automatically.
86	This means the modules to include often need to be tweaked manually.	86	This means the modules to include often need to be tweaked manually.
87		87
88	All this does not preclude more permissive modes to be implemented in	88	All this does not preclude more permissive modes to be implemented in
89	the future, but right now, you have to resolve state hidden dependencies	89	the future, but right now, you have to resolve hidden dependencies
90	manually.	90	manually.
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
94	Maintaining your own custom perl build can be a pain in the ass, and while	94	Maintaining your own custom perl build can be a pain in the ass, and while
…		…
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
202	=item F<staticperl cpan> [args...]	202	=item F<staticperl cpan> [args...]
203		203
204	Starts an interactive CPAN shell that you can use to install further	204	Starts an interactive CPAN shell that you can use to install further
205	modules. Installs the perl first if necessary, but apart from that,	205	modules. Installs the perl first if necessary, but apart from that,
206	no magic is involved: you could just as well run it manually via	206	no magic is involved: you could just as well run it manually via
207	F<~/.staticperl/perl/bin/cpan>.	207	F<~/.staticperl/perl/bin/cpan>, except that F<staticperl> additionally
		208	sets the environment variable C<$PERL> to the path of the perl
		209	interpreter, which is handy in subshells.
208		210
209	Any additional arguments are simply passed to the F<cpan> command.	211	Any 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
348	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
349	order given on the command line.	351	order 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
353	F<staticperl mkbundle> works by first assembling a list of candidate	355	F<staticperl mkbundle> works by first assembling a list of candidate
354	files and modules to include, then filtering them by include/exclude	356	files and modules to include, then filtering them by include/exclude
355	patterns. The remaining modules (together with their direct dependencies,	357	patterns. The remaining modules (together with their direct dependencies,
356	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
…		…
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
548	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
549	without any postprocessing (perl files might get stripped to reduce their	551	without any post-processing (perl files might get stripped to reduce their
550	size).	552	size).
551		553
552	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
553	clashing with embedded perl files (whose paths never start with C<&>),	555	clashing with embedded perl files (whose paths never start with C</>),
554	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>.
555		557
556	You can later get a copy of these files by calling C<staticperl::find	558	You can later get a copy of these files by calling C<static::find
557	"alias">.	559	"alias">.
558		560
559	An alternative way to embed binary files is to convert them to perl and	561	An alternative way to embed binary files is to convert them to perl and
560	use C<do> to get the contents - this method is a bit cumbersome, but works	562	use C<do> to get the contents - this method is a bit cumbersome, but works
561	both inside and outside of a staticperl bundle:	563	both 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
		575	By default, when F<mkbundle> hits a dynamic perl extension (e.g. a F<.so>
		576	or F<.dll> file), it will stop with a fatal error.
		577
		578	When this option is enabled, F<mkbundle> packages the shared
		579	object 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
		581	to you, F<staticperl> has no special support for this at the moment, apart
		582	from working around the lack of availability of F<PerlIO::scalar> while
		583	bootstrapping, at a speed cost.
		584
		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>.
		587
		588	(TODO for future self: write and insert a suitable example here, if
		589	somebody requests it).
570		590
571	=back	591	=back
572		592
573	=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.
574		594
…		…
685	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,
686	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
687	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
688	any way.	708	any way.
689		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
690	=item C<--perl>	718	=item C<--perl>
691		719
692	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
693	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
694	directory. The bundle files will be removed.	722	directory. The bundle files will be removed.
…		…
727		755
728	=item C<--ignore-env>	756	=item C<--ignore-env>
729		757
730	Generates extra code to unset some environment variables before	758	Generates extra code to unset some environment variables before
731	initialising/running perl. Perl supports a lot of environment variables	759	initialising/running perl. Perl supports a lot of environment variables
732	that might alter execution in ways that might be undesirablre for	760	that might alter execution in ways that might be undesirable for
733	standalone applications, and this option removes those known to cause	761	standalone applications, and this option removes those known to cause
734	trouble.	762	trouble.
735		763
736	Specifically, these are removed:	764	Specifically, these are removed:
737		765
738	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
739	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
740	C<PERL_SIGNALS> can alter execution significantly, and C<PERL_UNICODE>,	768	C<PERL_SIGNALS> can alter execution significantly, and C<PERL_UNICODE>,
741	C<PERLIO_DEBUG> and C<PERLIO> can affect input and output.	769	C<PERLIO_DEBUG> and C<PERLIO> can affect input and output.
742		770
743	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
…		…
758	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
759	modules are linked statically, but all external libraries are still	787	modules are linked statically, but all external libraries are still
760	referenced dynamically).	788	referenced dynamically).
761		789
762	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
763	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
764	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
765	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
766	statically.	794	statically.
767		795
768	=item C<--staticlib> libname	796	=item C<--staticlib> libname
769		797
…		…
781	staticperl mkperl -MIO::AIO --staticlib crypt	809	staticperl mkperl -MIO::AIO --staticlib crypt
782		810
783	# ldopts might now contain:	811	# ldopts might now contain:
784	# -lm -Wl,-Bstatic -lcrypt -Wl,-Bdynamic -lpthread	812	# -lm -Wl,-Bstatic -lcrypt -Wl,-Bdynamic -lpthread
785		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
786	=back	830	=back
787		831
788	=back	832	=back
789		833
790	=head3 EXTENDED GLOB PATTERNS	834	=head3 EXTENDED GLOB PATTERNS
…		…
833	In them you can override shell variables, or define shell functions	877	In them you can override shell variables, or define shell functions
834	("hooks") to be called at specific phases during installation. For	878	("hooks") to be called at specific phases during installation. For
835	example, you could define a C<postinstall> hook to install additional	879	example, you could define a C<postinstall> hook to install additional
836	modules from CPAN each time you start from scratch.	880	modules from CPAN each time you start from scratch.
837		881
838	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>
839	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
840	shell files in order:	884	following shell files in order:
841		885
842	/etc/staticperlrc	886	/etc/staticperlrc
843	~/.staticperlrc	887	~/.staticperlrc
844	$STATICPERL/rc	888	$STATICPERL/rc
845		889
…		…
882	=item C<STATICPERL>	926	=item C<STATICPERL>
883		927
884	The directory where staticperl stores all its files	928	The directory where staticperl stores all its files
885	(default: F<~/.staticperl>).	929	(default: F<~/.staticperl>).
886		930
		931	=item C<DLCACHE>
		932
		933	The path to a directory (will be created if it doesn't exist) where
		934	downloaded perl sources are being cached, to avoid downloading them
		935	again. The default is empty, which means there is no cache.
		936
		937	=item C<PERL_VERSION>
		938
		939	The perl version to install - C<5.12.5> is a good choice for small builds,
		940	but C<5.8.9> is also a good choice (5.8.9 is much smaller than 5.12.5), if
		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.
		950
887	=item C<PERL_MM_USE_DEFAULT>, C<EV_EXTRA_DEFS>, ...	951	=item C<PERL_MM_USE_DEFAULT>, C<EV_EXTRA_DEFS>, ...
888		952
889	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
890	installation, you can set any environment variable you want - some modules	954	installation. You can set (and export!) any environment variable you want
891	(such as L<Coro> or L<EV>) use environment variables for further tweaking.	955	- some modules (such as L<Coro> or L<EV>) use environment variables for
892		956	further tweaking.
893	=item C<PERL_VERSION>
894
895	The perl version to install - default is currently C<5.12.3>, but C<5.8.9>
896	is also a good choice (5.8.9 is much smaller than 5.12.3, while 5.10.1 is
897	about as big as 5.12.3).
898		957
899	=item C<PERL_PREFIX>	958	=item C<PERL_PREFIX>
900		959
901	The prefix where perl gets installed (default: F<$STATICPERL/perl>),	960	The directory where perl gets installed (default: F<$STATICPERL/perl>),
902	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.
903		963
904	=item C<PERL_CONFIGURE>	964	=item C<PERL_CONFIGURE>
905		965
906	Additional Configure options - these are simply passed to the perl	966	Additional Configure options - these are simply passed to the perl
907	Configure script. For example, if you wanted to enable dynamic loading,	967	Configure script. For example, if you wanted to enable dynamic loading,
908	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
909	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
910	and so on.	970	C<-Duseithreads> and so on.
911		971
912	More commonly, you would either activate 64 bit integer support	972	More commonly, you would either activate 64 bit integer support
913	(C<-Duse64bitint>), or disable large files support (-Uuselargefiles), to	973	(C<-Duse64bitint>), or disable large files support (C<-Uuselargefiles>),
914	reduce filesize further.	974	to reduce file size further.
915		975
916	=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>
917		977
918	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
919	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
…		…
922	the top of the F<staticperl> script for more info on these, and use a	982	the top of the F<staticperl> script for more info on these, and use a
923	F<~/.staticperlrc> to override them.	983	F<~/.staticperlrc> to override them.
924		984
925	Most of the variables override (or modify) the corresponding F<Configure>	985	Most of the variables override (or modify) the corresponding F<Configure>
926	variable, except C<PERL_CCFLAGS>, which gets appended.	986	variable, except C<PERL_CCFLAGS>, which gets appended.
		987
		988	The default for C<PERL_OPTIMIZE> is C<-Os> (assuming gcc or compatible
		989	compilers), and for C<PERL_LIBS> is C<-lm -lcrypt>, which should be good
		990	for most (but not all) systems.
		991
		992	For other compilers or more customised optimisation settings, you need to
		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
927		1005
928	=back	1006	=back
929		1007
930	=head4 Variables you probably I<do not want> to override	1008	=head4 Variables you probably I<do not want> to override
931		1009
…		…
996	Called after building, but before installing perl. Current working	1074	Called after building, but before installing perl. Current working
997	directory is the perl source directory.	1075	directory is the perl source directory.
998		1076
999	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.
1000		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
1001	=item postinstall	1088	=item postinstall
1002		1089
1003	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>,
1004	but before setting the "installation O.K." flag.	1091	but before setting the "installation O.K." flag.
1005		1092
…		…
1057	staticperl_init (0);	1144	staticperl_init (0);
1058	newXSproto ("myapp::xsfunction", xsfunction, __FILE__, "$$;$");	1145	newXSproto ("myapp::xsfunction", xsfunction, __FILE__, "$$;$");
1059	eval_pv ("require myapp::main", 1); // executes "myapp/main.pm"	1146	eval_pv ("require myapp::main", 1); // executes "myapp/main.pm"
1060	}	1147	}
1061		1148
1062	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
1063	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
1064	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
1065	but before the preamble code is executed:	1152	before the preamble code is executed:
1066		1153
1067	static void	1154	static void
1068	xs_init (pTHX)	1155	xs_init (pTHX)
1069	{	1156	{
1070	newXSproto ("myapp::xsfunction", xsfunction, __FILE__, "$$;$");	1157	newXSproto ("myapp::xsfunction", xsfunction, __FILE__, "$$;$");
…		…
1110		1197
1111	=back	1198	=back
1112		1199
1113	=head1 RUNTIME FUNCTIONALITY	1200	=head1 RUNTIME FUNCTIONALITY
1114		1201
1115	Binaries created with C<mkbundle>/C<mkperl> contain extra functions, which	1202	Binaries created with C<mkbundle>/C<mkperl> contain extra functionality,
1116	are required to access the bundled perl sources, but might be useful for	1203	mostly related to the extra files bundled in the binary (the virtual
1117	other purposes.	1204	filesystem). All of this data is statically compiled into the binary, and
		1205	accessing means copying it from a read-only section of your binary. Data
		1206	pages in this way are usually freed by the operating system, as they aren't
		1207	used more then once.
		1208
		1209	=head2 VIRTUAL FILESYSTEM
		1210
		1211	Every bundle has a virtual filesystem. The only information stored in it
		1212	is the path and contents of each file that was bundled.
		1213
		1214	=head3 LAYOUT
		1215
		1216	Any paths starting with an ampersand (F<&>) or exclamation mark (F<!>) are
		1217	reserved by F<staticperl>. They must only be used as described in this
		1218	section.
		1219
		1220	=over 4
		1221
		1222	=item !
		1223
		1224	All files that typically cannot be loaded from memory (such as dynamic
		1225	objects or shared libraries), but have to reside in the filesystem, are
		1226	prefixed with F<!>. Typically these files get written out to some
		1227	(semi-)temporary directory shortly after program startup, or before being
		1228	used.
		1229
		1230	=item !boot
		1231
		1232	The bootstrap file, if specified during bundling.
		1233
		1234	=item !auto/
		1235
		1236	Shared objects or dlls corresponding to dynamically-linked perl extensions
		1237	are stored with an F<!auto/> prefix.
		1238
		1239	=item !lib/
		1240
		1241	External shared libraries are stored in this directory.
		1242
		1243	=item any letter
		1244
		1245	Any path starting with a letter is a perl library file. For example,
		1246	F<Coro/AIO.pm> corresponds to the file loaded by C<use Coro::AIO>, and
		1247	F<Coro/jit.pl> corresponds to C<require "Coro/jit.pl">.
		1248
		1249	Obviously, module names shouldn't start with any other characters than
		1250	letters :)
		1251
		1252	=back
		1253
		1254	=head3 FUNCTIONS
		1255
		1256	=over 4
		1257
		1258	=item $file = static::find $path
		1259
		1260	Returns the data associated with the given C<$path>
		1261	(e.g. C<Digest/MD5.pm>, C<auto/POSIX/autosplit.ix>).
		1262
		1263	Returns C<undef> if the file isn't embedded.
		1264
		1265	=item @paths = static::list
		1266
		1267	Returns the list of all paths embedded in this binary.
		1268
		1269	=back
		1270
		1271	=head2 EXTRA FEATURES
1118		1272
1119	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>
1120	overrides the C<@INC> array.	1274	overrides the C<@INC> array.
1121		1275
1122	=over 4	1276	=head1 FULLY STATIC BINARIES - ALPINE LINUX
1123		1277
1124	=item $file = staticperl::find $path	1278	This section once contained a way to build fully static (including
		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.
1125		1284
1126	Returns the data associated with the given C<$path>	1285	The 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	1286	quite dependent on kernel versions, so the newest version of alpine linux
1128	the UNIX path relative to the perl library directory.	1287	might need a newer kernel then you might want for, if you plan to run your
1129		1288	binaries on on other kernels.
1130	Returns C<undef> if the file isn't embedded.
1131
1132	=item @paths = staticperl::list
1133
1134	Returns the list of all paths embedded in this binary.
1135
1136	=back
1137
1138	=head1 FULLY STATIC BINARIES - UCLIBC AND BUILDROOT
1139
1140	To make truly static (Linux-) libraries, you might want to have a look at
1141	buildroot (L<http://buildroot.uclibc.org/>).
1142
1143	Buildroot is primarily meant to set up a cross-compile environment (which
1144	is not so useful as perl doesn't quite like cross compiles), but it can also compile
1145	a chroot environment where you can use F<staticperl>.
1146
1147	To do so, download buildroot, and enable "Build options => development
1148	files in target filesystem" and optionally "Build options => gcc
1149	optimization level (optimize for size)". At the time of writing, I had
1150	good experiences with GCC 4.4.x but not GCC 4.5.
1151
1152	To minimise code size, I used C<-pipe -ffunction-sections -fdata-sections
1153	-finline-limit=8 -fno-builtin-strlen -mtune=i386>. The C<-mtune=i386>
1154	doesn't decrease codesize much, but it makes the file much more
1155	compressible.
1156
1157	If you don't need Coro or threads, you can go with "linuxthreads.old" (or
1158	no thread support). For Coro, it is highly recommended to switch to a
1159	uClibc newer than 0.9.31 (at the time of this writing, I used the 20101201
1160	snapshot) and enable NPTL, otherwise Coro needs to be configured with the
1161	ultra-slow pthreads backend to work around linuxthreads bugs (it also uses
1162	twice the address space needed for stacks).
1163
1164	If you use C<linuxthreads.old>, then you should also be aware that
1165	uClibc shares C<errno> between all threads when statically linking. See
1166	L<http://lists.uclibc.org/pipermail/uclibc/2010-June/044157.html> for a
1167	workaround (And L<https://bugs.uclibc.org/2089> for discussion).
1168
1169	C<ccache> support is also recommended, especially if you want
1170	to play around with buildroot options. Enabling the C<miniperl>
1171	package will probably enable all options required for a successful
1172	perl build. F<staticperl> itself additionally needs either C<wget>
1173	(recommended, for CPAN) or C<curl>.
1174
1175	As for shells, busybox should provide all that is needed, but the default
1176	busybox configuration doesn't include F<comm> which is needed by perl -
1177	either make a custom busybox config, or compile coreutils.
1178
1179	For the latter route, you might find that bash has some bugs that keep
1180	it from working properly in a chroot - either use dash (and link it to
1181	F</bin/sh> inside the chroot) or link busybox to F</bin/sh>, using it's
1182	built-in ash shell.
1183
1184	Finally, 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
1186	both provide this.
1187
1188	After you have compiled and set up your buildroot target, you can copy
1189	F<staticperl> from the C<App::Staticperl> distribution or from your
1190	perl f<bin> directory (if you installed it) into the F<output/target>
1191	filesystem, chroot inside and run it.
1192		1289
1193	=head1 RECIPES / SPECIFIC MODULES	1290	=head1 RECIPES / SPECIFIC MODULES
1194		1291
1195	This section contains some common(?) recipes and information about	1292	This section contains some common(?) recipes and information about
1196	problems with some common modules or perl constructs that require extra	1293	problems with some common modules or perl constructs that require extra
…		…
1200		1297
1201	=over 4	1298	=over 4
1202		1299
1203	=item utf8	1300	=item utf8
1204		1301
1205	Some functionality in the utf8 module, such as swash handling (used	1302	Some functionality in the C<utf8> module, such as swash handling
1206	for unicode character ranges in regexes) is implemented in the	1303	(used for unicode character ranges in regexes) is implemented in the
1207	C<"utf8_heavy.pl"> library:	1304	C<utf8_heavy.pl> library:
1208		1305
1209	-Mutf8_heavy.pl	1306	-Mutf8_heavy.pl
1210		1307
1211	Many Unicode properties in turn are defined in separate modules,	1308	Many Unicode properties in turn are defined in separate modules,
1212	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
1213	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
1214	are big (7MB uncompressed, although F<staticperl> contains special	1311	are big (7MB uncompressed, although F<staticperl> contains special
1215	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
1216	only might pay off.	1313	application might pay off.
1217		1314
1218	To simply include the whole unicode database, use:	1315	To simply include the whole unicode database, use:
1219		1316
1220	--incglob '/unicore/**.pl'	1317	--incglob '/unicore/**.pl'
1221		1318
…		…
1258	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.
1259		1356
1260	=item Gtk2	1357	=item Gtk2
1261		1358
1262	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	}
1263		1382
1264	=item Pango	1383	=item Pango
1265		1384
1266	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
1267	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>
…		…
1335	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
1336	is anybody's guess.	1455	is anybody's guess.
1337		1456
1338	=back	1457	=back
1339		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
1340	=head1 AUTHOR	1465	=head1 AUTHOR
1341		1466
1342	Marc Lehmann <schmorp@schmorp.de>	1467	Marc Lehmann <schmorp@schmorp.de>
1343	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.39 by root, Sat Apr 2 11:00:34 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.39 by root, Sat Apr 2 11:00:34 2011 UTC vs.
Revision 1.67 by root, Fri Aug 4 03:58:52 2023 UTC