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

Comparing App-Staticperl/staticperl.pod (file contents):
Revision 1.15 by root, Wed Dec 8 23:01:30 2010 UTC vs.
Revision 1.17 by root, Thu Dec 9 08:55:52 2010 UTC

…		…
28	staticperl mkapp myapp --boot mainprog mymodules	28	staticperl mkapp myapp --boot mainprog mymodules
29	# build a binary "myapp" from mainprog and mymodules	29	# build a binary "myapp" from mainprog and mymodules
30		30
31	=head1 DESCRIPTION	31	=head1 DESCRIPTION
32		32
33	This script helps you creating single-file perl interpreters, or embedding	33	This script helps you to create single-file perl interpreters
34	a perl interpreter in your applications. Single-file means that it is	34	or applications, or embedding a perl interpreter in your
35	fully self-contained - no separate shared objects, no autoload fragments,	35	applications. Single-file means that it is fully self-contained - no
36	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
37	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
38	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.
39		40
40	With F<uClibc> and F<upx> on x86, you can create a single 500kb binary	41	With F<uClibc> and F<upx> on x86, you can create a single 500kb binary
41	that contains perl and 100 modules such as POSIX, AnyEvent, EV, IO::AIO,	42	that contains perl and 100 modules such as POSIX, AnyEvent, EV, IO::AIO,
42	Coro and so on. Or any other choice of modules.	43	Coro and so on. Or any other choice of modules.
43		44
…		…
66	=item * The generated executables don't need a writable filesystem.	67	=item * The generated executables don't need a writable filesystem.
67		68
68	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
69	need to unpack files into a temporary directory.	70	need to unpack files into a temporary directory.
70		71
71	=item * More control over included files.	72	=item * More control over included files, more burden.
72		73
73	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
74	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
75	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)
76	memory and file size.	77	can take substantial amounts of memory and file size.
77		78
78	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
79	compile-time dependencies and L<AutoLoader> are handled automatically.	80	compile-time dependencies and L<AutoLoader> are handled automatically.
80	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.
81		86
82	=item * PAR works out of the box, F<staticperl> does not.	87	=item * PAR works out of the box, F<staticperl> does not.
83		88
84	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
85	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
…		…
782	After you have compiled and set up your buildroot target, you can copy	787	After you have compiled and set up your buildroot target, you can copy
783	F<staticperl> from the C<App::Staticperl> distribution or from your	788	F<staticperl> from the C<App::Staticperl> distribution or from your
784	perl f<bin> directory (if you installed it) into the F<output/target>	789	perl f<bin> directory (if you installed it) into the F<output/target>
785	filesystem, chroot inside and run it.	790	filesystem, chroot inside and run it.
786		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
787	=head1 AUTHOR	888	=head1 AUTHOR
788		889
789	Marc Lehmann <schmorp@schmorp.de>	890	Marc Lehmann <schmorp@schmorp.de>
790	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.15 by root, Wed Dec 8 23:01:30 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.15 by root, Wed Dec 8 23:01:30 2010 UTC vs.
Revision 1.17 by root, Thu Dec 9 08:55:52 2010 UTC