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

Comparing cvsroot/App-Staticperl/staticperl.pod (file contents):
Revision 1.1 by root, Mon Dec 6 19:33:57 2010 UTC vs.
Revision 1.2 by root, Mon Dec 6 20:53:44 2010 UTC

…		…
206	with any arguments you pass:	206	with any arguments you pass:
207		207
208	staticperl mkbundle mkbundle-args...	208	staticperl mkbundle mkbundle-args...
209		209
210	In the oh so unlikely case of something not working here, you	210	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	211	can run the script manually as well (by default it is written to
212	F<~/.staticperl/mkbundle>).	212	F<~/.staticperl/mkbundle>).
213		213
214	F<mkbundle> is a more conventional command and expect the argument	214	F<mkbundle> is a more conventional command and expect the argument
215	syntax commonly used on unix clones. For example, this command builds	215	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>),	216	a new F<perl> binary and includes F<Config.pm> (for F<perl -V>),
…		…
254	use AnyEvent::Impl::Perl	254	use AnyEvent::Impl::Perl
255	use AnyEvent::HTTPD	255	use AnyEvent::HTTPD
256	use URI::http	256	use URI::http
257	add eg/httpd httpd.pm	257	add eg/httpd httpd.pm
258		258
		259	All options that specify modules or files to be added are processed in the
		260	order given on the commandline (that affects the C<--use> and C<--eval>
		261	options at the moment).
		262
