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

Comparing App-Staticperl/staticperl.pod (file contents):
Revision 1.31 by root, Thu Dec 23 14:16:25 2010 UTC vs.
Revision 1.38 by root, Fri Mar 18 19:49:04 2011 UTC

…		…
20		20
21	Typical Examples:	21	Typical Examples:
22		22
23	staticperl install # fetch, configure, build and install perl	23	staticperl install # fetch, configure, build and install perl
24	staticperl cpan # run interactive cpan shell	24	staticperl cpan # run interactive cpan shell
25	staticperl mkperl -M '"Config_heavy.pl"' # build a perl that supports -V	25	staticperl mkperl -MConfig_heavy.pl # build a perl that supports -V
26	staticperl mkperl -MAnyEvent::Impl::Perl -MAnyEvent::HTTPD -MURI -MURI::http	26	staticperl mkperl -MAnyEvent::Impl::Perl -MAnyEvent::HTTPD -MURI -MURI::http
27	# 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	28	staticperl mkapp myapp --boot mainprog mymodules
29	# build a binary "myapp" from mainprog and mymodules	29	# build a binary "myapp" from mainprog and mymodules
30		30
…		…
139	with creating binaries and bundle files.	139	with creating binaries and bundle files.
140		140
141	=head2 PHASE 1 COMMANDS: INSTALLING PERL	141	=head2 PHASE 1 COMMANDS: INSTALLING PERL
142		142
143	The most important command is F<install>, which does basically	143	The most important command is F<install>, which does basically
144	everything. The default is to download and install perl 5.12.2 and a few	144	everything. The default is to download and install perl 5.12.3 and a few
145	modules required by F<staticperl> itself, but all this can (and should) be	145	modules required by F<staticperl> itself, but all this can (and should) be
146	changed - see L<CONFIGURATION>, below.	146	changed - see L<CONFIGURATION>, below.
147		147
148	The command	148	The command
149		149
…		…
252		252
253	# first make sure we have perl and the required modules	253	# first make sure we have perl and the required modules
254	staticperl instcpan AnyEvent::HTTPD	254	staticperl instcpan AnyEvent::HTTPD
255		255
256	# now build the perl	256	# now build the perl
257	staticperl mkperl -M'"Config_heavy.pl"' -MAnyEvent::Impl::Perl \	257	staticperl mkperl -MConfig_heavy.pl -MAnyEvent::Impl::Perl \
258	-MAnyEvent::HTTPD -MURI::http \	258	-MAnyEvent::HTTPD -MURI::http \
259	--add 'eg/httpd httpd.pm'	259	--add 'eg/httpd httpd.pm'
260		260
261	# finally, invoke it	261	# finally, invoke it
262	./perl -Mhttpd	262	./perl -Mhttpd
…		…
381		381
382	=over 4	382	=over 4
383		383
384	=item C<--use> F<module> \| C<-M>F<module>	384	=item C<--use> F<module> \| C<-M>F<module>
385		385
386	Include the named module and trace direct dependencies. This is done by	386	Include the named module or perl library and trace direct
387	C<require>'ing the module in a subprocess and tracing which other modules	387	dependencies. This is done by loading the module in a subprocess and
388	and files it actually loads.	388	tracing which other modules and files it actually loads.
389		389
390	Example: include AnyEvent and AnyEvent::Impl::Perl.	390	Example: include AnyEvent and AnyEvent::Impl::Perl.
391		391
392	staticperl mkbundle --use AnyEvent --use AnyEvent::Impl::Perl	392	staticperl mkbundle --use AnyEvent --use AnyEvent::Impl::Perl
393		393
394	Sometimes you want to load old-style "perl libraries" (F<.pl> files),	394	Sometimes you want to load old-style "perl libraries" (F<.pl> files), or
395	or maybe other weirdly named files. To do that, you need to quote	395	maybe other weirdly named files. To support this, the C<--use> option
396	the name in single or double quotes (this is because F<staticperl>	396	actually tries to do what you mean, depending on the string you specify:
397	I<literally> just adds the string after the C<require> - which acts	397
398	different when confronted with quoted vs. unquoted strings). When given on	398	=over 4
399	the command line, you probably need to quote once more to avoid your shell	399
400	interpreting it. Common cases that need this are F<Config_heavy.pl> and	400	=item a possibly valid module name, e.g. F<common::sense>, F<Carp>,
401	F<utf8_heavy.pl>.	401	F<Coro::Mysql>.
		402
		403	If the string contains no quotes, no F</> and no F<.>, then C<--use>
		404	assumes that it is a normal module name. It will create a new package and
		405	evaluate a C<use module> in it, i.e. it will load the package and do a
		406	default import.
		407
		408	The import step is done because many modules trigger more dependencies
		409	when something is imported than without.
		410
		411	=item anything that contains F</> or F<.> characters,
		412	e.g. F<utf8_heavy.pl>, F<Module/private/data.pl>.
		413
		414	The string will be quoted and passed to require, as if you used C<require
		415	$module>. Nothing will be imported.
		416
		417	=item "path" or 'path', e.g. C<"utf8_heavy.pl">.
		418
		419	If you enclose the name into single or double quotes, then the quotes will
		420	be removed and the resulting string will be passed to require. This syntax
		421	is form compatibility with older versions of staticperl and should not be
		422	used anymore.
		423
		424	=back
		425
		426	Example: C<use> AnyEvent::Socket, once using C<use> (importing the
		427	symbols), and once via C<require>, not importing any symbols. The first
		428	form is preferred as many modules load some extra dependencies when asked
		429	to export symbols.
		430
		431	staticperl mkbundle -MAnyEvent::Socket # use + import
		432	staticperl mkbundle -MAnyEvent/Socket.pm # require only
