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

Comparing App-Staticperl/staticperl.pod (file contents):
Revision 1.6 by root, Mon Dec 6 21:18:50 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
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
…		…
548	The script must return with a zero exit status, or the installation will	549	The script must return with a zero exit status, or the installation will
549	fail.	550	fail.
550		551
551	=back	552	=back
552		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.
		705
553	=head1 AUTHOR	706	=head1 AUTHOR
554		707
555	Marc Lehmann <schmorp@schmorp.de>	708	Marc Lehmann <schmorp@schmorp.de>
556	http://software.schmorp.de/pkg/staticperl.html	709	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.6 by root, Mon Dec 6 21:18:50 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.6 by root, Mon Dec 6 21:18:50 2010 UTC vs.
Revision 1.9 by root, Tue Dec 7 09:08:06 2010 UTC