259	=head3 MKBUNDLE OPTIONS	263	=head3 MKBUNDLE OPTIONS
260		264
261	=over 4	265	=over 4
262		266
263	"strip=s" => \$STRIP,	267	=item --verbose \| -v
264	"verbose\|v" => sub { ++$VERBOSE },	268
265	"quiet\|q" => sub { --$VERBOSE },	269	Increases the verbosity level by one (the default is C<1>).
266	"perl" => \$PERL,	270
267	"eval=s" => sub { trace_eval $_[1] },	271	=item --quiet \| -q
268	"use\|M=s" => sub { trace_module $_[1] },	272
269	"boot=s" => sub { cmd_boot $_[1] },	273	Decreases the verbosity level by one.
270	"add=s" => sub { cmd_add $_[1] },	274
271	"static" => sub { $STATIC = 1 },	275	=item --strip none\|pod\|ppi
272	"<>" => sub { cmd_file $_[1] },	276
		277	Specify the stripping method applied to reduce the file of the perl
		278	sources included.
		279
		280	The default is C<pod>, which uses the L<Pod::Strip> module to remove all
		281	pod documenatiton, which is very fast and reduces filesize a lot.
		282
		283	The C<ppi> method uses L<PPI> to parse and condense the perl sources. This
		284	saves a lot more than just L<Pod::Strip>, and is generally safer, but is
		285	also a lot slower, so is best used for production builds.
		286
		287	Last not least, in the unlikely case where C<pod> is too slow, or some
		288	module gets mistreated, you can specify C<none> to not mangle included
		289	perl sources in any way.
		290
		291	=item --perl
		292
		293	After writing out the bundle files, try to link a new perl interpreter. It
		294	will be called F<perl> and will be left in the current working
		295	directory. The bundle files will be removed.
		296
		297	This switch is automatically ued when F<staticperl> is invoked with the
		298	C<mkperl> command (instead of C<mkbundle>):
		299
		300	# build a new ./perl with only common::sense in it - very small :)
		301	staticperl mkperl -Mcommon::sense
		302
		303	=item --use module \| -Mmodule
		304
		305	Include the named module and all direct dependencies. This is done by
		306	C<require>'ing the module in a subprocess and tracing which other modules
		307	and files it actually loads. If the module uses L<AutoLoader>, then all
		308	splitfiles will be included as well.
		309
		310	Example: include AnyEvent and AnyEvent::Impl::Perl.
		311
		312	staticperl mkbundle --use AnyEvent --use AnyEvent::Impl::Perl
		313
		314	Sometimes you want to load old-style "perl libraries" (F<.pl> files), or
		315	maybe other weirdly named files. To do that, you need to quote the name in
		316	single or double quoutes. When given on the commandline, you probably need
		317	to quote once more to avoid your shell interpreting it. Common cases that
		318	need this are F<Config_heavy.pl> and F<utf8_heavy.pl>.
		319
		320	Example: include the required files for F<perl -V> to work in all its
		321	glory (F<Config.pm> is included automatically by this).
		322
		323	# bourne shell
		324	staticperl mkbundle --use '"Config_heavy.pl"'
		325
		326	# bundle specification file
		327	use "Config_heavy.pl"
		328
		329	The C<-Mmodule> syntax is included as an alias that might be easier to
		330	remember than C<use>. Or maybe it confuses people. Time will tell. Or
		331	maybe not. Argh.
		332
		333	=item --eval "perl code" \| -e "perl code"
		334
		335	Sometimes it is easier (or necessary) to specify dependencies using perl
		336	code, or maybe one of the modules you use need a special use statement. In
		337	that case, you can use C<eval> to execute some perl snippet or set some
		338	variables or whatever you need. All files C<require>'d or C<use>'d in the
		339	script are included in the final bundle.
		340
		341	Keep in mind that F<mkbundle> will only C<require> the modules named
		342	by the C<--use> option, so do not expect the symbols from modules you
		343	C<--use>'d earlier on the commandlien to be available.
		344
		345	Example: force L<AnyEvent> to detect a backend and therefore include it
		346	in the final bundle.
		347
		348	staticperl mkbundle --eval 'use AnyEvent; AnyEvent::detect'
		349
		350	# or like this
		351	staticperl mkbundle -MAnyEvent --eval 'use AnyEvent; AnyEvent::detect'
		352
		353	Example: use a separate "bootstrap" script that C<use>'s lots of modules
		354	and include this in the final bundle, to be executed automatically.
		355
		356	staticperl mkbundle --eval 'do "bootstrap"' --boot bootstrap
		357
		358	=item --boot filename
		359
		360	Include the given file in the bundle and arrange for it to be executed
		361	(using a C<require>) before anything else when the new perl is
		362	initialised. This can be used to modify C<@INC> or anything else before
		363	the perl interpreter executes scripts given on the commandline (or via
		364	C<-e>). This works even in an embedded interpreter.
		365
		366	=item --add "file" \| --add "file alias"
		367
		368	Adds the given (perl) file into the bundle (and optionally call it
		369	"alias"). This is useful to include any custom files into the bundle.
		370
		371	Example: embed the file F<httpd> as F<httpd.pm> when creating the bundle.
		372
		373	staticperl mkperl --add "httpd httpd.pm"
		374
		375	It is also a great way to add any custom modules:
		376
		377	# specification file
		378	add file1 myfiles/file1
		379	add file2 myfiles/file2
		380	add file3 myfiles/file3
		381
		382	=item --static
		383
		384	When C<--perl> is also given, link statically instead of dynamically. The
		385	default is to link the new perl interpreter fully dynamic (that means all
		386	perl modules are linked statically, but all external libraries are still
		387	referenced dynamically).
		388
		389	Keep in mind that Solaris doesn't support static linking at all, and
		390	systems based on GNU libc don't really support it in a usable fashion
		391	either. Try uClibc if you want to create fully statically linked
		392	executables, or try the C<--staticlibs> option to link only some libraries
		393	statically.
		394
		395	=item any other argument
		396
		397	Any other argument is interpreted as a bundle specification file, which
		398	supports most long options (without extra quoting), one option per line.
