[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.7 by root, Mon Dec 6 21:21:44 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, 50 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 that
38	contains perl and 50 modules such as AnyEvent, EV, IO::AIO, Coro and so	38	contains perl and 50 modules such as AnyEvent, EV, IO::AIO, Coro and so
39	on. Or any other choice of modules.	39	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, in the unlikely case where C<pod> is too slow, or some
		293	module gets mistreated, you can specify C<none> to not mangle included
		294	perl sources in any way.
		295
		296	=item --perl
		297
		298	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
		300	directory. The bundle files will be removed.
		301
		302	This switch is automatically used when F<staticperl> is invoked with the
		303	C<mkperl> command (instead of C<mkbundle>):
		304
		305	# build a new ./perl with only common::sense in it - very small :)
		306	staticperl mkperl -Mcommon::sense
		307
		308	=item --use module \| -Mmodule
		309
		310	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
		312	and files it actually loads. If the module uses L<AutoLoader>, then all
		313	splitfiles will be included as well.
		314
		315	Example: include AnyEvent and AnyEvent::Impl::Perl.
		316
		317	staticperl mkbundle --use AnyEvent --use AnyEvent::Impl::Perl
		318
		319	Sometimes you want to load old-style "perl libraries" (F<.pl> files), or
		320	maybe other weirdly named files. To do that, you need to quote the name in
		321	single or double quotes. When given on the command line, you probably need
		322	to quote once more to avoid your shell interpreting it. Common cases that
		323	need this are F<Config_heavy.pl> and F<utf8_heavy.pl>.
		324
		325	Example: include the required files for F<perl -V> to work in all its
		326	glory (F<Config.pm> is included automatically by this).
		327
		328	# bourne shell
		329	staticperl mkbundle --use '"Config_heavy.pl"'
		330
		331	# bundle specification file
		332	use "Config_heavy.pl"
		333
		334	The C<-Mmodule> syntax is included as an alias that might be easier to
		335	remember than C<use>. Or maybe it confuses people. Time will tell. Or
		336	maybe not. Argh.
		337
		338	=item --eval "perl code" \| -e "perl code"
		339
		340	Sometimes it is easier (or necessary) to specify dependencies using perl
		341	code, or maybe one of the modules you use need a special use statement. In
		342	that case, you can use C<eval> to execute some perl snippet or set some
		343	variables or whatever you need. All files C<require>'d or C<use>'d in the
		344	script are included in the final bundle.
		345
		346	Keep in mind that F<mkbundle> will only C<require> the modules named
		347	by the C<--use> option, so do not expect the symbols from modules you
		348	C<--use>'d earlier on the command line to be available.
		349
		350	Example: force L<AnyEvent> to detect a backend and therefore include it
		351	in the final bundle.
		352
		353	staticperl mkbundle --eval 'use AnyEvent; AnyEvent::detect'
		354
		355	# or like this
		356	staticperl mkbundle -MAnyEvent --eval 'use AnyEvent; AnyEvent::detect'
		357
		358	Example: use a separate "bootstrap" script that C<use>'s lots of modules
		359	and include this in the final bundle, to be executed automatically.
		360
		361	staticperl mkbundle --eval 'do "bootstrap"' --boot bootstrap
		362
		363	=item --boot filename
		364
		365	Include the given file in the bundle and arrange for it to be executed
		366	(using a C<require>) before anything else when the new perl is
		367	initialised. This can be used to modify C<@INC> or anything else before
		368	the perl interpreter executes scripts given on the command line (or via
		369	C<-e>). This works even in an embedded interpreter.
		370
		371	=item --add "file" \| --add "file alias"
		372
		373	Adds the given (perl) file into the bundle (and optionally call it
		374	"alias"). This is useful to include any custom files into the bundle.
		375
		376	Example: embed the file F<httpd> as F<httpd.pm> when creating the bundle.
		377
		378	staticperl mkperl --add "httpd httpd.pm"
		379
		380	It is also a great way to add any custom modules:
		381
		382	# specification file
		383	add file1 myfiles/file1
		384	add file2 myfiles/file2
		385	add file3 myfiles/file3
		386
		387	=item --static
		388
		389	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
		391	perl modules are linked statically, but all external libraries are still
		392	referenced dynamically).
		393
		394	Keep in mind that Solaris doesn't support static linking at all, and
		395	systems based on GNU libc don't really support it in a usable fashion
		396	either. Try uClibc if you want to create fully statically linked
		397	executables, or try the C<--staticlibs> option to link only some libraries
		398	statically.
		399
		400	=item any other argument
		401
		402	Any other argument is interpreted as a bundle specification file, which
		403	supports most long options (without extra quoting), one option per line.
