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

Comparing App-Staticperl/staticperl.pod (file contents):
Revision 1.1 by root, Mon Dec 6 19:33:57 2010 UTC vs.
Revision 1.9 by root, Tue Dec 7 09:08:06 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
26	# build a perl with the above modules linked in	26	# build a perl with the above modules linked in
27		27
28	=head1 DESCRIPTION	28	=head1 DESCRIPTION
29		29
30	This script helps you creating single-file perl interpreters, or embedding	30	This script helps you creating single-file perl interpreters, or embedding
31	a pelr interpreter in your apps. Single-file means that it is fully	31	a perl interpreter in your applications. Single-file means that it is
32	self-contained - no separate shared objects, no autoload fragments, no .pm	32	fully self-contained - no separate shared objects, no autoload fragments,
33	or .pl files are needed. And when linking statically, you can create (or	33	no .pm or .pl files are needed. And when linking statically, you can
34	embed) a single file that contains perl interpreter, libc, all the modules	34	create (or embed) a single file that contains perl interpreter, libc, all
35	you need and all the libraries you need.	35	the modules you need and all the libraries you need.
36		36
37	With uclibc and upx on x86, you can create a single 500kb binary that	37	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	38	that contains perl and 100 modules such as POSIX, AnyEvent, EV, IO::AIO,
39	on. Or any other choice of modules.	39	Coro and so on. Or any other choice of modules.
40		40
41	The created files do not need write access to the filesystem (like PAR	41	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,	42	does). In fact, since this script is in many ways similar to PAR::Packer,
43	here are the differences:	43	here are the differences:
44		44
45	=over 4	45	=over 4
46		46
…		…
65	F<staticperl> loads all required files directly from memory. There is no	65	F<staticperl> loads all required files directly from memory. There is no
66	need to unpack files into a temporary directory.	66	need to unpack files into a temporary directory.
67		67
68	=item * More control over included files.	68	=item * More control over included files.
69		69
70	PAR tries to be maintainance and hassle-free - it tries to include more files	70	PAR tries to be maintenance and hassle-free - it tries to include more
71	than necessary to make sure everything works out of the box. The extra files	71	files than necessary to make sure everything works out of the box. The
72	(such as the unicode database) can take substantial amounts of memory and filesize.	72	extra files (such as the unicode database) can take substantial amounts of
		73	memory and file size.
