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

Comparing App-Staticperl/staticperl.pod (file contents):
Revision 1.7 by root, Mon Dec 6 21:21:44 2010 UTC vs.
Revision 1.17 by root, Thu Dec 9 08:55:52 2010 UTC

…		…
1	=head1 NAME	1	=head1 NAME
2		2
3	staticperl - perl, libc, 50 modules, all in one 500kb file	3	staticperl - perl, libc, 100 modules, all in one 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
14	staticperl cpan # invoke CPAN shell	14	staticperl cpan # invoke CPAN shell
15	staticperl instmod path... # install unpacked modules	15	staticperl instmod path... # install unpacked modules
16	staticperl instcpan modulename... # install modules from CPAN	16	staticperl instcpan modulename... # install modules from CPAN
17	staticperl mkbundle <bundle-args...> # see documentation	17	staticperl mkbundle <bundle-args...> # see documentation
18	staticperl mkperl <bundle-args...> # see documentation	18	staticperl mkperl <bundle-args...> # see documentation
		19	staticperl mkapp appname <bundle-args...> # see documentation
19		20
20	Typical Examples:	21	Typical Examples:
21		22
22	staticperl install # fetch, configure, build and install perl	23	staticperl install # fetch, configure, build and install perl
23	staticperl cpan # run interactive cpan shell	24	staticperl cpan # run interactive cpan shell
24	staticperl mkperl -M '"Config_heavy.pl"' # build a perl that supports -V	25	staticperl mkperl -M '"Config_heavy.pl"' # build a perl that supports -V
25	staticperl mkperl -MAnyEvent::Impl::Perl -MAnyEvent::HTTPD -MURI -MURI::http	26	staticperl mkperl -MAnyEvent::Impl::Perl -MAnyEvent::HTTPD -MURI -MURI::http
26	# build a perl with the above modules linked in	27	# build a perl with the above modules linked in
		28	staticperl mkapp myapp --boot mainprog mymodules
		29	# build a binary "myapp" from mainprog and mymodules
27		30
28	=head1 DESCRIPTION	31	=head1 DESCRIPTION
29		32
30	This script helps you creating single-file perl interpreters, or embedding	33	This script helps you to create single-file perl interpreters
31	a perl interpreter in your applications. Single-file means that it is	34	or applications, or embedding a perl interpreter in your
32	fully self-contained - no separate shared objects, no autoload fragments,	35	applications. Single-file means that it is fully self-contained - no
33	no .pm or .pl files are needed. And when linking statically, you can	36	separate shared objects, no autoload fragments, no .pm or .pl files are
34	create (or embed) a single file that contains perl interpreter, libc, all	37	needed. And when linking statically, you can create (or embed) a single
35	the modules you need and all the libraries you need.	38	file that contains perl interpreter, libc, all the modules you need, all
		39	the libraries you need and of course your actual program.
36		40
37	With F<uClibc> and F<upx> on x86, you can create a single 500kb binary that	41	With F<uClibc> and F<upx> on x86, you can create a single 500kb binary
38	contains perl and 50 modules such as AnyEvent, EV, IO::AIO, Coro and so	42	that contains perl and 100 modules such as POSIX, AnyEvent, EV, IO::AIO,
39	on. Or any other choice of modules.	43	Coro and so on. Or any other choice of modules.
40		44
41	The created files do not need write access to the file system (like PAR	45	The created files do not need write access to the file system (like PAR
42	does). In fact, since this script is in many ways similar to PAR::Packer,	46	does). In fact, since this script is in many ways similar to PAR::Packer,
43	here are the differences:	47	here are the differences:
44		48
…		…
63	=item * The generated executables don't need a writable filesystem.	67	=item * The generated executables don't need a writable filesystem.
64		68
65	F<staticperl> loads all required files directly from memory. There is no	69	F<staticperl> loads all required files directly from memory. There is no
66	need to unpack files into a temporary directory.	70	need to unpack files into a temporary directory.
67		71
68	=item * More control over included files.	72	=item * More control over included files, more burden.
69		73
70	PAR tries to be maintenance and hassle-free - it tries to include more	74	PAR tries to be maintenance and hassle-free - it tries to include more
71	files than necessary to make sure everything works out of the box. The	75	files than necessary to make sure everything works out of the box. It
72	extra files (such as the unicode database) can take substantial amounts of	76	mostly succeeds at this, but he extra files (such as the unicode database)
73	memory and file size.	77	can take substantial amounts of memory and file size.
74		78
75	With F<staticperl>, the burden is mostly with the developer - only direct	79	With F<staticperl>, the burden is mostly with the developer - only direct
76	compile-time dependencies and L<AutoLoader> are handled automatically.	80	compile-time dependencies and L<AutoLoader> are handled automatically.
77	This means the modules to include often need to be tweaked manually.	81	This means the modules to include often need to be tweaked manually.
		82
		83	All this does not preclude more permissive modes to be implemented in
		84	the future, but right now, you have to resolve state hidden dependencies
		85	manually.