402		433
403	Example: include the required files for F<perl -V> to work in all its	434	Example: include the required files for F<perl -V> to work in all its
404	glory (F<Config.pm> is included automatically by this).	435	glory (F<Config.pm> is included automatically by the dependency tracker).
405		436
406	# bourne shell	437	# shell command
407	staticperl mkbundle --use '"Config_heavy.pl"'	438	staticperl mkbundle -MConfig_heavy.pl
408		439
409	# bundle specification file	440	# bundle specification file
410	use "Config_heavy.pl"	441	use Config_heavy.pl
411		442
412	The C<-M>module syntax is included as a convenience that might be easier	443	The C<-M>module syntax is included as a convenience that might be easier
413	to remember than C<--use> - it's the same switch as perl itself uses	444	to remember than C<--use> - it's the same switch as perl itself uses
414	to load modules. Or maybe it confuses people. Time will tell. Or maybe	445	to load modules. Or maybe it confuses people. Time will tell. Or maybe
415	not. Sigh.	446	not. Sigh.
…		…
420	code, or maybe one of the modules you use need a special use statement. In	451	code, or maybe one of the modules you use need a special use statement. In
421	that case, you can use C<--eval> to execute some perl snippet or set some	452	that case, you can use C<--eval> to execute some perl snippet or set some
422	variables or whatever you need. All files C<require>'d or C<use>'d while	453	variables or whatever you need. All files C<require>'d or C<use>'d while
423	executing the snippet are included in the final bundle.	454	executing the snippet are included in the final bundle.
424		455
425	Keep in mind that F<mkbundle> will only C<require> the modules named	456	Keep in mind that F<mkbundle> will not import any symbols from the modules
426	by the C<--use> option, so do not expect the symbols from modules you	457	named by the C<--use> option, so do not expect the symbols from modules
427	C<--use>'d earlier on the command line to be available.	458	you C<--use>'d earlier on the command line to be available.
428		459
429	Example: force L<AnyEvent> to detect a backend and therefore include it	460	Example: force L<AnyEvent> to detect a backend and therefore include it
430	in the final bundle.	461	in the final bundle.
431		462
432	staticperl mkbundle --eval 'use AnyEvent; AnyEvent::detect'	463	staticperl mkbundle --eval 'use AnyEvent; AnyEvent::detect'
…		…
467	--incglob '/unicore/**.pl'	498	--incglob '/unicore/**.pl'
468		499
469	=item C<--add> F<file> \| C<--add> "F<file> alias"	500	=item C<--add> F<file> \| C<--add> "F<file> alias"
470		501
471	Adds the given (perl) file into the bundle (and optionally call it	502	Adds the given (perl) file into the bundle (and optionally call it
472	"alias"). The F<file> is either an absolute path or a path relative to	503	"alias"). The F<file> is either an absolute path or a path relative to the
473	the current directory. If an alias is specified, then this is the name it	504	current directory. If an alias is specified, then this is the name it will
474	will use for C<@INC> searches, otherwise the F<file> will be used as the	505	use for C<@INC> searches, otherwise the path F<file> will be used as the
475	internal name.	506	internal name.
476		507
477	This switch is used to include extra files into the bundle.	508	This switch is used to include extra files into the bundle.
478		509
479	Example: embed the file F<httpd> in the current directory as F<httpd.pm>	510	Example: embed the file F<httpd> in the current directory as F<httpd.pm>
480	when creating the bundle.	511	when creating the bundle.
481		512
482	staticperl mkperl --add "httpd httpd.pm"	513	staticperl mkperl --add "httpd httpd.pm"
		514
		515	# can be accessed via "use httpd"
		516
		517	Example: add a file F<initcode> from the current directory.
		518
		519	staticperl mkperl --add 'initcode &initcode'
		520
		521	# can be accessed via "do '&initcode'"