73		74
74	With F<staticperl>, the burden is mostly with the developer - only direct	75	With F<staticperl>, the burden is mostly with the developer - only direct
75	compile-time dependencies and L<AutoLoader> are handled automatically.	76	compile-time dependencies and L<AutoLoader> are handled automatically.
76	This means the modules to include often need to be tweaked manually.	77	This means the modules to include often need to be tweaked manually.
77		78
…		…
88		89
89	Simple: F<staticperl> downloads, compile and installs a perl version of	90	Simple: F<staticperl> downloads, compile and installs a perl version of
90	your choice in F<~/.staticperl>. You can add extra modules either by	91	your choice in F<~/.staticperl>. You can add extra modules either by
91	letting F<staticperl> install them for you automatically, or by using CPAN	92	letting F<staticperl> install them for you automatically, or by using CPAN
92	and doing it interactively. This usually takes 5-10 minutes, depending on	93	and doing it interactively. This usually takes 5-10 minutes, depending on
93	the speed of your computer and your internet conenction.	94	the speed of your computer and your internet connection.
94		95
95	It is possible to do program development at this stage, too.	96	It is possible to do program development at this stage, too.
96		97
97	Afterwards, you create a list of files and modules you want to include,	98	Afterwards, you create a list of files and modules you want to include,
98	and then either build a new perl binary (that acts just like a normla perl	99	and then either build a new perl binary (that acts just like a normal perl
99	except everything is compiled in), or you create bundle files (basically C	100	except everything is compiled in), or you create bundle files (basically C
100	sources you can use to embed all files into your project).	101	sources you can use to embed all files into your project).
101		102
102	This step is very fast (a few seconds if PPI is not used for stripping,	103	This step is very fast (a few seconds if PPI is not used for stripping,
103	more seconds otherwise, as PPI is very slow), and can be tweaked and	104	more seconds otherwise, as PPI is very slow), and can be tweaked and
…		…
134	perl interpreter if required.	135	perl interpreter if required.
135		136
136	Most of the following commands simply run one or more steps of this	137	Most of the following commands simply run one or more steps of this
137	sequence.	138	sequence.
138		139
139	To force recompilation or reinstalaltion, you need to run F<staticperl	140	To force recompilation or reinstallation, you need to run F<staticperl
140	distclean> first.	141	distclean> first.
141		142
142	=over 4	143	=over 4
143		144
144	=item F<staticperl fetch>	145	=item F<staticperl fetch>
…		…
154	Builds the configured perl sources, potentially after automatically	155	Builds the configured perl sources, potentially after automatically
155	configuring them.	156	configuring them.
156		157
157	=item F<staticperl install>	158	=item F<staticperl install>
158		159
159	Wipes the perl installation directory (usually F<~/.staticperl/perl>) and installs	160	Wipes the perl installation directory (usually F<~/.staticperl/perl>) and
160	the perl distribution, potentially aftering building it first.	161	installs the perl distribution, potentially after building it first.
161		162
162	=item F<staticperl cpan> [args...]	163	=item F<staticperl cpan> [args...]
163		164
164	Starts an interactive CPAN shell that you cna use to install further	165	Starts an interactive CPAN shell that you can use to install further
165	modules. Installs the perl first if neccessary, but apart from that,	166	modules. Installs the perl first if necessary, but apart from that,
166	no magic is involved: you could just as well run it manually via	167	no magic is involved: you could just as well run it manually via
167	F<~/.staticperl/perl/bin/cpan>.	168	F<~/.staticperl/perl/bin/cpan>.
168		169
169	Any additional arguments are simply passed to the F<cpan> command.	170	Any additional arguments are simply passed to the F<cpan> command.
170		171
…		…
177	staticperl instcpan EV AnyEvent::HTTPD Coro	178	staticperl instcpan EV AnyEvent::HTTPD Coro
178		179
179	=item F<staticperl instsrc> directory...	180	=item F<staticperl instsrc> directory...
180		181
181	In the unlikely case that you have unpacked perl modules around and want	182	In the unlikely case that you have unpacked perl modules around and want
182	to install from these instead of from CPAN, you cna do this using this	183	to install from these instead of from CPAN, you can do this using this
183	command by specifying all the directories with modules in them that you	184	command by specifying all the directories with modules in them that you
184	want to have built.	185	want to have built.
185		186
186	=item F<staticperl clean>	187	=item F<staticperl clean>
187		188
…		…
206	with any arguments you pass:	207	with any arguments you pass:
207		208
208	staticperl mkbundle mkbundle-args...	209	staticperl mkbundle mkbundle-args...
209		210
210	In the oh so unlikely case of something not working here, you	211	In the oh so unlikely case of something not working here, you
211	cna run the script manually as well (by default it is written to	212	can run the script manually as well (by default it is written to
212	F<~/.staticperl/mkbundle>).	213	F<~/.staticperl/mkbundle>).
213		214
214	F<mkbundle> is a more conventional command and expect the argument	215	F<mkbundle> is a more conventional command and expect the argument
215	syntax commonly used on unix clones. For example, this command builds	216	syntax commonly used on UNIX clones. For example, this command builds
216	a new F<perl> binary and includes F<Config.pm> (for F<perl -V>),	217	a new F<perl> binary and includes F<Config.pm> (for F<perl -V>),
217	F<AnyEvent::HTTPD>, F<URI> and a custom F<httpd> script (from F<eg/httpd>	218	F<AnyEvent::HTTPD>, F<URI> and a custom F<httpd> script (from F<eg/httpd>
218	in this distribution):	219	in this distribution):
219		220
220	# first make sure we have perl and the required modules	221	# first make sure we have perl and the required modules
…		…
229	./perl -Mhttpd	230	./perl -Mhttpd
230		231
231	As you can see, things are not quite as trivial: the L<Config> module has	232	As you can see, things are not quite as trivial: the L<Config> module has
232	a hidden dependency which is not even a perl module (F<Config_heavy.pl>),	233	a hidden dependency which is not even a perl module (F<Config_heavy.pl>),
233	L<AnyEvent> needs at least one event loop backend that we have to	234	L<AnyEvent> needs at least one event loop backend that we have to
234	specifymanually (here L<AnyEvent::Impl::Perl>), and the F<URI> module	235	specify manually (here L<AnyEvent::Impl::Perl>), and the F<URI> module
235	(required by L<AnyEvent::HTTPD>) implements various URI schemes as extra	236	(required by L<AnyEvent::HTTPD>) implements various URI schemes as extra
236	modules - since L<AnyEvent::HTTPD> only needs C<http> URIs, we only need	237	modules - since L<AnyEvent::HTTPD> only needs C<http> URIs, we only need
237	to include that module.	238	to include that module. I found out about these dependencies by carefully
		239	watching any error messages about missing modules...