273		399
274	=back	400	=back
275		401
276	=head2 F<STATCPERL> CONFIGURATION AND HOOKS	402	=head2 F<STATCPERL> CONFIGURATION AND HOOKS
277		403
278	#TODO	404	During (each) startup, F<staticperl> tries to source the following shell
		405	files in order:
		406
		407	/etc/staticperlrc
		408	~/.staticperlrc
		409	$STATICPERL/rc
		410
		411	They can be used to override shell variables, or define functions to be
		412	called at specific phases.
		413
		414	Note that the last file is erased during F<staticperl distclean>, so
		415	generally should not be used.
		416
		417	=head3 CONFIGURATION VARIABLES
		418
		419	=head4 Variables you I<should> override
		420
		421	=over 4
		422
		423	=item C<EMAIL>
		424
		425	The e-mail address of the person who built this binary. Has no good
		426	default, so should be specified by you.
		427
		428	=back
		429
		430	=head4 Variables you I<might want> to override
		431
		432	=over 4
		433
		434	=item C<PERLVER>
		435
		436	The perl version to install - default is currently C<5.12.2>, but C<5.8.9>
		437	is also a good choice (5.8.9 is much smaller than 5.12.2, while 5.10.1 is
		438	about as big as 5.12.2).
		439
		440	=item C<CPAN>
		441
		442	The URL of the CPAN mirror to use (e.g. L<http://mirror.netcologne.de/cpan/>).
		443
		444	=item C<PERL_CPPFLAGS>, C<PERL_OPTIMIZE>, C<PERL_LDFLAGS>, C<PERL_LIBS>
		445
		446	These flags are passed to perl's F<Configure> script, and are generally
		447	optimised for small size (at the cost of performance). Since they also
		448	contain subtle workarounds around various build issues, changing these
		449	usually requires understanding their default values - best look at the top
		450	of the F<staticperl> script for more info on these.
		451
		452	=item C<STATICPERL>
		453
		454	The directory where staticperl stores all its files
		455	(default: F<~/.staticperl>).
		456
		457	=item C<PREFIX>
		458
		459	The prefix where perl get's installed (default: F<$STATICPERL/perl>),
		460	i.e. where the F<bin> and F<lib> subdirectories will end up.
		461
		462	=item C<PERL_MM_USE_DEFAULT>, C<EV_EXTRA_DEFS>, others
		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<EXTRA_MODULES>
		469
		470	Additional modules installed during F<staticperl install>. Here you can
		471	set which modules you want have to installed from CPAN.
		472
		473	Example: I really really need EV, AnyEvent, Coro and IO::AIO.
		474
		475	EXTRA_MODULES="EV AnyEvent Coro IO::AIO"
		476
		477	Note that you cna also use a C<postinstall> hook to achieve this, and
		478	more.
		479
		480	=back
		481
		482	=head4 Variables you I<probably do not want> to override
		483
		484	=over 4
		485
		486	=item C<MKBUNDLE>
		487
		488	Where F<staticperl> writes the C<mkbundle> command to
		489	(default: F<$STATICPERL/mkbundle>).
		490
		491	=item C<STATICPERL_MODULES>
		492
		493	Additional modules needed by C<mkbundle> - should therefore not be changed
		494	unless you know what you are doing.
		495
		496	=back
		497
		498	=head3 OVERRIDABLE HOOKS
		499
		500	In addition to environment variables, it is possible to provide some
		501	shell functions that are called at specific times. To provide your own
		502	commands, justd efine the corresponding function.
		503
		504	Example: install extra modules from CPAN and from some directories
		505	at F<staticperl install> time.
		506
		507	postinstall() {
		508	rm -rf lib/threads.* # weg mit Schaden
		509	instcpan IO::AIO EV
		510	instsrc ~/src/AnyEvent
		511	instsrc ~/src/XML-Sablotron-1.0100001
		512	instcpan AnyEvent::HTTPD
		513	}
		514
		515	=over 4
		516
		517	=item postconfigure
		518
		519	Called after configuring, but before building perl. Current working
		520	directory is the perl source directory.
		521
		522	Could be used to tailor/patch config.sh (followed by F<./Configure -S>) or
		523	do any other modifications.
		524
		525	=item postbuild
		526
		527	Called after building, but before installing perl. Current working
		528	directory is the perl source directory.
		529
		530	I have no clue what this could be used for - tell me.
		531
		532	=item postinstall
		533
		534	Called after perl and any extra modules have been installed in C<$PREFIX>,
		535	but before setting the "installation O.K." flag.
		536
		537	The current working directory is C<$PREFIX>, but maybe you should not rely
		538	on that.
		539
		540	This hook is most useful to customise the installation, by deleting files,
		541	or installing extra modules using the C<instcpan> or C<instsrc> functions.
		542
		543	The script must return with a zero exit status, or the installation will
		544	fail.
		545
		546	=back
279		547
280	=head1 AUTHOR	548	=head1 AUTHOR
281		549
282	Marc Lehmann <schmorp@schmorp.de>	550	Marc Lehmann <schmorp@schmorp.de>
283	http://software.schmorp.de/pkg/staticperl.html	551	http://software.schmorp.de/pkg/staticperl.html
284
285
286

Diff Legend

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

Comparing cvsroot/App-Staticperl/staticperl.pod (file contents): Revision 1.1 by root, Mon Dec 6 19:33:57 2010 UTC vs. Revision 1.2 by root, Mon Dec 6 20:53:44 2010 UTC

Diff Legend

Comparing cvsroot/App-Staticperl/staticperl.pod (file contents):
Revision 1.1 by root, Mon Dec 6 19:33:57 2010 UTC vs.
Revision 1.2 by root, Mon Dec 6 20:53:44 2010 UTC