273		404
274	=back	405	=back
275		406
276	=head2 F<STATCPERL> CONFIGURATION AND HOOKS	407	=head2 F<STATCPERL> CONFIGURATION AND HOOKS
277		408
278	#TODO	409	During (each) startup, F<staticperl> tries to source the following shell
		410	files in order:
		411
		412	/etc/staticperlrc
		413	~/.staticperlrc
		414	$STATICPERL/rc
		415
		416	They can be used to override shell variables, or define functions to be
		417	called at specific phases.
		418
		419	Note that the last file is erased during F<staticperl distclean>, so
		420	generally should not be used.
		421
		422	=head3 CONFIGURATION VARIABLES
		423
		424	=head4 Variables you I<should> override
		425
		426	=over 4
		427
		428	=item C<EMAIL>
		429
		430	The e-mail address of the person who built this binary. Has no good
		431	default, so should be specified by you.
		432
		433	=back
		434
		435	=head4 Variables you might I<want> to override
		436
		437	=over 4
		438
		439	=item C<PERLVER>
		440
		441	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
		443	about as big as 5.12.2).
		444
		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>
		473
		474	The prefix where perl gets installed (default: F<$STATICPERL/perl>),
		475	i.e. where the F<bin> and F<lib> subdirectories will end up.
		476
		477	=item C<PERL_CPPFLAGS>, C<PERL_OPTIMIZE>, C<PERL_LDFLAGS>, C<PERL_LIBS>
		478
		479	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
		481	contain subtle workarounds around various build issues, changing these
		482	usually requires understanding their default values - best look at the top
		483	of the F<staticperl> script for more info on these.
		484
		485	=back
		486
		487	=head4 Variables you probably I<do not want> to override
		488
		489	=over 4
		490
		491	=item C<MKBUNDLE>
		492
		493	Where F<staticperl> writes the C<mkbundle> command to
		494	(default: F<$STATICPERL/mkbundle>).
		495
		496	=item C<STATICPERL_MODULES>
		497
		498	Additional modules needed by C<mkbundle> - should therefore not be changed
		499	unless you know what you are doing.
		500
		501	=back
		502
		503	=head3 OVERRIDABLE HOOKS
		504
		505	In addition to environment variables, it is possible to provide some
		506	shell functions that are called at specific times. To provide your own
		507	commands, just define the corresponding function.
		508
		509	Example: install extra modules from CPAN and from some directories
		510	at F<staticperl install> time.
		511
		512	postinstall() {
		513	rm -rf lib/threads* # weg mit Schaden
		514	instcpan IO::AIO EV
		515	instsrc ~/src/AnyEvent
		516	instsrc ~/src/XML-Sablotron-1.0100001
		517	instcpan Anyevent::AIO AnyEvent::HTTPD
		518	}
		519
		520	=over 4
		521
		522	=item postconfigure
		523
		524	Called after configuring, but before building perl. Current working
		525	directory is the perl source directory.
		526
		527	Could be used to tailor/patch config.sh (followed by F<./Configure -S>) or
		528	do any other modifications.
		529
		530	=item postbuild
		531
		532	Called after building, but before installing perl. Current working
		533	directory is the perl source directory.
		534
		535	I have no clue what this could be used for - tell me.
		536
		537	=item postinstall
		538
		539	Called after perl and any extra modules have been installed in C<$PREFIX>,
		540	but before setting the "installation O.K." flag.
		541
		542	The current working directory is C<$PREFIX>, but maybe you should not rely
		543	on that.
		544
		545	This hook is most useful to customise the installation, by deleting files,
		546	or installing extra modules using the C<instcpan> or C<instsrc> functions.
		547
		548	The script must return with a zero exit status, or the installation will
		549	fail.
		550
		551	=back
279		552
280	=head1 AUTHOR	553	=head1 AUTHOR
281		554
282	Marc Lehmann <schmorp@schmorp.de>	555	Marc Lehmann <schmorp@schmorp.de>
283	http://software.schmorp.de/pkg/staticperl.html	556	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.7 by root, Mon Dec 6 21:21:44 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.7 by root, Mon Dec 6 21:21:44 2010 UTC