238		240
239	=head3 OPTION PROCESSING	241	=head3 OPTION PROCESSING
240		242
241	All options can be given as arguments on the commandline (typically using	243	All options can be given as arguments on the command line (typically
242	long (e.g. C<--verbose>) or short option (e.g. C<-v>) style). Since	244	using long (e.g. C<--verbose>) or short option (e.g. C<-v>) style). Since
243	specifying a lot of modules can make the commandlien very cumbersome,	245	specifying a lot of modules can make the command line very cumbersome,
244	you can put all long options into a "bundle specification file" (with or	246	you can put all long options into a "bundle specification file" (with or
245	without C<--> prefix) and specify this bundle file instead.	247	without C<--> prefix) and specify this bundle file instead.
246		248
247	For example, the command given earlier could also look like this:	249	For example, the command given earlier could also look like this:
248		250
…		…
254	use AnyEvent::Impl::Perl	256	use AnyEvent::Impl::Perl
255	use AnyEvent::HTTPD	257	use AnyEvent::HTTPD
256	use URI::http	258	use URI::http
257	add eg/httpd httpd.pm	259	add eg/httpd httpd.pm
258		260
		261	All options that specify modules or files to be added are processed in the
		262	order given on the command line (that affects the C<--use> and C<--eval>
		263	options at the moment).
		264