483		522
484	Example: add local files as extra modules in the bundle.	523	Example: add local files as extra modules in the bundle.
485		524
486	# specification file	525	# specification file
487	add file1 myfiles/file1.pm	526	add file1 myfiles/file1.pm
…		…
497		536
498	Just like C<--add>, except that it treats the file as binary and adds it	537	Just like C<--add>, except that it treats the file as binary and adds it
499	without any postprocessing (perl files might get stripped to reduce their	538	without any postprocessing (perl files might get stripped to reduce their
500	size).	539	size).
501		540
502	You should probably add a C</> prefix to avoid clashing with embedded perl	541	If you specify an alias you should probably add a C<&> prefix to avoid
503	files (whose paths do not start with C</>), and/or use a special directory	542	clashing with embedded perl files (whose paths never start with C<&>),
504	prefix, such as C</res/name>.	543	and/or use a special directory prefix, such as C<&res/name>.
505		544
506	You can later get a copy of these files by calling C<staticperl::find	545	You can later get a copy of these files by calling C<staticperl::find
507	"alias">.	546	"alias">.
508		547
509	An alternative way to embed binary files is to convert them to perl and	548	An alternative way to embed binary files is to convert them to perl and
…		…
664	The difference to the (mutually exclusive) C<--perl> option is that the	703	The difference to the (mutually exclusive) C<--perl> option is that the
665	binary created by this option will not try to act as a perl interpreter -	704	binary created by this option will not try to act as a perl interpreter -
666	instead it will simply initialise the perl interpreter, clean it up and	705	instead it will simply initialise the perl interpreter, clean it up and
667	exit.	706	exit.
668		707
669	This means that, by default, it will do nothing but burna few CPU cycles	708	This means that, by default, it will do nothing but burn a few CPU cycles
670	- for it to do something useful you I<must> add some boot code, e.g. with	709	- for it to do something useful you I<must> add some boot code, e.g. with
671	the C<--boot> option.	710	the C<--boot> option.
672		711
673	Example: create a standalone perl binary called F<./myexe> that will	712	Example: create a standalone perl binary called F<./myexe> that will
674	execute F<appfile> when it is started.	713	execute F<appfile> when it is started.
675		714
676	staticperl mkbundle --app myexe --boot appfile	715	staticperl mkbundle --app myexe --boot appfile
		716
		717	=item C<--ignore-env>
		718
		719	Generates extra code to unset some environment variables before
		720	initialising/running perl. Perl supports a lot of environment variables
		721	that might alter execution in ways that might be undesirablre for
		722	standalone applications, and this option removes those known to cause
		723	trouble.
		724
		725	Specifically, these are removed:
		726
		727	C<PERL_HASH_SEED_DEBUG> and C<PERL_DEBUG_MSTATS> can cause underaible
		728	output, C<PERL5OPT>, C<PERL_DESTRUCT_LEVEL>, C<PERL_HASH_SEED> and
		729	C<PERL_SIGNALS> can alter execution significantly, and C<PERL_UNICODE>,
		730	C<PERLIO_DEBUG> and C<PERLIO> can affect input and output.
		731
		732	The variables C<PERL_LIB> and C<PERL5_LIB> are always ignored because the
		733	startup code used by F<staticperl> overrides C<@INC> in all cases.
		734
		735	This option will not make your program more secure (unless you are
		736	running with elevated privileges), but it will reduce the surprise effect
		737	when a user has these environment variables set and doesn't expect your
		738	standalone program to act like a perl interpreter.
