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.2 by root, Mon Dec 6 20:53:44 2010 UTC vs.
Revision 1.7 by root, Mon Dec 6 21:21:44 2010 UTC

1=head1 NAME 1=head1 NAME
2 2
3staticperl - perl, libc, 50 modules all in one 500kb file 3staticperl - perl, libc, 50 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
… …
26 # build a perl with the above modules linked in 26 # build a perl with the above modules linked in
27 27
28=head1 DESCRIPTION 28=head1 DESCRIPTION
29 29
30This script helps you creating single-file perl interpreters, or embedding 30This script helps you creating single-file perl interpreters, or embedding
31a pelr interpreter in your apps. Single-file means that it is fully 31a perl interpreter in your applications. Single-file means that it is
32self-contained - no separate shared objects, no autoload fragments, no .pm 32fully self-contained - no separate shared objects, no autoload fragments,
33or .pl files are needed. And when linking statically, you can create (or 33no .pm or .pl files are needed. And when linking statically, you can
34embed) a single file that contains perl interpreter, libc, all the modules 34create (or embed) a single file that contains perl interpreter, libc, all
35you need and all the libraries you need. 35the modules you need and all the libraries you need.
36 36
37With uclibc and upx on x86, you can create a single 500kb binary that 37With F<uClibc> and F<upx> on x86, you can create a single 500kb binary that
38contains perl and 50 modules such as AnyEvent, EV, IO::AIO, Coro and so 38contains perl and 50 modules such as AnyEvent, EV, IO::AIO, Coro and so
39on. Or any other choice of modules. 39on. Or any other choice of modules.
40 40
41The created files do not need write access to the filesystem (like PAR 41The created files do not need write access to the file system (like PAR
42does). In fact, since this script is in many ways similar to PAR::Packer, 42does). In fact, since this script is in many ways similar to PAR::Packer,
43here are the differences: 43here are the differences:
44 44
45=over 4 45=over 4
46 46
… …
65F<staticperl> loads all required files directly from memory. There is no 65F<staticperl> loads all required files directly from memory. There is no
66need to unpack files into a temporary directory. 66need to unpack files into a temporary directory.
67 67
68=item * More control over included files. 68=item * More control over included files.
69 69
70PAR tries to be maintainance and hassle-free - it tries to include more files 70PAR tries to be maintenance and hassle-free - it tries to include more
71than necessary to make sure everything works out of the box. The extra files 71files than necessary to make sure everything works out of the box. The
72(such as the unicode database) can take substantial amounts of memory and filesize. 72extra files (such as the unicode database) can take substantial amounts of
73memory and file size.
73 74
74With F<staticperl>, the burden is mostly with the developer - only direct 75With F<staticperl>, the burden is mostly with the developer - only direct
75compile-time dependencies and L<AutoLoader> are handled automatically. 76compile-time dependencies and L<AutoLoader> are handled automatically.
76This means the modules to include often need to be tweaked manually. 77This means the modules to include often need to be tweaked manually.
77 78
… …
88 89
89Simple: F<staticperl> downloads, compile and installs a perl version of 90Simple: F<staticperl> downloads, compile and installs a perl version of
90your choice in F<~/.staticperl>. You can add extra modules either by 91your choice in F<~/.staticperl>. You can add extra modules either by
91letting F<staticperl> install them for you automatically, or by using CPAN 92letting F<staticperl> install them for you automatically, or by using CPAN
92and doing it interactively. This usually takes 5-10 minutes, depending on 93and doing it interactively. This usually takes 5-10 minutes, depending on
93the speed of your computer and your internet conenction. 94the speed of your computer and your internet connection.
94 95
95It is possible to do program development at this stage, too. 96It is possible to do program development at this stage, too.
96 97
97Afterwards, you create a list of files and modules you want to include, 98Afterwards, you create a list of files and modules you want to include,
98and then either build a new perl binary (that acts just like a normla perl 99and then either build a new perl binary (that acts just like a normal perl
99except everything is compiled in), or you create bundle files (basically C 100except everything is compiled in), or you create bundle files (basically C
100sources you can use to embed all files into your project). 101sources you can use to embed all files into your project).
101 102
102This step is very fast (a few seconds if PPI is not used for stripping, 103This step is very fast (a few seconds if PPI is not used for stripping,
103more seconds otherwise, as PPI is very slow), and can be tweaked and 104more seconds otherwise, as PPI is very slow), and can be tweaked and
… …
134perl interpreter if required. 135perl interpreter if required.
135 136
136Most of the following commands simply run one or more steps of this 137Most of the following commands simply run one or more steps of this
137sequence. 138sequence.
138 139
139To force recompilation or reinstalaltion, you need to run F<staticperl 140To force recompilation or reinstallation, you need to run F<staticperl
140distclean> first. 141distclean> first.
141 142
142=over 4 143=over 4
143 144
144=item F<staticperl fetch> 145=item F<staticperl fetch>
… …
154Builds the configured perl sources, potentially after automatically 155Builds the configured perl sources, potentially after automatically
155configuring them. 156configuring them.
156 157
157=item F<staticperl install> 158=item F<staticperl install>
158 159
159Wipes the perl installation directory (usually F<~/.staticperl/perl>) and installs 160Wipes the perl installation directory (usually F<~/.staticperl/perl>) and
160the perl distribution, potentially aftering building it first. 161installs the perl distribution, potentially after building it first.
161 162
162=item F<staticperl cpan> [args...] 163=item F<staticperl cpan> [args...]
163 164
164Starts an interactive CPAN shell that you cna use to install further 165Starts an interactive CPAN shell that you can use to install further
165modules. Installs the perl first if neccessary, but apart from that, 166modules. Installs the perl first if necessary, but apart from that,
166no magic is involved: you could just as well run it manually via 167no magic is involved: you could just as well run it manually via
167F<~/.staticperl/perl/bin/cpan>. 168F<~/.staticperl/perl/bin/cpan>.
168 169
169Any additional arguments are simply passed to the F<cpan> command. 170Any additional arguments are simply passed to the F<cpan> command.
170 171
… …
177 staticperl instcpan EV AnyEvent::HTTPD Coro 178 staticperl instcpan EV AnyEvent::HTTPD Coro
178 179
179=item F<staticperl instsrc> directory... 180=item F<staticperl instsrc> directory...
180 181
181In the unlikely case that you have unpacked perl modules around and want 182In the unlikely case that you have unpacked perl modules around and want
182to install from these instead of from CPAN, you cna do this using this 183to install from these instead of from CPAN, you can do this using this
183command by specifying all the directories with modules in them that you 184command by specifying all the directories with modules in them that you
184want to have built. 185want to have built.
185 186
186=item F<staticperl clean> 187=item F<staticperl clean>
187 188
… …
210In the oh so unlikely case of something not working here, you 211In the oh so unlikely case of something not working here, you
211can run the script manually as well (by default it is written to 212can run the script manually as well (by default it is written to
212F<~/.staticperl/mkbundle>). 213F<~/.staticperl/mkbundle>).
213 214
214F<mkbundle> is a more conventional command and expect the argument 215F<mkbundle> is a more conventional command and expect the argument
215syntax commonly used on unix clones. For example, this command builds 216syntax commonly used on UNIX clones. For example, this command builds
216a new F<perl> binary and includes F<Config.pm> (for F<perl -V>), 217a new F<perl> binary and includes F<Config.pm> (for F<perl -V>),
217F<AnyEvent::HTTPD>, F<URI> and a custom F<httpd> script (from F<eg/httpd> 218F<AnyEvent::HTTPD>, F<URI> and a custom F<httpd> script (from F<eg/httpd>
218in this distribution): 219in this distribution):
219 220
220 # first make sure we have perl and the required modules 221 # first make sure we have perl and the required modules
… …
229 ./perl -Mhttpd 230 ./perl -Mhttpd
230 231
231As you can see, things are not quite as trivial: the L<Config> module has 232As you can see, things are not quite as trivial: the L<Config> module has
232a hidden dependency which is not even a perl module (F<Config_heavy.pl>), 233a hidden dependency which is not even a perl module (F<Config_heavy.pl>),
233L<AnyEvent> needs at least one event loop backend that we have to 234L<AnyEvent> needs at least one event loop backend that we have to
234specifymanually (here L<AnyEvent::Impl::Perl>), and the F<URI> module 235specify manually (here L<AnyEvent::Impl::Perl>), and the F<URI> module
235(required by L<AnyEvent::HTTPD>) implements various URI schemes as extra 236(required by L<AnyEvent::HTTPD>) implements various URI schemes as extra
236modules - since L<AnyEvent::HTTPD> only needs C<http> URIs, we only need 237modules - since L<AnyEvent::HTTPD> only needs C<http> URIs, we only need
237to include that module. 238to include that module. I found out about these dependencies by carefully
239watching any error messages about missing modules...
238 240
239=head3 OPTION PROCESSING 241=head3 OPTION PROCESSING
240 242
241All options can be given as arguments on the commandline (typically using 243All options can be given as arguments on the command line (typically
242long (e.g. C<--verbose>) or short option (e.g. C<-v>) style). Since 244using long (e.g. C<--verbose>) or short option (e.g. C<-v>) style). Since
243specifying a lot of modules can make the commandlien very cumbersome, 245specifying a lot of modules can make the command line very cumbersome,
244you can put all long options into a "bundle specification file" (with or 246you can put all long options into a "bundle specification file" (with or
245without C<--> prefix) and specify this bundle file instead. 247without C<--> prefix) and specify this bundle file instead.
246 248
247For example, the command given earlier could also look like this: 249For example, the command given earlier could also look like this:
248 250
… …
255 use AnyEvent::HTTPD 257 use AnyEvent::HTTPD
256 use URI::http 258 use URI::http
257 add eg/httpd httpd.pm 259 add eg/httpd httpd.pm
258 260
259All options that specify modules or files to be added are processed in the 261All options that specify modules or files to be added are processed in the
260order given on the commandline (that affects the C<--use> and C<--eval> 262order given on the command line (that affects the C<--use> and C<--eval>
261options at the moment). 263options at the moment).
262 264
263=head3 MKBUNDLE OPTIONS 265=head3 MKBUNDLE OPTIONS
264 266
265=over 4 267=over 4
… …
276 278
277Specify the stripping method applied to reduce the file of the perl 279Specify the stripping method applied to reduce the file of the perl
278sources included. 280sources included.
279 281
280The default is C<pod>, which uses the L<Pod::Strip> module to remove all 282The default is C<pod>, which uses the L<Pod::Strip> module to remove all
281pod documenatiton, which is very fast and reduces filesize a lot. 283pod documentation, which is very fast and reduces file size a lot.
282 284
283The C<ppi> method uses L<PPI> to parse and condense the perl sources. This 285The C<ppi> method uses L<PPI> to parse and condense the perl sources. This
284saves a lot more than just L<Pod::Strip>, and is generally safer, but is 286saves a lot more than just L<Pod::Strip>, and is generally safer, but
285also a lot slower, so is best used for production builds. 287is also a lot slower, so is best used for production builds. Note that
288this 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
290compress better, e.g. with F<upx>).
286 291
287Last not least, in the unlikely case where C<pod> is too slow, or some 292Last not least, in the unlikely case where C<pod> is too slow, or some
288module gets mistreated, you can specify C<none> to not mangle included 293module gets mistreated, you can specify C<none> to not mangle included
289perl sources in any way. 294perl sources in any way.
290 295
… …
292 297
293After writing out the bundle files, try to link a new perl interpreter. It 298After writing out the bundle files, try to link a new perl interpreter. It
294will be called F<perl> and will be left in the current working 299will be called F<perl> and will be left in the current working
295directory. The bundle files will be removed. 300directory. The bundle files will be removed.
296 301
297This switch is automatically ued when F<staticperl> is invoked with the 302This switch is automatically used when F<staticperl> is invoked with the
298C<mkperl> command (instead of C<mkbundle>): 303C<mkperl> command (instead of C<mkbundle>):
299 304
300 # build a new ./perl with only common::sense in it - very small :) 305 # build a new ./perl with only common::sense in it - very small :)
301 staticperl mkperl -Mcommon::sense 306 staticperl mkperl -Mcommon::sense
302 307
… …
311 316
312 staticperl mkbundle --use AnyEvent --use AnyEvent::Impl::Perl 317 staticperl mkbundle --use AnyEvent --use AnyEvent::Impl::Perl
313 318
314Sometimes you want to load old-style "perl libraries" (F<.pl> files), or 319Sometimes you want to load old-style "perl libraries" (F<.pl> files), or
315maybe other weirdly named files. To do that, you need to quote the name in 320maybe other weirdly named files. To do that, you need to quote the name in
316single or double quoutes. When given on the commandline, you probably need 321single or double quotes. When given on the command line, you probably need
317to quote once more to avoid your shell interpreting it. Common cases that 322to quote once more to avoid your shell interpreting it. Common cases that
318need this are F<Config_heavy.pl> and F<utf8_heavy.pl>. 323need this are F<Config_heavy.pl> and F<utf8_heavy.pl>.
319 324
320Example: include the required files for F<perl -V> to work in all its 325Example: include the required files for F<perl -V> to work in all its
321glory (F<Config.pm> is included automatically by this). 326glory (F<Config.pm> is included automatically by this).
… …
338variables or whatever you need. All files C<require>'d or C<use>'d in the 343variables or whatever you need. All files C<require>'d or C<use>'d in the
339script are included in the final bundle. 344script are included in the final bundle.
340 345
341Keep in mind that F<mkbundle> will only C<require> the modules named 346Keep in mind that F<mkbundle> will only C<require> the modules named
342by the C<--use> option, so do not expect the symbols from modules you 347by the C<--use> option, so do not expect the symbols from modules you
343C<--use>'d earlier on the commandlien to be available. 348C<--use>'d earlier on the command line to be available.
344 349
345Example: force L<AnyEvent> to detect a backend and therefore include it 350Example: force L<AnyEvent> to detect a backend and therefore include it
346in the final bundle. 351in the final bundle.
347 352
348 staticperl mkbundle --eval 'use AnyEvent; AnyEvent::detect' 353 staticperl mkbundle --eval 'use AnyEvent; AnyEvent::detect'
… …
358=item --boot filename 363=item --boot filename
359 364
360Include the given file in the bundle and arrange for it to be executed 365Include the given file in the bundle and arrange for it to be executed
361(using a C<require>) before anything else when the new perl is 366(using a C<require>) before anything else when the new perl is
362initialised. This can be used to modify C<@INC> or anything else before 367initialised. This can be used to modify C<@INC> or anything else before
363the perl interpreter executes scripts given on the commandline (or via 368the perl interpreter executes scripts given on the command line (or via
364C<-e>). This works even in an embedded interpreter. 369C<-e>). This works even in an embedded interpreter.
365 370
366=item --add "file" | --add "file alias" 371=item --add "file" | --add "file alias"
367 372
368Adds the given (perl) file into the bundle (and optionally call it 373Adds the given (perl) file into the bundle (and optionally call it
… …
425The e-mail address of the person who built this binary. Has no good 430The e-mail address of the person who built this binary. Has no good
426default, so should be specified by you. 431default, so should be specified by you.
427 432
428=back 433=back
429 434
430=head4 Variables you I<might want> to override 435=head4 Variables you might I<want> to override
431 436
432=over 4 437=over 4
433 438
434=item C<PERLVER> 439=item C<PERLVER>
435 440
… …
438about as big as 5.12.2). 443about as big as 5.12.2).
439 444
440=item C<CPAN> 445=item C<CPAN>
441 446
442The URL of the CPAN mirror to use (e.g. L<http://mirror.netcologne.de/cpan/>). 447The URL of the CPAN mirror to use (e.g. L<http://mirror.netcologne.de/cpan/>).
448
449=item C<EXTRA_MODULES>
450
451Additional modules installed during F<staticperl install>. Here you can
452set which modules you want have to installed from CPAN.
453
454Example: I really really need EV, AnyEvent, Coro and IO::AIO.
455
456 EXTRA_MODULES="EV AnyEvent Coro IO::AIO"
457
458Note that you can also use a C<postinstall> hook to achieve this, and
459more.
460
461=item C<PERL_MM_USE_DEFAULT>, C<EV_EXTRA_DEFS>, ...
462
463Usually set to C<1> to make modules "less inquisitive" during their
464installation, you can set any environment variable you want - some modules
465(such as L<Coro> or L<EV>) use environment variables for further tweaking.
466
467=item C<STATICPERL>
468
469The directory where staticperl stores all its files
470(default: F<~/.staticperl>).
471
472=item C<PREFIX>
473
474The prefix where perl gets installed (default: F<$STATICPERL/perl>),
475i.e. where the F<bin> and F<lib> subdirectories will end up.
443 476
444=item C<PERL_CPPFLAGS>, C<PERL_OPTIMIZE>, C<PERL_LDFLAGS>, C<PERL_LIBS> 477=item C<PERL_CPPFLAGS>, C<PERL_OPTIMIZE>, C<PERL_LDFLAGS>, C<PERL_LIBS>
445 478
446These flags are passed to perl's F<Configure> script, and are generally 479These flags are passed to perl's F<Configure> script, and are generally
447optimised for small size (at the cost of performance). Since they also 480optimised for small size (at the cost of performance). Since they also
448contain subtle workarounds around various build issues, changing these 481contain subtle workarounds around various build issues, changing these
449usually requires understanding their default values - best look at the top 482usually requires understanding their default values - best look at the top
450of the F<staticperl> script for more info on these. 483of the F<staticperl> script for more info on these.
451 484
452=item C<STATICPERL>
453
454The directory where staticperl stores all its files
455(default: F<~/.staticperl>).
456
457=item C<PREFIX>
458
459The prefix where perl get's installed (default: F<$STATICPERL/perl>),
460i.e. where the F<bin> and F<lib> subdirectories will end up.
461
462=item C<PERL_MM_USE_DEFAULT>, C<EV_EXTRA_DEFS>, others
463
464Usually set to C<1> to make modules "less inquisitive" during their
465installation, you can set any environment variable you want - some modules
466(such as L<Coro> or L<EV>) use environment variables for further tweaking.
467
468=item C<EXTRA_MODULES>
469
470Additional modules installed during F<staticperl install>. Here you can
471set which modules you want have to installed from CPAN.
472
473Example: I really really need EV, AnyEvent, Coro and IO::AIO.
474
475 EXTRA_MODULES="EV AnyEvent Coro IO::AIO"
476
477Note that you cna also use a C<postinstall> hook to achieve this, and
478more.
479
480=back 485=back
481 486
482=head4 Variables you I<probably do not want> to override 487=head4 Variables you probably I<do not want> to override
483 488
484=over 4 489=over 4
485 490
486=item C<MKBUNDLE> 491=item C<MKBUNDLE>
487 492
… …
497 502
498=head3 OVERRIDABLE HOOKS 503=head3 OVERRIDABLE HOOKS
499 504
500In addition to environment variables, it is possible to provide some 505In addition to environment variables, it is possible to provide some
501shell functions that are called at specific times. To provide your own 506shell functions that are called at specific times. To provide your own
502commands, justd efine the corresponding function. 507commands, just define the corresponding function.
503 508
504Example: install extra modules from CPAN and from some directories 509Example: install extra modules from CPAN and from some directories
505at F<staticperl install> time. 510at F<staticperl install> time.
506 511
507 postinstall() { 512 postinstall() {
508 rm -rf lib/threads.* # weg mit Schaden 513 rm -rf lib/threads* # weg mit Schaden
509 instcpan IO::AIO EV 514 instcpan IO::AIO EV
510 instsrc ~/src/AnyEvent 515 instsrc ~/src/AnyEvent
511 instsrc ~/src/XML-Sablotron-1.0100001 516 instsrc ~/src/XML-Sablotron-1.0100001
512 instcpan AnyEvent::HTTPD 517 instcpan Anyevent::AIO AnyEvent::HTTPD
513 } 518 }
514 519
515=over 4 520=over 4
516 521
517=item postconfigure 522=item postconfigure

Diff Legend

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