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

Comparing App-Staticperl/staticperl.pod (file contents):
Revision 1.5 by root, Mon Dec 6 21:14:26 2010 UTC vs.
Revision 1.10 by root, Tue Dec 7 09:27:54 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
32	fully self-contained - no separate shared objects, no autoload fragments,	32	fully self-contained - no separate shared objects, no autoload fragments,
33	no .pm or .pl files are needed. And when linking statically, you can	33	no .pm or .pl files are needed. And when linking statically, you can
34	create (or embed) a single file that contains perl interpreter, libc, all	34	create (or embed) a single file that contains perl interpreter, libc, all
35	the modules you need and all the libraries you need.	35	the modules you need and all the libraries you need.
36		36
37	With F<uClibc> and F<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 file system (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
…		…
287	is also a lot slower, so is best used for production builds. Note that	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	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	289	(that means that the uncompressed file size is a bit larger, but the files
290	compress better, e.g. with F<upx>).	290	compress better, e.g. with F<upx>).
291		291
		292	Last not least, if you need accurate line numbers in error messages,
292	Last not least, in the unlikely case where C<pod> is too slow, or some	293	or in the unlikely case where C<pod> is too slow, or some module gets
293	module gets mistreated, you can specify C<none> to not mangle included	294	mistreated, you can specify C<none> to not mangle included perl sources in
294	perl sources in any way.	295	any way.
295		296
296	=item --perl	297	=item --perl
297		298
298	After writing out the bundle files, try to link a new perl interpreter. It	299	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	will be called F<perl> and will be left in the current working
…		…
382	# specification file	383	# specification file
383	add file1 myfiles/file1	384	add file1 myfiles/file1
384	add file2 myfiles/file2	385	add file2 myfiles/file2
385	add file3 myfiles/file3	386	add file3 myfiles/file3
386		387
		388	=item --binadd "file" \| --add "file alias"
		389
		390	Just like C<--add>, except that it treats the file as binary and adds it
		391	without any processing.
		392
		393	You should probably add a C</> prefix to avoid clashing with embedded
		394	perl files (whose paths do not start with C</>), and/or use a special
		395	directory, such as C</res/name>.
		396
		397	You can later get a copy of these files by calling C<staticperl::find
		398	"alias">.
		399
