[ViewVC] Diff of: cvs/App-Staticperl/README

Comparing App-Staticperl/README (file contents):
Revision 1.15 by root, Tue Jun 14 07:04:43 2011 UTC vs.
Revision 1.16 by root, Mon Jul 18 07:34:48 2011 UTC

…		…
9	staticperl install # build and then install perl	9	staticperl install # build and then install perl
10	staticperl clean # clean most intermediate files (restart at configure)	10	staticperl clean # clean most intermediate files (restart at configure)
11	staticperl distclean # delete everything installed by this script	11	staticperl distclean # delete everything installed by this script
12	staticperl perl ... # invoke the perlinterpreter	12	staticperl perl ... # invoke the perlinterpreter
13	staticperl cpan # invoke CPAN shell	13	staticperl cpan # invoke CPAN shell
14	staticperl instmod path... # install unpacked modules	14	staticperl instsrc path... # install unpacked modules
15	staticperl instcpan modulename... # install modules from CPAN	15	staticperl instcpan modulename... # install modules from CPAN
16	staticperl mkbundle <bundle-args...> # see documentation	16	staticperl mkbundle <bundle-args...> # see documentation
17	staticperl mkperl <bundle-args...> # see documentation	17	staticperl mkperl <bundle-args...> # see documentation
18	staticperl mkapp appname <bundle-args...> # see documentation	18	staticperl mkapp appname <bundle-args...> # see documentation
19		19
…		…
81	direct compile-time dependencies and AutoLoader are handled	81	direct compile-time dependencies and AutoLoader are handled
82	automatically. This means the modules to include often need to be	82	automatically. This means the modules to include often need to be
83	tweaked manually.	83	tweaked manually.
84		84
85	All this does not preclude more permissive modes to be implemented	85	All this does not preclude more permissive modes to be implemented
86	in the future, but right now, you have to resolve state hidden	86	in the future, but right now, you have to resolve hidden
87	dependencies manually.	87	dependencies manually.
88		88
89	* PAR works out of the box, staticperl does not.	89	* PAR works out of the box, staticperl does not.
90		90
91	Maintaining your own custom perl build can be a pain in the ass, and	91	Maintaining your own custom perl build can be a pain in the ass, and
…		…
189		189
190	staticperl cpan [args...]	190	staticperl cpan [args...]
191	Starts an interactive CPAN shell that you can use to install further	191	Starts an interactive CPAN shell that you can use to install further
192	modules. Installs the perl first if necessary, but apart from that,	192	modules. Installs the perl first if necessary, but apart from that,
193	no magic is involved: you could just as well run it manually via	193	no magic is involved: you could just as well run it manually via
194	~/.staticperl/perl/bin/cpan.	194	~/.staticperl/perl/bin/cpan, except that staticperl additionally
		195	sets the environment variable $PERL to the path of the perl
		196	interpreter, which is handy in subshells.