677		739
678	=item C<--static>	740	=item C<--static>
679		741
680	Add C<-static> to F<bundle.ldopts>, which means a fully static (if	742	Add C<-static> to F<bundle.ldopts>, which means a fully static (if
681	supported by the OS) executable will be created. This is not immensely	743	supported by the OS) executable will be created. This is not immensely
…		…
817	installation, you can set any environment variable you want - some modules	879	installation, you can set any environment variable you want - some modules
818	(such as L<Coro> or L<EV>) use environment variables for further tweaking.	880	(such as L<Coro> or L<EV>) use environment variables for further tweaking.
819		881
820	=item C<PERL_VERSION>	882	=item C<PERL_VERSION>
821		883
822	The perl version to install - default is currently C<5.12.2>, but C<5.8.9>	884	The perl version to install - default is currently C<5.12.3>, but C<5.8.9>
823	is also a good choice (5.8.9 is much smaller than 5.12.2, while 5.10.1 is	885	is also a good choice (5.8.9 is much smaller than 5.12.3, while 5.10.1 is
824	about as big as 5.12.2).	886	about as big as 5.12.3).
825		887
826	=item C<PERL_PREFIX>	888	=item C<PERL_PREFIX>
827		889
828	The prefix where perl gets installed (default: F<$STATICPERL/perl>),	890	The prefix where perl gets installed (default: F<$STATICPERL/perl>),
829	i.e. where the F<bin> and F<lib> subdirectories will end up.	891	i.e. where the F<bin> and F<lib> subdirectories will end up.
…		…
877	=head3 OVERRIDABLE HOOKS	939	=head3 OVERRIDABLE HOOKS
878		940
879	In addition to environment variables, it is possible to provide some	941	In addition to environment variables, it is possible to provide some
880	shell functions that are called at specific times. To provide your own	942	shell functions that are called at specific times. To provide your own
881	commands, just define the corresponding function.	943	commands, just define the corresponding function.
		944
		945	The actual order in which hooks are invoked during a full install
		946	from scratch is C<preconfigure>, C<patchconfig>, C<postconfigure>,
		947	C<postbuild>, C<postinstall>.
882		948
883	Example: install extra modules from CPAN and from some directories	949	Example: install extra modules from CPAN and from some directories
884	at F<staticperl install> time.	950	at F<staticperl install> time.
885		951
886	postinstall() {	952	postinstall() {
…		…
893		959
894	=over 4	960	=over 4
895		961
896	=item preconfigure	962	=item preconfigure
897		963
898	Called just before running F<./Configur> in the perl source	964	Called just before running F<./Configure> in the perl source
899	directory. Current working directory is the perl source directory.	965	directory. Current working directory is the perl source directory.
900		966
901	This can be used to set any C<PERL_xxx> variables, which might be costly	967	This can be used to set any C<PERL_xxx> variables, which might be costly
902	to compute.	968	to compute.
903		969
		970	=item patchconfig
		971
		972	Called after running F<./Configure> in the perl source directory to create
		973	F<./config.sh>, but before running F<./Configure -S> to actually apply the
		974	config. Current working directory is the perl source directory.
		975
		976	Can be used to tailor/patch F<config.sh> or do any other modifications.
		977
904	=item postconfigure	978	=item postconfigure
905		979
906	Called after configuring, but before building perl. Current working	980	Called after configuring, but before building perl. Current working
907	directory is the perl source directory.	981	directory is the perl source directory.
908
909	Could be used to tailor/patch config.sh (followed by F<sh Configure -S>)
910	or do any other modifications.
911		982
912	=item postbuild	983	=item postbuild
913		984
914	Called after building, but before installing perl. Current working	985	Called after building, but before installing perl. Current working
915	directory is the perl source directory.	986	directory is the perl source directory.
…		…
953	A header file that contains the prototypes of the few symbols "exported"	1024	A header file that contains the prototypes of the few symbols "exported"
954	by bundle.c, and also exposes the perl headers to the application.	1025	by bundle.c, and also exposes the perl headers to the application.
955		1026
956	=over 4	1027	=over 4
957		1028
958	=item staticperl_init ()	1029	=item staticperl_init (xs_init = 0)
959		1030
960	Initialises the perl interpreter. You can use the normal perl functions	1031	Initialises the perl interpreter. You can use the normal perl functions
961	after calling this function, for example, to define extra functions or	1032	after calling this function, for example, to define extra functions or
962	to load a .pm file that contains some initialisation code, or the main	1033	to load a .pm file that contains some initialisation code, or the main
963	program function:	1034	program function:
…		…
970	}	1041	}
971		1042
972	static void	1043	static void
973	run_myapp(void)	1044	run_myapp(void)
974	{	1045	{
975	staticperl_init ();	1046	staticperl_init (0);
976	newXSproto ("myapp::xsfunction", xsfunction, __FILE__, "$$;$");	1047	newXSproto ("myapp::xsfunction", xsfunction, __FILE__, "$$;$");
977	eval_pv ("require myapp::main", 1); // executes "myapp/main.pm"	1048	eval_pv ("require myapp::main", 1); // executes "myapp/main.pm"
978	}	1049	}
979		1050
		1051	When your bootcode already wants to access some XS functions at
		1052	compiletime, then you need to supply an C<xs_init> function pointer that
		1053	is called as soon as perl is initialised enough to define XS functions,
		1054	but before the preamble code is executed:
		1055
		1056	static void
		1057	xs_init (pTHX)
		1058	{
		1059	newXSproto ("myapp::xsfunction", xsfunction, __FILE__, "$$;$");
		1060	}
		1061
		1062	static void
		1063	run_myapp(void)
		1064	{
		1065	staticperl_init (xs_init);
		1066	}
		1067
		1068	=item staticperl_cleanup ()
		1069
		1070	In the unlikely case that you want to destroy the perl interpreter, here
		1071	is the corresponding function.
		1072