78		86
79	=item * PAR works out of the box, F<staticperl> does not.	87	=item * PAR works out of the box, F<staticperl> does not.
80		88
81	Maintaining your own custom perl build can be a pain in the ass, and while	89	Maintaining your own custom perl build can be a pain in the ass, and while
82	F<staticperl> tries to make this easy, it still requires a custom perl	90	F<staticperl> tries to make this easy, it still requires a custom perl
83	build and possibly fiddling with some modules. PAR is likely to produce	91	build and possibly fiddling with some modules. PAR is likely to produce
84	results faster.	92	results faster.
		93
		94	Ok, PAR never has worked for me out of the box, and for some people,
		95	F<staticperl> does work out of the box, as they don't count "fiddling with
		96	module use lists" against it, but nevertheless, F<staticperl> is certainly
		97	a bit more difficult to use.
85		98
86	=back	99	=back
87		100
88	=head1 HOW DOES IT WORK?	101	=head1 HOW DOES IT WORK?
89		102
…		…
184	command by specifying all the directories with modules in them that you	197	command by specifying all the directories with modules in them that you
185	want to have built.	198	want to have built.
186		199
187	=item F<staticperl clean>	200	=item F<staticperl clean>
188		201
189	Runs F<make distclean> in the perl source directory (and potentially	202	Deletes the perl source directory (and potentially cleans up other
190	cleans up other intermediate files). This can be used to clean up	203	intermediate files). This can be used to clean up files only needed for
191	intermediate files without removing the installed perl interpreter.	204	building perl, without removing the installed perl interpreter, or to
		205	force a re-build from scratch.
		206
		207	At the moment, it doesn't delete downloaded tarballs.
192		208
193	=item F<staticperl distclean>	209	=item F<staticperl distclean>
194		210
195	This wipes your complete F<~/.staticperl> directory. Be careful with this,	211	This wipes your complete F<~/.staticperl> directory. Be careful with this,
196	it nukes your perl download, perl sources, perl distribution and any	212	it nukes your perl download, perl sources, perl distribution and any
…		…
236	(required by L<AnyEvent::HTTPD>) implements various URI schemes as extra	252	(required by L<AnyEvent::HTTPD>) implements various URI schemes as extra
237	modules - since L<AnyEvent::HTTPD> only needs C<http> URIs, we only need	253	modules - since L<AnyEvent::HTTPD> only needs C<http> URIs, we only need
238	to include that module. I found out about these dependencies by carefully	254	to include that module. I found out about these dependencies by carefully
239	watching any error messages about missing modules...	255	watching any error messages about missing modules...
240		256
		257	Instead of building a new perl binary, you can also build a standalone
		258	application:
		259
		260	# build the app
		261	staticperl mkapp app --boot eg/httpd \
		262	-MAnyEvent::Impl::Perl -MAnyEvent::HTTPD -MURI::http
		263
		264	# run it
		265	./app
		266
241	=head3 OPTION PROCESSING	267	=head3 OPTION PROCESSING
242		268
243	All options can be given as arguments on the command line (typically	269	All options can be given as arguments on the command line (typically
244	using long (e.g. C<--verbose>) or short option (e.g. C<-v>) style). Since	270	using long (e.g. C<--verbose>) or short option (e.g. C<-v>) style). Since
245	specifying a lot of modules can make the command line very cumbersome,	271	specifying a lot of modules can make the command line very cumbersome,
…		…
287	is also a lot slower, so is best used for production builds. Note that	313	is also a lot slower, so is best used for production builds. Note that
288	this method doesn't optimise for raw file size, but for best compression	314	this method doesn't optimise for raw file size, but for best compression
289	(that means that the uncompressed file size is a bit larger, but the files	315	(that means that the uncompressed file size is a bit larger, but the files
290	compress better, e.g. with F<upx>).	316	compress better, e.g. with F<upx>).
291		317
		318	Last not least, if you need accurate line numbers in error messages,
