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.11 by root, Tue Dec 7 10:40:39 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
… …
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.
85 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.
94
86=back 95=back
87 96
88=head1 HOW DOES IT WORK? 97=head1 HOW DOES IT WORK?
89 98
90Simple: F<staticperl> downloads, compile and installs a perl version of 99Simple: F<staticperl> downloads, compile and installs a perl version of
… …
184command by specifying all the directories with modules in them that you 193command by specifying all the directories with modules in them that you
185want to have built. 194want to have built.
186 195
187=item F<staticperl clean> 196=item F<staticperl clean>
188 197
189Runs F<make distclean> in the perl source directory (and potentially 198Deletes the perl source directory (and potentially cleans up other
190cleans up other intermediate files). This can be used to clean up 199intermediate files). This can be used to clean up files only needed for
191intermediate files without removing the installed perl interpreter. 200building perl, without removing the installed perl interpreter, or to
201force a re-build from scratch.
202
203At the moment, it doesn't delete downloaded tarballs.
192 204
193=item F<staticperl distclean> 205=item F<staticperl distclean>
194 206
195This wipes your complete F<~/.staticperl> directory. Be careful with this, 207This wipes your complete F<~/.staticperl> directory. Be careful with this,
196it nukes your perl download, perl sources, perl distribution and any 208it nukes your perl download, perl sources, perl distribution and any
… …
236(required by L<AnyEvent::HTTPD>) implements various URI schemes as extra 248(required by L<AnyEvent::HTTPD>) implements various URI schemes as extra
237modules - 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
238to include that module. I found out about these dependencies by carefully 250to include that module. I found out about these dependencies by carefully
239watching any error messages about missing modules... 251watching any error messages about missing modules...
240 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
241=head3 OPTION PROCESSING 263=head3 OPTION PROCESSING
242 264
243All options can be given as arguments on the command line (typically 265All options can be given as arguments on the command line (typically
244using 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
245specifying a lot of modules can make the command line very cumbersome, 267specifying a lot of modules can make the command line very cumbersome,
… …
304C<mkperl> command (instead of C<mkbundle>): 326C<mkperl> command (instead of C<mkbundle>):
305 327
306 # 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 :)
307 staticperl mkperl -Mcommon::sense 329 staticperl mkperl -Mcommon::sense
308 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
309=item --use module | -Mmodule 353=item --use module | -Mmodule
310 354
311Include the named module and all direct dependencies. This is done by 355Include the named module and all direct dependencies. This is done by
312C<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
313and 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
… …
415Any other argument is interpreted as a bundle specification file, which 459Any other argument is interpreted as a bundle specification file, which
416supports most long options (without extra quoting), one option per line. 460supports most long options (without extra quoting), one option per line.
417 461
418=back 462=back
419 463
420=head2 F<STATCPERL> CONFIGURATION AND HOOKS 464=head2 F<STATICPERL> CONFIGURATION AND HOOKS
421 465
422During (each) startup, F<staticperl> tries to source the following shell 466During (each) startup, F<staticperl> tries to source the following shell
423files in order: 467files in order:
424 468
425 /etc/staticperlrc 469 /etc/staticperlrc
… …
542 instcpan Anyevent::AIO AnyEvent::HTTPD 586 instcpan Anyevent::AIO AnyEvent::HTTPD
543 } 587 }
544 588
545=over 4 589=over 4
546 590
591=item preconfigure
592
593Called just before running F<./Configur> in the perl source
594directory. Current working directory is the perl source directory.
595
596This can be used to set any C<PERL_xxx> variables, which might be costly
597to compute.
598
547=item postconfigure 599=item postconfigure
548 600
549Called after configuring, but before building perl. Current working 601Called after configuring, but before building perl. Current working
550directory is the perl source directory. 602directory is the perl source directory.
551 603
552Could be used to tailor/patch config.sh (followed by F<./Configure -S>) or 604Could be used to tailor/patch config.sh (followed by F<sh Configure -S>)
553do any other modifications. 605or do any other modifications.
554 606
555=item postbuild 607=item postbuild
556 608
557Called after building, but before installing perl. Current working 609Called after building, but before installing perl. Current working
558directory is the perl source directory. 610directory is the perl source directory.

Diff Legend

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