195		197
196	Any additional arguments are simply passed to the cpan command.	198	Any additional arguments are simply passed to the cpan command.
197		199
198	staticperl instcpan module...	200	staticperl instcpan module...
199	Tries to install all the modules given and their dependencies, using	201	Tries to install all the modules given and their dependencies, using
…		…
498	"--binadd" file \| "--add" "file alias"	500	"--binadd" file \| "--add" "file alias"
499	Just like "--add", except that it treats the file as binary and	501	Just like "--add", except that it treats the file as binary and
500	adds it without any postprocessing (perl files might get	502	adds it without any postprocessing (perl files might get
501	stripped to reduce their size).	503	stripped to reduce their size).
502		504
503	If you specify an alias you should probably add a "&" prefix to	505	If you specify an alias you should probably add a "/" prefix to
504	avoid clashing with embedded perl files (whose paths never start	506	avoid clashing with embedded perl files (whose paths never start
505	with "&"), and/or use a special directory prefix, such as	507	with "/"), and/or use a special directory prefix, such as
506	"&res/name".	508	"/res/name".
507		509
508	You can later get a copy of these files by calling	510	You can later get a copy of these files by calling "static::find
509	"staticperl::find "alias"".	511	"alias"".
510		512
511	An alternative way to embed binary files is to convert them to	513	An alternative way to embed binary files is to convert them to
512	perl and use "do" to get the contents - this method is a bit	514	perl and use "do" to get the contents - this method is a bit
513	cumbersome, but works both inside and outside of a staticperl	515	cumbersome, but works both inside and outside of a staticperl
514	bundle:	516	bundle, without extra ado:
515		517
516	# a "binary" file, call it "bindata.pl"	518	# a "binary" file, call it "bindata.pl"
517	<<'SOME_MARKER'	519	<<'SOME_MARKER'
518	binary data NOT containing SOME_MARKER	520	binary data NOT containing SOME_MARKER
519	SOME_MARKER	521	SOME_MARKER
520		522
521	# load the binary	523	# load the binary
522	chomp (my $data = do "bindata.pl");	524	chomp (my $data = do "bindata.pl");
		525
		526	"--allow-dynamic"
		527	By default, when mkbundle hits a dynamic perl extension (e.g. a
		528	.so or .dll file), it will stop with a fatal error.
		529
		530	When this option is enabled, mkbundle packages the shared object
		531	into the bundle instead, with a prefix of ! (e.g.
		532	!auto/List/Util/Util.so). What you do with that is currently up
		533	to you, staticperl has no special support for this at the
		534	moment, apart from working around the lack of availability of
		535	PerlIO::scalar while bootstrapping, at a speed cost.
		536
		537	One way to deal with this is to write all files starting with !
		538	into some directory and then "unshift" that path onto @INC.
		539
		540	#TODO: example