292	Last not least, in the unlikely case where C<pod> is too slow, or some	319	or in the unlikely case where C<pod> is too slow, or some module gets
293	module gets mistreated, you can specify C<none> to not mangle included	320	mistreated, you can specify C<none> to not mangle included perl sources in
294	perl sources in any way.	321	any way.
295		322
296	=item --perl	323	=item --perl
297		324
298	After writing out the bundle files, try to link a new perl interpreter. It	325	After writing out the bundle files, try to link a new perl interpreter. It
299	will be called F<perl> and will be left in the current working	326	will be called F<perl> and will be left in the current working
…		…
302	This switch is automatically used when F<staticperl> is invoked with the	329	This switch is automatically used when F<staticperl> is invoked with the
303	C<mkperl> command (instead of C<mkbundle>):	330	C<mkperl> command (instead of C<mkbundle>):
304		331
305	# build a new ./perl with only common::sense in it - very small :)	332	# build a new ./perl with only common::sense in it - very small :)
306	staticperl mkperl -Mcommon::sense	333	staticperl mkperl -Mcommon::sense
		334
		335	=item --app name
		336
		337	After writing out the bundle files, try to link a new standalone
		338	program. It will be called C<name>, and the bundle files get removed after
		339	linking it.
		340
		341	The difference to the (mutually exclusive) C<--perl> option is that the
		342	binary created by this option will not try to act as a perl interpreter -
		343	instead it will simply initialise the perl interpreter, clean it up and
		344	exit.
		345
		346	This switch is automatically used when F<staticperl> is invoked with the
		347	C<mkapp> command (instead of C<mkbundle>):
		348
		349	To let it do something useful you I<must> add some boot code, e.g. with
		350	the C<--boot> option.
		351
		352	Example: create a standalone perl binary that will execute F<appfile> when
		353	it is started.
		354
		355	staticperl mkbundle --app myexe --boot appfile
307		356
308	=item --use module \| -Mmodule	357	=item --use module \| -Mmodule
309		358
310	Include the named module and all direct dependencies. This is done by	359	Include the named module and all direct dependencies. This is done by
311	C<require>'ing the module in a subprocess and tracing which other modules	360	C<require>'ing the module in a subprocess and tracing which other modules
…		…
382	# specification file	431	# specification file
383	add file1 myfiles/file1	432	add file1 myfiles/file1
384	add file2 myfiles/file2	433	add file2 myfiles/file2
385	add file3 myfiles/file3	434	add file3 myfiles/file3
386		435
		436	=item --binadd "file" \| --add "file alias"
		437
		438	Just like C<--add>, except that it treats the file as binary and adds it
		439	without any processing.
		440
		441	You should probably add a C</> prefix to avoid clashing with embedded
		442	perl files (whose paths do not start with C</>), and/or use a special
		443	directory, such as C</res/name>.
		444
		445	You can later get a copy of these files by calling C<staticperl::find
		446	"alias">.
		447
