ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/App-Staticperl/staticperl.pod
(Generate patch)

Comparing App-Staticperl/staticperl.pod (file contents):
Revision 1.12 by root, Tue Dec 7 13:23:07 2010 UTC vs.
Revision 1.16 by root, Wed Dec 8 23:03:21 2010 UTC

… …
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
20Typical Examples: 21Typical 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
30This script helps you creating single-file perl interpreters, or embedding 33This script helps you to create single-file perl interpreters
31a perl interpreter in your applications. Single-file means that it is 34or applications, or embedding a perl interpreter in your
32fully self-contained - no separate shared objects, no autoload fragments, 35applications. Single-file means that it is fully self-contained - no
33no .pm or .pl files are needed. And when linking statically, you can 36separate shared objects, no autoload fragments, no .pm or .pl files are
34create (or embed) a single file that contains perl interpreter, libc, all 37needed. And when linking statically, you can create (or embed) a single
35the modules you need and all the libraries you need. 38file that contains perl interpreter, libc, all the modules you need, all
39the libraries you need and of course your actual program.
36 40
37With F<uClibc> and F<upx> on x86, you can create a single 500kb binary 41With F<uClibc> and F<upx> on x86, you can create a single 500kb binary
38that contains perl and 100 modules such as POSIX, AnyEvent, EV, IO::AIO, 42that contains perl and 100 modules such as POSIX, AnyEvent, EV, IO::AIO,
39Coro and so on. Or any other choice of modules. 43Coro and so on. Or any other choice of modules.
40 44
… …
80 84
81Maintaining your own custom perl build can be a pain in the ass, and while 85Maintaining your own custom perl build can be a pain in the ass, and while
82F<staticperl> tries to make this easy, it still requires a custom perl 86F<staticperl> tries to make this easy, it still requires a custom perl
83build and possibly fiddling with some modules. PAR is likely to produce 87build and possibly fiddling with some modules. PAR is likely to produce
84results faster. 88results faster.
89
90Ok, PAR never has worked for me out of the box, and for some people,
91F<staticperl> does work out of the box, as they don't count "fiddling with
92module use lists" against it, but nevertheless, F<staticperl> is certainly
93a bit more difficult to use.
85 94
86=back 95=back
87 96
88=head1 HOW DOES IT WORK? 97=head1 HOW DOES IT WORK?
89 98
… …
239(required by L<AnyEvent::HTTPD>) implements various URI schemes as extra 248(required by L<AnyEvent::HTTPD>) implements various URI schemes as extra
240modules - since L<AnyEvent::HTTPD> only needs C<http> URIs, we only need 249modules - since L<AnyEvent::HTTPD> only needs C<http> URIs, we only need
241to include that module. I found out about these dependencies by carefully 250to include that module. I found out about these dependencies by carefully
242watching any error messages about missing modules... 251watching any error messages about missing modules...
243 252
253Instead of building a new perl binary, you can also build a standalone
254application:
255
256 # build the app
257 staticperl mkapp app --boot eg/httpd \
258 -MAnyEvent::Impl::Perl -MAnyEvent::HTTPD -MURI::http
259
260 # run it
261 ./app
262
244=head3 OPTION PROCESSING 263=head3 OPTION PROCESSING
245 264
246All options can be given as arguments on the command line (typically 265All options can be given as arguments on the command line (typically
247using long (e.g. C<--verbose>) or short option (e.g. C<-v>) style). Since 266using long (e.g. C<--verbose>) or short option (e.g. C<-v>) style). Since
248specifying a lot of modules can make the command line very cumbersome, 267specifying a lot of modules can make the command line very cumbersome,
… …
307C<mkperl> command (instead of C<mkbundle>): 326C<mkperl> command (instead of C<mkbundle>):
308 327
309 # build a new ./perl with only common::sense in it - very small :) 328 # build a new ./perl with only common::sense in it - very small :)
310 staticperl mkperl -Mcommon::sense 329 staticperl mkperl -Mcommon::sense
311 330
331=item --app name
332
333After writing out the bundle files, try to link a new standalone
334program. It will be called C<name>, and the bundle files get removed after
335linking it.
336
337The difference to the (mutually exclusive) C<--perl> option is that the
338binary created by this option will not try to act as a perl interpreter -
339instead it will simply initialise the perl interpreter, clean it up and
340exit.
341
342This switch is automatically used when F<staticperl> is invoked with the
343C<mkapp> command (instead of C<mkbundle>):
344
345To let it do something useful you I<must> add some boot code, e.g. with
346the C<--boot> option.
347
348Example: create a standalone perl binary that will execute F<appfile> when
349it is started.
350
351 staticperl mkbundle --app myexe --boot appfile
352
312=item --use module | -Mmodule 353=item --use module | -Mmodule
313 354
314Include the named module and all direct dependencies. This is done by 355Include the named module and all direct dependencies. This is done by
315C<require>'ing the module in a subprocess and tracing which other modules 356C<require>'ing the module in a subprocess and tracing which other modules
316and files it actually loads. If the module uses L<AutoLoader>, then all 357and files it actually loads. If the module uses L<AutoLoader>, then all
… …
418Any other argument is interpreted as a bundle specification file, which 459Any other argument is interpreted as a bundle specification file, which
419supports most long options (without extra quoting), one option per line. 460supports most long options (without extra quoting), one option per line.
420 461
421=back 462=back
422 463
423=head2 F<STATCPERL> CONFIGURATION AND HOOKS 464=head2 F<STATICPERL> CONFIGURATION AND HOOKS
424 465
425During (each) startup, F<staticperl> tries to source the following shell 466During (each) startup, F<staticperl> tries to source the following shell
426files in order: 467files in order:
427 468
428 /etc/staticperlrc 469 /etc/staticperlrc

Diff Legend

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