523		541
524	Step 2: filter all files using "--include" and "--exclude" options.	542	Step 2: filter all files using "--include" and "--exclude" options.
525	After all candidate files and modules are added, they are filtered	543	After all candidate files and modules are added, they are filtered
526	by a combination of "--include" and "--exclude" patterns (there is	544	by a combination of "--include" and "--exclude" patterns (there is
527	an implicit "--include *" at the end, so if no filters are	545	an implicit "--include *" at the end, so if no filters are
…		…
797	Variables you might want to override	815	Variables you might want to override
798	"STATICPERL"	816	"STATICPERL"
799	The directory where staticperl stores all its files (default:	817	The directory where staticperl stores all its files (default:
800	~/.staticperl).	818	~/.staticperl).
801		819
802	"PERL_MM_USE_DEFAULT", "EV_EXTRA_DEFS", ...	820	"DLCACHE"
803	Usually set to 1 to make modules "less inquisitive" during their	821	The path to a directory (will be created if it doesn't exist) where
804	installation, you can set any environment variable you want - some	822	downloaded perl sources are being cached, to avoid downloading them
805	modules (such as Coro or EV) use environment variables for further	823	again. The default is empty, which means there is no cache.
806	tweaking.
807		824
808	"PERL_VERSION"	825	"PERL_VERSION"
809	The perl version to install - default is currently 5.12.3, but 5.8.9	826	The perl version to install - default is currently 5.12.3, but 5.8.9
810	is also a good choice (5.8.9 is much smaller than 5.12.3, while	827	is also a good choice (5.8.9 is much smaller than 5.12.3, while
811	5.10.1 is about as big as 5.12.3).	828	5.10.1 is about as big as 5.12.3).
		829
		830	"PERL_MM_USE_DEFAULT", "EV_EXTRA_DEFS", ...
		831	Usually set to 1 to make modules "less inquisitive" during their
		832	installation. You can set (and export!) any environment variable you
		833	want - some modules (such as Coro or EV) use environment variables
		834	for further tweaking.
812		835
813	"PERL_PREFIX"	836	"PERL_PREFIX"
814	The prefix where perl gets installed (default: $STATICPERL/perl),	837	The prefix where perl gets installed (default: $STATICPERL/perl),
815	i.e. where the bin and lib subdirectories will end up.	838	i.e. where the bin and lib subdirectories will end up.
816		839
…		…
834	these, and use a ~/.staticperlrc to override them.	857	these, and use a ~/.staticperlrc to override them.
835		858
836	Most of the variables override (or modify) the corresponding	859	Most of the variables override (or modify) the corresponding
837	Configure variable, except "PERL_CCFLAGS", which gets appended.	860	Configure variable, except "PERL_CCFLAGS", which gets appended.
838		861
839	You should have a look near the beginning of the staticperl script -	862	The default for "PERL_OPTIMIZE" is "-Os" (assuming gcc), and for
840	staticperl tries to default "PERL_OPTIMIZE" to some psace-saving	863	"PERL_LIBS" is "-lm -lcrypt", which should be good for most (but not
841	options suitable for newer gcc versions. For other compilers or	864	all) systems.
842	older versions you need to adjust these, for example, in your	865
843	~/.staticperlrc.	866	For other compilers or more customised optimisation settings, you
		867	need to adjust these, e.g. in your ~/.staticperlrc.
		868
		869	With gcc on x86 and amd64, you can get more space-savings by using:
		870
		871	-Os -ffunction-sections -fdata-sections -finline-limit=8 -mpush-args
		872	-mno-inline-stringops-dynamically -mno-align-stringops
		873
		874	And on x86 and pentium3 and newer (basically everything you might
		875	ever want to run on), adding these is even better for space-savings
		876	(use -mtune=core2 or something newer for much faster code, too):
		877
		878	-fomit-frame-pointer -march=pentium3 -mtune=i386
844		879
845	Variables you probably do not want to override	880	Variables you probably do not want to override
846	"MAKE"	881	"MAKE"
847	The make command to use - default is "make".	882	The make command to use - default is "make".
848		883
…		…
993		1028
994	bundle.ldopts	1029	bundle.ldopts
995	The linker options needed to link the final program.	1030	The linker options needed to link the final program.
996		1031
997	RUNTIME FUNCTIONALITY	1032	RUNTIME FUNCTIONALITY
998	Binaries created with "mkbundle"/"mkperl" contain extra functions, which	1033	Binaries created with "mkbundle"/"mkperl" contain extra functionality,
999	are required to access the bundled perl sources, but might be useful for	1034	mostly related to the extra files bundled in the binary (the virtual
1000	other purposes.	1035	filesystem). All of this data is statically compiled into the binary,
		1036	and accessing means copying it from a read-only section of your binary.
		1037	Data pages in this way is usually freed by the operating system, as it
		1038	isn't use more the onace.
1001		1039
		1040	VIRTUAL FILESYSTEM
		1041	Every bundle has a virtual filesystem. The only information stored in it
		1042	is the path and contents of each file that was bundled.
		1043
		1044	LAYOUT
		1045	Any path starting with an ampersand (&) or exclamation mark (!) are
		1046	reserved by staticperl. They must only be used as described in this
		1047	section.
		1048
		1049	! All files that typically cannot be loaded from memory (such as
		1050	dynamic objects or shared libraries), but have to reside in the
		1051	filesystem, are prefixed with !. Typically these files get written
		1052	out to some (semi-)temporary directory shortly after program
		1053	startup, or before being used.
		1054
		1055	!boot
		1056	The bootstrap file, if specified during bundling.
		1057
		1058	!auto/
		1059	Shared objects or dlls corresponding to dynamically-linked perl
		1060	extensions are stored with an !auto/ prefix.
		1061
		1062	!lib/
		1063	External shared libraries are stored in this directory.
		1064
		1065	any letter
		1066	Any path starting with a letter is a perl library file. For example,
		1067	Coro/AIO.pm corresponds to the file loaded by "use Coro::AIO", and
		1068	Coro/jit.pl corresponds to "require "Coro/jit.pl"".
		1069
		1070	Obviously, module names shouldn't start with any other characters
		1071	than letters :)
		1072
		1073	FUNCTIONS
		1074	$file = static::find $path
		1075	Returns the data associated with the given $path (e.g.
		1076	"Digest/MD5.pm", "auto/POSIX/autosplit.ix").
		1077
		1078	Returns "undef" if the file isn't embedded.
		1079
		1080	@paths = static::list
		1081	Returns the list of all paths embedded in this binary.
		1082
		1083	EXTRA FEATURES
1002	In addition, for the embedded loading of perl files to work, staticperl	1084	In addition, for the embedded loading of perl files to work, staticperl
1003	overrides the @INC array.	1085	overrides the @INC array.
1004
1005	$file = staticperl::find $path
1006	Returns the data associated with the given $path (e.g.
1007	"Digest/MD5.pm", "auto/POSIX/autosplit.ix"), which is basically the
1008	UNIX path relative to the perl library directory.
1009
1010	Returns "undef" if the file isn't embedded.
1011
1012	@paths = staticperl::list
1013	Returns the list of all paths embedded in this binary.
1014		1086
1015	FULLY STATIC BINARIES - UCLIBC AND BUILDROOT	1087	FULLY STATIC BINARIES - UCLIBC AND BUILDROOT
1016	To make truly static (Linux-) libraries, you might want to have a look	1088	To make truly static (Linux-) libraries, you might want to have a look
1017	at buildroot (<http://buildroot.uclibc.org/>).	1089	at buildroot (<http://buildroot.uclibc.org/>).
1018		1090
…		…
1039	stacks).	1111	stacks).
1040		1112
1041	If you use "linuxthreads.old", then you should also be aware that uClibc	1113	If you use "linuxthreads.old", then you should also be aware that uClibc
1042	shares "errno" between all threads when statically linking. See	1114	shares "errno" between all threads when statically linking. See
1043	<http://lists.uclibc.org/pipermail/uclibc/2010-June/044157.html> for a	1115	<http://lists.uclibc.org/pipermail/uclibc/2010-June/044157.html> for a
1044	workaround (And <https://bugs.uclibc.org/2089> for discussion).	1116	workaround (and <https://bugs.uclibc.org/2089> for discussion).
1045		1117
1046	"ccache" support is also recommended, especially if you want to play	1118	"ccache" support is also recommended, especially if you want to play
1047	around with buildroot options. Enabling the "miniperl" package will	1119	around with buildroot options. Enabling the "miniperl" package will
1048	probably enable all options required for a successful perl build.	1120	probably enable all options required for a successful perl build.
1049	staticperl itself additionally needs either "wget" (recommended, for	1121	staticperl itself additionally needs either "wget" (recommended, for
…		…
1057	it from working properly in a chroot - either use dash (and link it to	1129	it from working properly in a chroot - either use dash (and link it to
1058	/bin/sh inside the chroot) or link busybox to /bin/sh, using it's	1130	/bin/sh inside the chroot) or link busybox to /bin/sh, using it's
1059	built-in ash shell.	1131	built-in ash shell.
1060		1132
1061	Finally, you need /dev/null inside the chroot for many scripts to work -	1133	Finally, you need /dev/null inside the chroot for many scripts to work -
1062	cp /dev/null output/target/dev or bind-mounting your /dev will both	1134	either cp /dev/null output/target/dev or bind-mounting your /dev will
1063	provide this.	1135	provide this.
1064		1136
1065	After you have compiled and set up your buildroot target, you can copy	1137	After you have compiled and set up your buildroot target, you can copy
1066	staticperl from the "App::Staticperl" distribution or from your perl	1138	staticperl from the "App::Staticperl" distribution or from your perl bin
1067	f<bin> directory (if you installed it) into the output/target	1139	directory (if you installed it) into the output/target filesystem,
1068	filesystem, chroot inside and run it.	1140	chroot inside and run it.
1069		1141
1070	RECIPES / SPECIFIC MODULES	1142	RECIPES / SPECIFIC MODULES
1071	This section contains some common(?) recipes and information about	1143	This section contains some common(?) recipes and information about
1072	problems with some common modules or perl constructs that require extra	1144	problems with some common modules or perl constructs that require extra
1073	files to be included.	1145	files to be included.

Diff Legend

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

Comparing App-Staticperl/README (file contents): Revision 1.15 by root, Tue Jun 14 07:04:43 2011 UTC vs. Revision 1.16 by root, Mon Jul 18 07:34:48 2011 UTC

Diff Legend

Comparing App-Staticperl/README (file contents):
Revision 1.15 by root, Tue Jun 14 07:04:43 2011 UTC vs.
Revision 1.16 by root, Mon Jul 18 07:34:48 2011 UTC