387	=item --static	448	=item --static
388		449
389	When C<--perl> is also given, link statically instead of dynamically. The	450	When C<--perl> is also given, link statically instead of dynamically. The
390	default is to link the new perl interpreter fully dynamic (that means all	451	default is to link the new perl interpreter fully dynamic (that means all
391	perl modules are linked statically, but all external libraries are still	452	perl modules are linked statically, but all external libraries are still
…		…
402	Any other argument is interpreted as a bundle specification file, which	463	Any other argument is interpreted as a bundle specification file, which
403	supports most long options (without extra quoting), one option per line.	464	supports most long options (without extra quoting), one option per line.
404		465
405	=back	466	=back
406		467
407	=head2 F<STATCPERL> CONFIGURATION AND HOOKS	468	=head2 F<STATICPERL> CONFIGURATION AND HOOKS
408		469
409	During (each) startup, F<staticperl> tries to source the following shell	470	During (each) startup, F<staticperl> tries to source the following shell
410	files in order:	471	files in order:
411		472
412	/etc/staticperlrc	473	/etc/staticperlrc
…		…
428	=item C<EMAIL>	489	=item C<EMAIL>
429		490
430	The e-mail address of the person who built this binary. Has no good	491	The e-mail address of the person who built this binary. Has no good
431	default, so should be specified by you.	492	default, so should be specified by you.
432		493
		494	=item C<CPAN>
		495
		496	The URL of the CPAN mirror to use (e.g. L<http://mirror.netcologne.de/cpan/>).
		497
		498	=item C<EXTRA_MODULES>
		499
		500	Additional modules installed during F<staticperl install>. Here you can
		501	set which modules you want have to installed from CPAN.
		502
		503	Example: I really really need EV, AnyEvent, Coro and AnyEvent::AIO.
		504
		505	EXTRA_MODULES="EV AnyEvent Coro AnyEvent::AIO"
		506
		507	Note that you can also use a C<postinstall> hook to achieve this, and
		508	more.
		509
433	=back	510	=back
434		511
435	=head4 Variables you might I<want> to override	512	=head4 Variables you might I<want> to override
436		513
437	=over 4	514	=over 4
438		515
		516	=item C<STATICPERL>
		517
		518	The directory where staticperl stores all its files
		519	(default: F<~/.staticperl>).
		520
		521	=item C<PERL_MM_USE_DEFAULT>, C<EV_EXTRA_DEFS>, ...
		522
		523	Usually set to C<1> to make modules "less inquisitive" during their
		524	installation, you can set any environment variable you want - some modules
		525	(such as L<Coro> or L<EV>) use environment variables for further tweaking.
		526
439	=item C<PERLVER>	527	=item C<PERL_VERSION>
440		528
441	The perl version to install - default is currently C<5.12.2>, but C<5.8.9>	529	The perl version to install - default is currently C<5.12.2>, but C<5.8.9>
442	is also a good choice (5.8.9 is much smaller than 5.12.2, while 5.10.1 is	530	is also a good choice (5.8.9 is much smaller than 5.12.2, while 5.10.1 is
443	about as big as 5.12.2).	531	about as big as 5.12.2).
444		532
445	=item C<CPAN>
446
447	The URL of the CPAN mirror to use (e.g. L<http://mirror.netcologne.de/cpan/>).
448
449	=item C<EXTRA_MODULES>
450
451	Additional modules installed during F<staticperl install>. Here you can
452	set which modules you want have to installed from CPAN.
453
454	Example: I really really need EV, AnyEvent, Coro and IO::AIO.
455
456	EXTRA_MODULES="EV AnyEvent Coro IO::AIO"
457
458	Note that you can also use a C<postinstall> hook to achieve this, and
459	more.
460
461	=item C<PERL_MM_USE_DEFAULT>, C<EV_EXTRA_DEFS>, ...
462
463	Usually set to C<1> to make modules "less inquisitive" during their
464	installation, you can set any environment variable you want - some modules
465	(such as L<Coro> or L<EV>) use environment variables for further tweaking.
466
467	=item C<STATICPERL>
468
469	The directory where staticperl stores all its files
470	(default: F<~/.staticperl>).
471
472	=item C<PREFIX>	533	=item C<PERL_PREFIX>
473		534
474	The prefix where perl gets installed (default: F<$STATICPERL/perl>),	535	The prefix where perl gets installed (default: F<$STATICPERL/perl>),
475	i.e. where the F<bin> and F<lib> subdirectories will end up.	536	i.e. where the F<bin> and F<lib> subdirectories will end up.
		537
		538	=item C<PERL_CONFIGURE>
		539
		540	Additional Configure options - these are simply passed to the perl
		541	Configure script. For example, if you wanted to enable dynamic loading,
		542	you could pass C<-Dusedl>. To enable ithreads (Why would you want that
		543	insanity? Don't! Use L<forks> instead!) you would pass C<-Duseithreads>
		544	and so on.
		545
		546	More commonly, you would either activate 64 bit integer support
		547	(C<-Duse64bitint>), or disable large files support (-Uuselargefiles), to
		548	reduce filesize further.
476		549
477	=item C<PERL_CPPFLAGS>, C<PERL_OPTIMIZE>, C<PERL_LDFLAGS>, C<PERL_LIBS>	550	=item C<PERL_CPPFLAGS>, C<PERL_OPTIMIZE>, C<PERL_LDFLAGS>, C<PERL_LIBS>
478		551
479	These flags are passed to perl's F<Configure> script, and are generally	552	These flags are passed to perl's F<Configure> script, and are generally
480	optimised for small size (at the cost of performance). Since they also	553	optimised for small size (at the cost of performance). Since they also
…		…
517	instcpan Anyevent::AIO AnyEvent::HTTPD	590	instcpan Anyevent::AIO AnyEvent::HTTPD
518	}	591	}
519		592
520	=over 4	593	=over 4
521		594
		595	=item preconfigure
		596
		597	Called just before running F<./Configur> in the perl source
		598	directory. Current working directory is the perl source directory.
		599
		600	This can be used to set any C<PERL_xxx> variables, which might be costly
		601	to compute.
		602
522	=item postconfigure	603	=item postconfigure
523		604
524	Called after configuring, but before building perl. Current working	605	Called after configuring, but before building perl. Current working
525	directory is the perl source directory.	606	directory is the perl source directory.
526		607
527	Could be used to tailor/patch config.sh (followed by F<./Configure -S>) or	608	Could be used to tailor/patch config.sh (followed by F<sh Configure -S>)
528	do any other modifications.	609	or do any other modifications.
529		610
530	=item postbuild	611	=item postbuild
531		612
532	Called after building, but before installing perl. Current working	613	Called after building, but before installing perl. Current working
533	directory is the perl source directory.	614	directory is the perl source directory.
…		…
548	The script must return with a zero exit status, or the installation will	629	The script must return with a zero exit status, or the installation will
549	fail.	630	fail.
550		631
551	=back	632	=back
552		633
		634	=head1 ANATOMY OF A BUNDLE
		635
		636	When not building a new perl binary, C<mkbundle> will leave a number of
		637	files in the current working directory, which can be used to embed a perl
		638	interpreter in your program.
		639
		640	Intimate knowledge of L<perlembed> and preferably some experience with
		641	embedding perl is highly recommended.
		642
		643	C<mkperl> (or the C<--perl> option) basically does this to link the new
		644	interpreter (it also adds a main program to F<bundle.>):
		645
		646	$Config{cc} $(cat bundle.ccopts) -o perl bundle.c $(cat bundle.ldopts)
		647
		648	=over 4
		649
		650	=item bundle.h
		651
		652	A header file that contains the prototypes of the few symbols "exported"
		653	by bundle.c, and also exposes the perl headers to the application.
		654
		655	=over 4
		656
		657	=item staticperl_init ()
		658
		659	Initialises the perl interpreter. You can use the normal perl functions
		660	after calling this function, for example, to define extra functions or
		661	to load a .pm file that contains some initialisation code, or the main
		662	program function:
		663
		664	XS (xsfunction)
		665	{
		666	dXSARGS;
		667
		668	// now we have items, ST(i) etc.
		669	}
		670
		671	static void
		672	run_myapp(void)
		673	{
		674	staticperl_init ();
		675	newXSproto ("myapp::xsfunction", xsfunction, __FILE__, "$$;$");
		676	eval_pv ("require myapp::main", 1); // executes "myapp/main.pm"
		677	}
		678
		679	=item staticperl_xs_init (pTHX)
		680
		681	Sometimes you need direct control over C<perl_parse> and C<perl_run>, in
		682	which case you do not want to use C<staticperl_init> but call them on your
		683	own.
		684
		685	Then you need this function - either pass it directly as the C<xs_init>
		686	function to C<perl_parse>, or call it from your own C<xs_init> function.
		687
		688	=item staticperl_cleanup ()
		689
		690	In the unlikely case that you want to destroy the perl interpreter, here
		691	is the corresponding function.
		692
		693	=item PerlInterpreter *staticperl
		694
		695	The perl interpreter pointer used by staticperl. Not normally so useful,
		696	but there it is.
		697
		698	=back
		699
		700	=item bundle.ccopts
		701
		702	Contains the compiler options required to compile at least F<bundle.c> and
		703	any file that includes F<bundle.h> - you should probably use it in your
		704	C<CFLAGS>.
		705
		706	=item bundle.ldopts
		707
		708	The linker options needed to link the final program.
		709
		710	=back
		711
		712	=head1 RUNTIME FUNCTIONALITY
		713
		714	Binaries created with C<mkbundle>/C<mkperl> contain extra functions, which
		715	are required to access the bundled perl sources, but might be useful for
		716	other purposes.
		717
		718	In addition, for the embedded loading of perl files to work, F<staticperl>
		719	overrides the C<@INC> array.
		720
		721	=over 4
		722
		723	=item $file = staticperl::find $path
		724
		725	Returns the data associated with the given C<$path>
		726	(e.g. C<Digest/MD5.pm>, C<auto/POSIX/autosplit.ix>), which is basically
		727	the UNIX path relative to the perl library directory.
		728
		729	Returns C<undef> if the file isn't embedded.
		730
		731	=item @paths = staticperl::list
		732
		733	Returns the list of all paths embedded in this binary.
		734
		735	=back
		736
		737	=head1 FULLY STATIC BINARIES - BUILDROOT
		738
		739	To make truly static (Linux-) libraries, you might want to have a look at
		740	buildroot (L<http://buildroot.uclibc.org/>).
		741
		742	Buildroot is primarily meant to set up a cross-compile environment (which
		743	is not so useful as perl doesn't quite like cross compiles), but it can also compile
		744	a chroot environment where you can use F<staticperl>.
		745
		746	To do so, download buildroot, and enable "Build options => development
		747	files in target filesystem" and optionally "Build options => gcc
		748	optimization level (optimize for size)". At the time of writing, I had
		749	good experiences with GCC 4.4.x but not GCC 4.5.
		750
		751	To minimise code size, I used C<-pipe -ffunction-sections -fdata-sections
		752	-finline-limit=8 -fno-builtin-strlen -mtune=i386>. The C<-mtune=i386>
		753	doesn't decrease codesize much, but it makes the file much more
		754	compressible.
		755
		756	If you don't need Coro or threads, you can go with "linuxthreads.old" (or
		757	no thread support). For Coro, it is highly recommended to switch to a
		758	uClibc newer than 0.9.31 (at the time of this writing, I used the 20101201
		759	snapshot) and enable NPTL, otherwise Coro needs to be configured with the
		760	ultra-slow pthreads backend to work around linuxthreads bugs (it also uses
		761	twice the address space needed for stacks).
		762
		763	If you use C<linuxthreads.old>, then you should also be aware that
		764	uClibc shares C<errno> between all threads when statically linking. See
		765	L<http://lists.uclibc.org/pipermail/uclibc/2010-June/044157.html> for a
		766	workaround (And L<https://bugs.uclibc.org/2089> for discussion).
		767
		768	C<ccache> support is also recommended, especially if you want
		769	to play around with buildroot options. Enabling the C<miniperl>
		770	package will probably enable all options required for a successful
		771	perl build. F<staticperl> itself additionally needs either C<wget>
		772	(recommended, for CPAN) or C<curl>.
		773
		774	As for shells, busybox should provide all that is needed, but the default
		775	busybox configuration doesn't include F<comm> which is needed by perl -
		776	either make a custom busybox config, or compile coreutils.
		777
		778	For the latter route, you might find that bash has some bugs that keep
		779	it from working properly in a chroot - either use dash (and link it to
		780	F</bin/sh> inside the chroot) or link busybox to F</bin/sh>, using it's
		781	built-in ash shell.
		782
		783	Finally, you need F</dev/null> inside the chroot for many scripts to work
		784	- F<cp /dev/null output/target/dev> or bind-mounting your F</dev> will
		785	both provide this.
		786
		787	After you have compiled and set up your buildroot target, you can copy
		788	F<staticperl> from the C<App::Staticperl> distribution or from your
		789	perl f<bin> directory (if you installed it) into the F<output/target>
		790	filesystem, chroot inside and run it.
		791
		792	=head1 RECIPES / SPECIFIC MODULES
		793
		794	This section contains some common(?) recipes and information about
		795	problems with some common modules or perl constructs that require extra
		796	files to be included.
		797
		798	=head2 MODULES
		799
		800	=over 4
		801
		802	=item utf8
		803
		804	Some functionality in the utf8 module, such as swash handling (used
		805	for unicode character ranges in regexes) is implemented in the
		806	C<"utf8_heavy.pl"> library.
		807
		808	Many Unicode properties in turn are defined in separate modules,
		809	such as C<"unicore/Heavy.pl"> and more specific data tables such as
		810	C<"unicore/To/Digit.pl"> or C<"unicore/lib/Perl/Word.pl">. These
		811	tables are big (7MB uncompressed), so including them on demand by your
		812	applciation only might pay off.
		813
		814	=item Carp
		815
		816	Carp had (in older versions of perl) a dependency on L<Carp::Heavy>. As of
		817	perl 5.12.2 (maybe earlier), this dependency no longer exists.
		818
		819	=item Config
		820
		821	The F<perl -V> switch (as well as many modules) needs L<Config>, which in
		822	turn might need L<"Config_heavy.pl">. Including the latter gives you
		823	both.
		824
		825	=item AnyEvent
		826
		827	AnyEvent needs a backend implementation that it will load in a delayed
		828	fashion. The L<AnyEvent::Impl::Perl> backend is the default choice
		829	for AnyEvent if it can't find anything else, and is usually a safe
		830	fallback. If you plan to use e.g. L<EV> (L<POE>...), then you need to
		831	include the L<AnyEvent::Impl::EV> (L<AnyEvent::Impl::POE>...) backend as
		832	well.
		833
		834	If you want to handle IRIs or IDNs (L<AnyEvent::Util> punycode and idn
		835	functions), you also need to include C<"AnyEvent/Util/idna.pl"> and
		836	C<"AnyEvent/Util/uts46data.pl">.
		837
		838	=item URI
		839
		840	URI implements schemes as separate modules - the generic URL scheme is
		841	implemented in L<URI::_generic>, HTTP is implemented in L<URI::http>. If
		842	you need to use any of these schemes, you should include these manually.
		843
		844	=back
		845
		846	=head2 RECIPES
		847
		848	=over 4
		849
		850	=item Getting rid of netdb function
		851
		852	The perl core has lots of netdb functions (C<getnetbyname>, C<getgrent>
		853	and so on) that few applications use. You can avoid compiling them in by
		854	putting the following fragment into a C<preconfigure> hook:
		855
		856	preconfigure() {
		857	for sym in \
		858	d_getgrnam_r d_endgrent d_endgrent_r d_endhent \
		859	d_endhostent_r d_endnent d_endnetent_r d_endpent \
		860	d_endprotoent_r d_endpwent d_endpwent_r d_endsent \
		861	d_endservent_r d_getgrent d_getgrent_r d_getgrgid_r \
		862	d_getgrnam_r d_gethbyaddr d_gethent d_getsbyport \
		863	d_gethostbyaddr_r d_gethostbyname_r d_gethostent_r \
		864	d_getlogin_r d_getnbyaddr d_getnbyname d_getnent \
		865	d_getnetbyaddr_r d_getnetbyname_r d_getnetent_r \
		866	d_getpent d_getpbyname d_getpbynumber d_getprotobyname_r \
		867	d_getprotobynumber_r d_getprotoent_r d_getpwent \
		868	d_getpwent_r d_getpwnam_r d_getpwuid_r d_getsent \
		869	d_getservbyname_r d_getservbyport_r d_getservent_r \
		870	d_getspnam_r d_getsbyname
		871	# d_gethbyname
		872	do
		873	PERL_CONFIGURE="$PERL_CONFIGURE -U$sym"
		874	done
		875	}
		876
		877	This mostly gains space when linking staticaly, as the functions will
		878	liekly not be linked in. The gain for dynamically-linked binaries is
		879	smaller.
		880
		881	Also, this leaves C<gethostbyname> in - not only is it actually used
		882	often, the L<Socket> module also exposes it, so leaving it out usually
		883	gains little. Why Socket exposes a C function that is in the core already
		884	is anybody's guess.
		885
		886	=back
		887
553	=head1 AUTHOR	888	=head1 AUTHOR
554		889
555	Marc Lehmann <schmorp@schmorp.de>	890	Marc Lehmann <schmorp@schmorp.de>
556	http://software.schmorp.de/pkg/staticperl.html	891	http://software.schmorp.de/pkg/staticperl.html

Diff Legend

-–
+Removed lines
-+
+Added lines
-<
+Changed lines
->
+Changed lines

Comparing App-Staticperl/staticperl.pod (file contents): Revision 1.7 by root, Mon Dec 6 21:21:44 2010 UTC vs. Revision 1.17 by root, Thu Dec 9 08:55:52 2010 UTC

Diff Legend

Comparing App-Staticperl/staticperl.pod (file contents):
Revision 1.7 by root, Mon Dec 6 21:21:44 2010 UTC vs.
Revision 1.17 by root, Thu Dec 9 08:55:52 2010 UTC