259	=head3 MKBUNDLE OPTIONS	265	=head3 MKBUNDLE OPTIONS
260		266
261	=over 4	267	=over 4
262		268
263	"strip=s" => \$STRIP,	269	=item --verbose \| -v
264	"verbose\|v" => sub { ++$VERBOSE },	270
265	"quiet\|q" => sub { --$VERBOSE },	271	Increases the verbosity level by one (the default is C<1>).
266	"perl" => \$PERL,	272
267	"eval=s" => sub { trace_eval $_[1] },	273	=item --quiet \| -q
268	"use\|M=s" => sub { trace_module $_[1] },	274
269	"boot=s" => sub { cmd_boot $_[1] },	275	Decreases the verbosity level by one.
270	"add=s" => sub { cmd_add $_[1] },	276
271	"static" => sub { $STATIC = 1 },	277	=item --strip none\|pod\|ppi
272	"<>" => sub { cmd_file $_[1] },	278
		279	Specify the stripping method applied to reduce the file of the perl
		280	sources included.
		281
		282	The default is C<pod>, which uses the L<Pod::Strip> module to remove all
		283	pod documentation, which is very fast and reduces file size a lot.
		284
		285	The C<ppi> method uses L<PPI> to parse and condense the perl sources. This
		286	saves a lot more than just L<Pod::Strip>, and is generally safer, but
		287	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
		289	(that means that the uncompressed file size is a bit larger, but the files
		290	compress better, e.g. with F<upx>).
		291
		292	Last not least, if you need accurate line numbers in error messages,
		293	or in the unlikely case where C<pod> is too slow, or some module gets
		294	mistreated, you can specify C<none> to not mangle included perl sources in
		295	any way.
		296
		297	=item --perl
		298
		299	After writing out the bundle files, try to link a new perl interpreter. It
		300	will be called F<perl> and will be left in the current working
		301	directory. The bundle files will be removed.
		302
		303	This switch is automatically used when F<staticperl> is invoked with the
		304	C<mkperl> command (instead of C<mkbundle>):
		305
		306	# build a new ./perl with only common::sense in it - very small :)
		307	staticperl mkperl -Mcommon::sense
		308
		309	=item --use module \| -Mmodule
		310
		311	Include the named module and all direct dependencies. This is done by
		312	C<require>'ing the module in a subprocess and tracing which other modules
		313	and files it actually loads. If the module uses L<AutoLoader>, then all
		314	splitfiles will be included as well.
		315
		316	Example: include AnyEvent and AnyEvent::Impl::Perl.
		317
		318	staticperl mkbundle --use AnyEvent --use AnyEvent::Impl::Perl
		319
		320	Sometimes you want to load old-style "perl libraries" (F<.pl> files), or
		321	maybe other weirdly named files. To do that, you need to quote the name in
		322	single or double quotes. When given on the command line, you probably need
		323	to quote once more to avoid your shell interpreting it. Common cases that
		324	need this are F<Config_heavy.pl> and F<utf8_heavy.pl>.
		325
		326	Example: include the required files for F<perl -V> to work in all its
		327	glory (F<Config.pm> is included automatically by this).
		328
		329	# bourne shell
		330	staticperl mkbundle --use '"Config_heavy.pl"'
		331
		332	# bundle specification file
		333	use "Config_heavy.pl"
		334
		335	The C<-Mmodule> syntax is included as an alias that might be easier to
		336	remember than C<use>. Or maybe it confuses people. Time will tell. Or
		337	maybe not. Argh.
		338
		339	=item --eval "perl code" \| -e "perl code"
		340
		341	Sometimes it is easier (or necessary) to specify dependencies using perl
		342	code, or maybe one of the modules you use need a special use statement. In
		343	that case, you can use C<eval> to execute some perl snippet or set some
		344	variables or whatever you need. All files C<require>'d or C<use>'d in the
		345	script are included in the final bundle.
		346
		347	Keep in mind that F<mkbundle> will only C<require> the modules named
		348	by the C<--use> option, so do not expect the symbols from modules you
		349	C<--use>'d earlier on the command line to be available.
		350
		351	Example: force L<AnyEvent> to detect a backend and therefore include it
		352	in the final bundle.
		353
		354	staticperl mkbundle --eval 'use AnyEvent; AnyEvent::detect'
		355
		356	# or like this
		357	staticperl mkbundle -MAnyEvent --eval 'use AnyEvent; AnyEvent::detect'
		358
		359	Example: use a separate "bootstrap" script that C<use>'s lots of modules
		360	and include this in the final bundle, to be executed automatically.
		361
		362	staticperl mkbundle --eval 'do "bootstrap"' --boot bootstrap
		363
		364	=item --boot filename
		365
		366	Include the given file in the bundle and arrange for it to be executed
		367	(using a C<require>) before anything else when the new perl is
		368	initialised. This can be used to modify C<@INC> or anything else before
		369	the perl interpreter executes scripts given on the command line (or via
		370	C<-e>). This works even in an embedded interpreter.
		371
		372	=item --add "file" \| --add "file alias"
		373
		374	Adds the given (perl) file into the bundle (and optionally call it
		375	"alias"). This is useful to include any custom files into the bundle.
		376
		377	Example: embed the file F<httpd> as F<httpd.pm> when creating the bundle.
		378
		379	staticperl mkperl --add "httpd httpd.pm"
		380
		381	It is also a great way to add any custom modules:
		382
		383	# specification file
		384	add file1 myfiles/file1
		385	add file2 myfiles/file2
		386	add file3 myfiles/file3
		387
		388	=item --static
		389
		390	When C<--perl> is also given, link statically instead of dynamically. The
		391	default is to link the new perl interpreter fully dynamic (that means all
		392	perl modules are linked statically, but all external libraries are still
		393	referenced dynamically).
		394
		395	Keep in mind that Solaris doesn't support static linking at all, and
		396	systems based on GNU libc don't really support it in a usable fashion
		397	either. Try uClibc if you want to create fully statically linked
		398	executables, or try the C<--staticlibs> option to link only some libraries
		399	statically.
		400
		401	=item any other argument
		402
		403	Any other argument is interpreted as a bundle specification file, which
		404	supports most long options (without extra quoting), one option per line.