980	=item staticperl_xs_init (pTHX)	1073	=item staticperl_xs_init (pTHX)
981		1074
982	Sometimes you need direct control over C<perl_parse> and C<perl_run>, in	1075	Sometimes you need direct control over C<perl_parse> and C<perl_run>, in
983	which case you do not want to use C<staticperl_init> but call them on your	1076	which case you do not want to use C<staticperl_init> but call them on your
984	own.	1077	own.
985		1078
986	Then you need this function - either pass it directly as the C<xs_init>	1079	Then you need this function - either pass it directly as the C<xs_init>
987	function to C<perl_parse>, or call it from your own C<xs_init> function.	1080	function to C<perl_parse>, or call it as one of the first things from your
988		1081	own C<xs_init> function.
989	=item staticperl_cleanup ()
990
991	In the unlikely case that you want to destroy the perl interpreter, here
992	is the corresponding function.
993		1082
994	=item PerlInterpreter *staticperl	1083	=item PerlInterpreter *staticperl
995		1084
996	The perl interpreter pointer used by staticperl. Not normally so useful,	1085	The perl interpreter pointer used by staticperl. Not normally so useful,
997	but there it is.	1086	but there it is.
…		…
1104		1193
1105	Some functionality in the utf8 module, such as swash handling (used	1194	Some functionality in the utf8 module, such as swash handling (used
1106	for unicode character ranges in regexes) is implemented in the	1195	for unicode character ranges in regexes) is implemented in the
1107	C<"utf8_heavy.pl"> library:	1196	C<"utf8_heavy.pl"> library:
1108		1197
1109	-M'"utf8_heavy.pl"'	1198	-Mutf8_heavy.pl
1110		1199
1111	Many Unicode properties in turn are defined in separate modules,	1200	Many Unicode properties in turn are defined in separate modules,
1112	such as C<"unicore/Heavy.pl"> and more specific data tables such as	1201	such as C<"unicore/Heavy.pl"> and more specific data tables such as
1113	C<"unicore/To/Digit.pl"> or C<"unicore/lib/Perl/Word.pl">. These tables	1202	C<"unicore/To/Digit.pl"> or C<"unicore/lib/Perl/Word.pl">. These tables
1114	are big (7MB uncompressed, although F<staticperl> contains special	1203	are big (7MB uncompressed, although F<staticperl> contains special

Diff Legend

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

Comparing App-Staticperl/staticperl.pod (file contents): Revision 1.31 by root, Thu Dec 23 14:16:25 2010 UTC vs. Revision 1.38 by root, Fri Mar 18 19:49:04 2011 UTC

Diff Legend

Comparing App-Staticperl/staticperl.pod (file contents):
Revision 1.31 by root, Thu Dec 23 14:16:25 2010 UTC vs.
Revision 1.38 by root, Fri Mar 18 19:49:04 2011 UTC