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