273		405
274	=back	406	=back
275		407
276	=head2 F<STATCPERL> CONFIGURATION AND HOOKS	408	=head2 F<STATCPERL> CONFIGURATION AND HOOKS
277		409
278	#TODO	410	During (each) startup, F<staticperl> tries to source the following shell
		411	files in order:
		412
		413	/etc/staticperlrc
		414	~/.staticperlrc
		415	$STATICPERL/rc
		416
		417	They can be used to override shell variables, or define functions to be
		418	called at specific phases.
		419
		420	Note that the last file is erased during F<staticperl distclean>, so
		421	generally should not be used.
		422
		423	=head3 CONFIGURATION VARIABLES
		424
		425	=head4 Variables you I<should> override
		426
		427	=over 4
		428
		429	=item C<EMAIL>
		430
		431	The e-mail address of the person who built this binary. Has no good
		432	default, so should be specified by you.
		433
		434	=back
		435
		436	=head4 Variables you might I<want> to override
		437
		438	=over 4
		439
		440	=item C<PERLVER>
		441
		442	The perl version to install - default is currently C<5.12.2>, but C<5.8.9>
		443	is also a good choice (5.8.9 is much smaller than 5.12.2, while 5.10.1 is
		444	about as big as 5.12.2).
		445
		446	=item C<CPAN>
		447
		448	The URL of the CPAN mirror to use (e.g. L<http://mirror.netcologne.de/cpan/>).
		449
		450	=item C<EXTRA_MODULES>
		451
		452	Additional modules installed during F<staticperl install>. Here you can
		453	set which modules you want have to installed from CPAN.
		454
		455	Example: I really really need EV, AnyEvent, Coro and IO::AIO.
		456
		457	EXTRA_MODULES="EV AnyEvent Coro IO::AIO"
		458
		459	Note that you can also use a C<postinstall> hook to achieve this, and
		460	more.
		461
		462	=item C<PERL_MM_USE_DEFAULT>, C<EV_EXTRA_DEFS>, ...
		463
		464	Usually set to C<1> to make modules "less inquisitive" during their
		465	installation, you can set any environment variable you want - some modules
		466	(such as L<Coro> or L<EV>) use environment variables for further tweaking.
		467
		468	=item C<STATICPERL>
		469
		470	The directory where staticperl stores all its files
		471	(default: F<~/.staticperl>).
		472
		473	=item C<PREFIX>
		474
		475	The prefix where perl gets installed (default: F<$STATICPERL/perl>),
		476	i.e. where the F<bin> and F<lib> subdirectories will end up.
		477
		478	=item C<PERL_CPPFLAGS>, C<PERL_OPTIMIZE>, C<PERL_LDFLAGS>, C<PERL_LIBS>
		479
		480	These flags are passed to perl's F<Configure> script, and are generally
		481	optimised for small size (at the cost of performance). Since they also
		482	contain subtle workarounds around various build issues, changing these
		483	usually requires understanding their default values - best look at the top
		484	of the F<staticperl> script for more info on these.
		485
		486	=back
		487
		488	=head4 Variables you probably I<do not want> to override
		489
		490	=over 4
		491
		492	=item C<MKBUNDLE>
		493
		494	Where F<staticperl> writes the C<mkbundle> command to
		495	(default: F<$STATICPERL/mkbundle>).
		496
		497	=item C<STATICPERL_MODULES>
		498
		499	Additional modules needed by C<mkbundle> - should therefore not be changed
		500	unless you know what you are doing.
		501
		502	=back
		503
		504	=head3 OVERRIDABLE HOOKS
		505
		506	In addition to environment variables, it is possible to provide some
		507	shell functions that are called at specific times. To provide your own
		508	commands, just define the corresponding function.
		509
		510	Example: install extra modules from CPAN and from some directories
		511	at F<staticperl install> time.
		512
		513	postinstall() {
		514	rm -rf lib/threads* # weg mit Schaden
		515	instcpan IO::AIO EV
		516	instsrc ~/src/AnyEvent
		517	instsrc ~/src/XML-Sablotron-1.0100001
		518	instcpan Anyevent::AIO AnyEvent::HTTPD
		519	}
		520
		521	=over 4
		522
		523	=item postconfigure
		524
		525	Called after configuring, but before building perl. Current working
		526	directory is the perl source directory.
		527
		528	Could be used to tailor/patch config.sh (followed by F<./Configure -S>) or
		529	do any other modifications.
		530
		531	=item postbuild
		532
		533	Called after building, but before installing perl. Current working
		534	directory is the perl source directory.
		535
		536	I have no clue what this could be used for - tell me.
		537
		538	=item postinstall
		539
		540	Called after perl and any extra modules have been installed in C<$PREFIX>,
		541	but before setting the "installation O.K." flag.
		542
		543	The current working directory is C<$PREFIX>, but maybe you should not rely
		544	on that.
		545
		546	This hook is most useful to customise the installation, by deleting files,
		547	or installing extra modules using the C<instcpan> or C<instsrc> functions.
		548
		549	The script must return with a zero exit status, or the installation will
		550	fail.
		551
		552	=back
		553
		554	=head1 ANATOMY OF A BUNDLE
		555
		556	When not building a new perl binary, C<mkbundle> will leave a number of
		557	files in the current working directory, which can be used to embed a perl
		558	interpreter in your program.
		559
		560	Intimate knowledge of L<perlembed> and preferably some experience with
		561	embedding perl is highly recommended.
		562
		563	C<mkperl> (or the C<--perl> option) basically does this to link the new
		564	interpreter (it also adds a main program to F<bundle.>):
		565
		566	$Config{cc} $(cat bundle.ccopts) -o perl bundle.c $(cat bundle.ldopts)
		567
		568	=over 4
		569
		570	=item bundle.h
		571
		572	A header file that contains the prototypes of the few symbols "exported"
		573	by bundle.c, and also exposes the perl headers to the application.
		574
		575	=over 4
		576
		577	=item staticperl_init ()
		578
		579	Initialises the perl interpreter. You can use the normal perl functions
		580	after calling this function, for example, to define extra functions or
		581	to load a .pm file that contains some initialisation code, or the main
		582	program function:
		583
		584	XS (xsfunction)
		585	{
		586	dXSARGS;
		587
		588	// now we have items, ST(i) etc.
		589	}
		590
		591	static void
		592	run_myapp(void)
		593	{
		594	staticperl_init ();
		595	newXSproto ("myapp::xsfunction", xsfunction, __FILE__, "$$;$");
		596	eval_pv ("require myapp::main", 1); // executes "myapp/main.pm"
		597	}
		598
		599	=item staticperl_xs_init (pTHX)
		600
		601	Sometimes you need direct control over C<perl_parse> and C<perl_run>, in
		602	which case you do not want to use C<staticperl_init> but call them on your
		603	own.
		604
		605	Then you need this function - either pass it directly as the C<xs_init>
		606	function to C<perl_parse>, or call it from your own C<xs_init> function.
		607
		608	=item staticperl_cleanup ()
		609
		610	In the unlikely case that you want to destroy the perl interpreter, here
		611	is the corresponding function.
		612
		613	=item PerlInterpreter *staticperl
		614
		615	The perl interpreter pointer used by staticperl. Not normally so useful,
		616	but there it is.
		617
		618	=back
		619
		620	=item bundle.ccopts
		621
		622	Contains the compiler options required to compile at least F<bundle.c> and
		623	any file that includes F<bundle.h> - you should probably use it in your
		624	C<CFLAGS>.
		625
		626	=item bundle.ldopts
		627
		628	The linker options needed to link the final program.
		629
		630	=back
		631
		632	=head1 RUNTIME FUNCTIONALITY
		633
		634	Binaries created with C<mkbundle>/C<mkperl> contain extra functions, which
		635	are required to access the bundled perl sources, but might be useful for
		636	other purposes.
		637
		638	In addition, for the embedded loading of perl files to work, F<staticperl>
		639	overrides the C<@INC> array.
		640
		641	=over 4
		642
		643	=item $file = staticperl::find $path
		644
		645	Returns the data associated with the given C<$path>
		646	(e.g. C<Digest/MD5.pm>, C<auto/POSIX/autosplit.ix>), which is basically
		647	the UNIX path relative to the perl library directory.
		648
		649	Returns C<undef> if the file isn't embedded.
		650
		651	=item @paths = staticperl::list
		652
		653	Returns the list of all paths embedded in this binary.
		654
		655	=back
		656
		657	=head1 FULLY STATIC BINARIES - BUILDROOT
		658
		659	To make truly static (linux-) libraries, you might want to have a look at
		660	buildroot (L<http://buildroot.uclibc.org/>).
		661
		662	Buildroot is primarily meant to set up a cross-compile environment (which
		663	is not so useful as perl doesn't quite like cross compiles), but it can also compile
		664	a chroot environment where you can use F<staticperl>.
		665
		666	To do so, download buildroot, and enable "Build options => development
		667	files in target filesystem" and optionally "Build options => gcc
		668	optimization level (optimize for size)". At the time of writing, I had
		669	good experiences with GCC 4.4.x but not GCC 4.5.
		670
		671	To minimise code size, I used C<-pipe -ffunction-sections -fdata-sections
		672	-finline-limit=8 -fno-builtin-strlen -mtune=i386>. The C<-mtune=i386>
		673	doesn't decrease codesize much, but it makes the file much more
		674	compressible.
		675
		676	If you don't need Coro or threads, you can go with "linuxthreads.old" (or
		677	no thread support). For Coro, it is highly recommended to switch to a
		678	uClibc newer than 0.9.31 (at the time of this writing, I used the 20101201
		679	snapshot) and enable NPTL, otherwise Coro needs to be configured with the
		680	ultra-slow pthreads backend to work around linuxthreads bugs (it also uses
		681	twice the address space needed for stacks).
		682
		683	C<ccache> support is also recommended, especially if you want to
		684	play around with buildroot options. Enabling the C<miniperl> package
		685	will probably enable all options required for a successful perl
		686	build. F<staticperl> itself additionally needs either C<wget> or C<curl>.
		687
		688	As for shells, busybox should provide all that is needed, but the default
		689	busybox configuration doesn't include F<comm> which is needed by perl -
		690	either make a custom busybox config, or compile coreutils.
		691
		692	For the latter route, you might find that bash has some bugs that keep
		693	it from working properly in a chroot - either use dash (and link it to
		694	F</bin/sh> inside the chroot) or link busybox to F</bin/sh>, using it's
		695	built-in ash shell.
		696
		697	Finally, you need F</dev/null> inside the chroot for many scripts to work
		698	- F<cp /dev/null output/target/dev> or bind-mounting your F</dev> will
		699	both provide this.
		700
		701	After you have compiled and set up your buildroot target, you can copy
		702	F<staticperl> from the C<App::Staticperl> distribution or from your
		703	perl f<bin> directory (if you installed it) into the F<output/target>
		704	filesystem, chroot inside and run it.
279		705
280	=head1 AUTHOR	706	=head1 AUTHOR
281		707
282	Marc Lehmann <schmorp@schmorp.de>	708	Marc Lehmann <schmorp@schmorp.de>
283	http://software.schmorp.de/pkg/staticperl.html	709	http://software.schmorp.de/pkg/staticperl.html
284
285
286

Diff Legend

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

Comparing App-Staticperl/staticperl.pod (file contents): Revision 1.1 by root, Mon Dec 6 19:33:57 2010 UTC vs. Revision 1.9 by root, Tue Dec 7 09:08:06 2010 UTC

Diff Legend

Comparing App-Staticperl/staticperl.pod (file contents):
Revision 1.1 by root, Mon Dec 6 19:33:57 2010 UTC vs.
Revision 1.9 by root, Tue Dec 7 09:08:06 2010 UTC