387	=item --static	400	=item --static
388		401
389	When C<--perl> is also given, link statically instead of dynamically. The	402	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	403	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	404	perl modules are linked statically, but all external libraries are still
…		…
444		457
445	=item C<CPAN>	458	=item C<CPAN>
446		459
447	The URL of the CPAN mirror to use (e.g. L<http://mirror.netcologne.de/cpan/>).	460	The URL of the CPAN mirror to use (e.g. L<http://mirror.netcologne.de/cpan/>).
448		461
		462	=item C<EXTRA_MODULES>
		463
		464	Additional modules installed during F<staticperl install>. Here you can
		465	set which modules you want have to installed from CPAN.
		466
		467	Example: I really really need EV, AnyEvent, Coro and IO::AIO.
		468
		469	EXTRA_MODULES="EV AnyEvent Coro IO::AIO"
		470
		471	Note that you can also use a C<postinstall> hook to achieve this, and
		472	more.
		473
		474	=item C<PERL_MM_USE_DEFAULT>, C<EV_EXTRA_DEFS>, ...
		475
		476	Usually set to C<1> to make modules "less inquisitive" during their
		477	installation, you can set any environment variable you want - some modules
		478	(such as L<Coro> or L<EV>) use environment variables for further tweaking.
		479
		480	=item C<STATICPERL>
		481
		482	The directory where staticperl stores all its files
		483	(default: F<~/.staticperl>).
		484
		485	=item C<PREFIX>
		486
		487	The prefix where perl gets installed (default: F<$STATICPERL/perl>),
		488	i.e. where the F<bin> and F<lib> subdirectories will end up.
		489
		490	=item C<PERL_CONFIGURE>
		491
		492	Additional Configure options - these are simply passed to the perl
		493	Configure script. For example, if you wanted to enable dynamic loading,
		494	you could pass C<-Dusedl>. To enable ithreads (Why would you want that
		495	insanity? Don't! Use L<forks> instead!) you would pass C<-Duseithreads>
		496	and so on.
		497
		498	More commonly, you would either activate 64 bit integer support
		499	(C<-Duse64bitint>), or disable large files support (-Uuselargefiles), to
		500	reduce filesize further.
		501
449	=item C<PERL_CPPFLAGS>, C<PERL_OPTIMIZE>, C<PERL_LDFLAGS>, C<PERL_LIBS>	502	=item C<PERL_CPPFLAGS>, C<PERL_OPTIMIZE>, C<PERL_LDFLAGS>, C<PERL_LIBS>
450		503
451	These flags are passed to perl's F<Configure> script, and are generally	504	These flags are passed to perl's F<Configure> script, and are generally
452	optimised for small size (at the cost of performance). Since they also	505	optimised for small size (at the cost of performance). Since they also
453	contain subtle workarounds around various build issues, changing these	506	contain subtle workarounds around various build issues, changing these
454	usually requires understanding their default values - best look at the top	507	usually requires understanding their default values - best look at the top
455	of the F<staticperl> script for more info on these.	508	of the F<staticperl> script for more info on these.
456
457	=item C<STATICPERL>
458
459	The directory where staticperl stores all its files
460	(default: F<~/.staticperl>).
461
462	=item C<PREFIX>
463
464	The prefix where perl gets installed (default: F<$STATICPERL/perl>),
465	i.e. where the F<bin> and F<lib> subdirectories will end up.
466
467	=item C<PERL_MM_USE_DEFAULT>, C<EV_EXTRA_DEFS>, others
468
469	Usually set to C<1> to make modules "less inquisitive" during their
470	installation, you can set any environment variable you want - some modules
471	(such as L<Coro> or L<EV>) use environment variables for further tweaking.
472
473	=item C<EXTRA_MODULES>
474
475	Additional modules installed during F<staticperl install>. Here you can
476	set which modules you want have to installed from CPAN.
477
478	Example: I really really need EV, AnyEvent, Coro and IO::AIO.
479
480	EXTRA_MODULES="EV AnyEvent Coro IO::AIO"
481
482	Note that you can also use a C<postinstall> hook to achieve this, and
483	more.
484		509
485	=back	510	=back
486		511
487	=head4 Variables you probably I<do not want> to override	512	=head4 Variables you probably I<do not want> to override
488		513
…		…
548	The script must return with a zero exit status, or the installation will	573	The script must return with a zero exit status, or the installation will
549	fail.	574	fail.
550		575
551	=back	576	=back
552		577
		578	=head1 ANATOMY OF A BUNDLE
		579
		580	When not building a new perl binary, C<mkbundle> will leave a number of
		581	files in the current working directory, which can be used to embed a perl
		582	interpreter in your program.
		583
		584	Intimate knowledge of L<perlembed> and preferably some experience with
		585	embedding perl is highly recommended.
		586
		587	C<mkperl> (or the C<--perl> option) basically does this to link the new
		588	interpreter (it also adds a main program to F<bundle.>):
		589
		590	$Config{cc} $(cat bundle.ccopts) -o perl bundle.c $(cat bundle.ldopts)
		591
		592	=over 4
		593
		594	=item bundle.h
		595
		596	A header file that contains the prototypes of the few symbols "exported"
		597	by bundle.c, and also exposes the perl headers to the application.
		598
		599	=over 4
		600
		601	=item staticperl_init ()
		602
		603	Initialises the perl interpreter. You can use the normal perl functions
		604	after calling this function, for example, to define extra functions or
		605	to load a .pm file that contains some initialisation code, or the main
		606	program function:
		607
		608	XS (xsfunction)
		609	{
		610	dXSARGS;
		611
		612	// now we have items, ST(i) etc.
		613	}
		614
		615	static void
		616	run_myapp(void)
		617	{
		618	staticperl_init ();
		619	newXSproto ("myapp::xsfunction", xsfunction, __FILE__, "$$;$");
		620	eval_pv ("require myapp::main", 1); // executes "myapp/main.pm"
		621	}
		622
		623	=item staticperl_xs_init (pTHX)
		624
		625	Sometimes you need direct control over C<perl_parse> and C<perl_run>, in
		626	which case you do not want to use C<staticperl_init> but call them on your
		627	own.
		628
		629	Then you need this function - either pass it directly as the C<xs_init>
		630	function to C<perl_parse>, or call it from your own C<xs_init> function.
		631
		632	=item staticperl_cleanup ()
		633
		634	In the unlikely case that you want to destroy the perl interpreter, here
		635	is the corresponding function.
		636
		637	=item PerlInterpreter *staticperl
		638
		639	The perl interpreter pointer used by staticperl. Not normally so useful,
		640	but there it is.
		641
		642	=back
		643
		644	=item bundle.ccopts
		645
		646	Contains the compiler options required to compile at least F<bundle.c> and
		647	any file that includes F<bundle.h> - you should probably use it in your
		648	C<CFLAGS>.
		649
		650	=item bundle.ldopts
		651
		652	The linker options needed to link the final program.
		653
		654	=back
		655
		656	=head1 RUNTIME FUNCTIONALITY
		657
		658	Binaries created with C<mkbundle>/C<mkperl> contain extra functions, which
		659	are required to access the bundled perl sources, but might be useful for
		660	other purposes.
		661
		662	In addition, for the embedded loading of perl files to work, F<staticperl>
		663	overrides the C<@INC> array.
		664
		665	=over 4
		666
		667	=item $file = staticperl::find $path
		668
		669	Returns the data associated with the given C<$path>
		670	(e.g. C<Digest/MD5.pm>, C<auto/POSIX/autosplit.ix>), which is basically
		671	the UNIX path relative to the perl library directory.
		672
		673	Returns C<undef> if the file isn't embedded.
		674
		675	=item @paths = staticperl::list
		676
		677	Returns the list of all paths embedded in this binary.
		678
		679	=back
		680
		681	=head1 FULLY STATIC BINARIES - BUILDROOT
		682
		683	To make truly static (Linux-) libraries, you might want to have a look at
		684	buildroot (L<http://buildroot.uclibc.org/>).
		685
		686	Buildroot is primarily meant to set up a cross-compile environment (which
		687	is not so useful as perl doesn't quite like cross compiles), but it can also compile
		688	a chroot environment where you can use F<staticperl>.
		689
		690	To do so, download buildroot, and enable "Build options => development
		691	files in target filesystem" and optionally "Build options => gcc
		692	optimization level (optimize for size)". At the time of writing, I had
		693	good experiences with GCC 4.4.x but not GCC 4.5.
		694
		695	To minimise code size, I used C<-pipe -ffunction-sections -fdata-sections
		696	-finline-limit=8 -fno-builtin-strlen -mtune=i386>. The C<-mtune=i386>
		697	doesn't decrease codesize much, but it makes the file much more
		698	compressible.
		699
		700	If you don't need Coro or threads, you can go with "linuxthreads.old" (or
		701	no thread support). For Coro, it is highly recommended to switch to a
		702	uClibc newer than 0.9.31 (at the time of this writing, I used the 20101201
		703	snapshot) and enable NPTL, otherwise Coro needs to be configured with the
		704	ultra-slow pthreads backend to work around linuxthreads bugs (it also uses
		705	twice the address space needed for stacks).
		706
		707	If you use C<linuxthreads.old>, then you should also be aware that
		708	uClibc shares C<errno> between all threads when statically linking. See
		709	L<http://lists.uclibc.org/pipermail/uclibc/2010-June/044157.html> for a
		710	workaround (And L<https://bugs.uclibc.org/2089> for discussion).
		711
		712	C<ccache> support is also recommended, especially if you want to
		713	play around with buildroot options. Enabling the C<miniperl> package
		714	will probably enable all options required for a successful perl
		715	build. F<staticperl> itself additionally needs either C<wget> or C<curl>.
		716
		717	As for shells, busybox should provide all that is needed, but the default
		718	busybox configuration doesn't include F<comm> which is needed by perl -
		719	either make a custom busybox config, or compile coreutils.
		720
		721	For the latter route, you might find that bash has some bugs that keep
		722	it from working properly in a chroot - either use dash (and link it to
		723	F</bin/sh> inside the chroot) or link busybox to F</bin/sh>, using it's
		724	built-in ash shell.
		725
		726	Finally, you need F</dev/null> inside the chroot for many scripts to work
		727	- F<cp /dev/null output/target/dev> or bind-mounting your F</dev> will
		728	both provide this.
		729
		730	After you have compiled and set up your buildroot target, you can copy
		731	F<staticperl> from the C<App::Staticperl> distribution or from your
		732	perl f<bin> directory (if you installed it) into the F<output/target>
		733	filesystem, chroot inside and run it.
		734
553	=head1 AUTHOR	735	=head1 AUTHOR
554		736
555	Marc Lehmann <schmorp@schmorp.de>	737	Marc Lehmann <schmorp@schmorp.de>
556	http://software.schmorp.de/pkg/staticperl.html	738	http://software.schmorp.de/pkg/staticperl.html

Diff Legend

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

Comparing App-Staticperl/staticperl.pod (file contents): Revision 1.5 by root, Mon Dec 6 21:14:26 2010 UTC vs. Revision 1.10 by root, Tue Dec 7 09:27:54 2010 UTC

Diff Legend

Comparing App-Staticperl/staticperl.pod (file contents):
Revision 1.5 by root, Mon Dec 6 21:14:26 2010 UTC vs.
Revision 1.10 by root, Tue Dec 7 09:27:54 2010 UTC