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.16 by root, Wed Dec 8 23:03:21 2010 UTC

1=head1 NAME 1=head1 NAME
2 2
3staticperl - perl, libc, 50 modules all in one 500kb file 3staticperl - perl, libc, 100 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
… …
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 pelr interpreter in your apps. Single-file means that it is fully 34or applications, or embedding a perl interpreter in your
32self-contained - no separate shared objects, no autoload fragments, no .pm 35applications. Single-file means that it is fully self-contained - no
36separate shared objects, no autoload fragments, no .pm or .pl files are
33or .pl files are needed. And when linking statically, you can create (or 37needed. And when linking statically, you can create (or embed) a single
34embed) a single file that contains perl interpreter, libc, all the modules 38file that contains perl interpreter, libc, all the modules you need, all
35you need and all the libraries you need. 39the libraries you need and of course your actual program.
36 40
37With uclibc and upx on x86, you can create a single 500kb binary that 41With F<uClibc> and F<upx> on x86, you can create a single 500kb binary
38contains perl and 50 modules such as AnyEvent, EV, IO::AIO, Coro and so 42that contains perl and 100 modules such as POSIX, AnyEvent, EV, IO::AIO,
39on. Or any other choice of modules. 43Coro and so on. Or any other choice of modules.
40 44
41The created files do not need write access to the filesystem (like PAR 45The 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, 46does). In fact, since this script is in many ways similar to PAR::Packer,
43here are the differences: 47here are the differences:
44 48
45=over 4 49=over 4
46 50
… …
65F<staticperl> loads all required files directly from memory. There is no 69F<staticperl> loads all required files directly from memory. There is no
66need to unpack files into a temporary directory. 70need to unpack files into a temporary directory.
67 71
68=item * More control over included files. 72=item * More control over included files.
69 73
70PAR tries to be maintainance and hassle-free - it tries to include more files 74PAR 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 75files 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. 76extra files (such as the unicode database) can take substantial amounts of
77memory and file size.
73 78
74With F<staticperl>, the burden is mostly with the developer - only direct 79With F<staticperl>, the burden is mostly with the developer - only direct
75compile-time dependencies and L<AutoLoader> are handled automatically. 80compile-time dependencies and L<AutoLoader> are handled automatically.
76This means the modules to include often need to be tweaked manually. 81This means the modules to include often need to be tweaked manually.
77 82
… …
80Maintaining 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
81F<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
82build and possibly fiddling with some modules. PAR is likely to produce 87build and possibly fiddling with some modules. PAR is likely to produce
83results faster. 88results faster.
84 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
85=back 95=back
86 96
87=head1 HOW DOES IT WORK? 97=head1 HOW DOES IT WORK?
88 98
89Simple: F<staticperl> downloads, compile and installs a perl version of 99Simple: F<staticperl> downloads, compile and installs a perl version of
90your choice in F<~/.staticperl>. You can add extra modules either by 100your choice in F<~/.staticperl>. You can add extra modules either by
91letting F<staticperl> install them for you automatically, or by using CPAN 101letting F<staticperl> install them for you automatically, or by using CPAN
92and doing it interactively. This usually takes 5-10 minutes, depending on 102and doing it interactively. This usually takes 5-10 minutes, depending on
93the speed of your computer and your internet conenction. 103the speed of your computer and your internet connection.
94 104
95It is possible to do program development at this stage, too. 105It is possible to do program development at this stage, too.
96 106
97Afterwards, you create a list of files and modules you want to include, 107Afterwards, 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 108and 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 109except everything is compiled in), or you create bundle files (basically C
100sources you can use to embed all files into your project). 110sources you can use to embed all files into your project).
101 111
102This step is very fast (a few seconds if PPI is not used for stripping, 112This 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 113more seconds otherwise, as PPI is very slow), and can be tweaked and
… …
134perl interpreter if required. 144perl interpreter if required.
135 145
136Most of the following commands simply run one or more steps of this 146Most of the following commands simply run one or more steps of this
137sequence. 147sequence.
138 148
139To force recompilation or reinstalaltion, you need to run F<staticperl 149To force recompilation or reinstallation, you need to run F<staticperl
140distclean> first. 150distclean> first.
141 151
142=over 4 152=over 4
143 153
144=item F<staticperl fetch> 154=item F<staticperl fetch>
… …
154Builds the configured perl sources, potentially after automatically 164Builds the configured perl sources, potentially after automatically
155configuring them. 165configuring them.
156 166
157=item F<staticperl install> 167=item F<staticperl install>
158 168
159Wipes the perl installation directory (usually F<~/.staticperl/perl>) and installs 169Wipes the perl installation directory (usually F<~/.staticperl/perl>) and
160the perl distribution, potentially aftering building it first. 170installs the perl distribution, potentially after building it first.
161 171
162=item F<staticperl cpan> [args...] 172=item F<staticperl cpan> [args...]
163 173
164Starts an interactive CPAN shell that you cna use to install further 174Starts an interactive CPAN shell that you can use to install further
165modules. Installs the perl first if neccessary, but apart from that, 175modules. Installs the perl first if necessary, but apart from that,
166no magic is involved: you could just as well run it manually via 176no magic is involved: you could just as well run it manually via
167F<~/.staticperl/perl/bin/cpan>. 177F<~/.staticperl/perl/bin/cpan>.
168 178
169Any additional arguments are simply passed to the F<cpan> command. 179Any additional arguments are simply passed to the F<cpan> command.
170 180
… …
177 staticperl instcpan EV AnyEvent::HTTPD Coro 187 staticperl instcpan EV AnyEvent::HTTPD Coro
178 188
179=item F<staticperl instsrc> directory... 189=item F<staticperl instsrc> directory...
180 190
181In the unlikely case that you have unpacked perl modules around and want 191In 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 192to 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 193command by specifying all the directories with modules in them that you
184want to have built. 194want to have built.
185 195
186=item F<staticperl clean> 196=item F<staticperl clean>
187 197
188Runs F<make distclean> in the perl source directory (and potentially 198Deletes the perl source directory (and potentially cleans up other
189cleans up other intermediate files). This can be used to clean up 199intermediate files). This can be used to clean up files only needed for
190intermediate 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.
191 204
192=item F<staticperl distclean> 205=item F<staticperl distclean>
193 206
194This wipes your complete F<~/.staticperl> directory. Be careful with this, 207This wipes your complete F<~/.staticperl> directory. Be careful with this,
195it nukes your perl download, perl sources, perl distribution and any 208it nukes your perl download, perl sources, perl distribution and any
… …
210In the oh so unlikely case of something not working here, you 223In the oh so unlikely case of something not working here, you
211can run the script manually as well (by default it is written to 224can run the script manually as well (by default it is written to
212F<~/.staticperl/mkbundle>). 225F<~/.staticperl/mkbundle>).
213 226
214F<mkbundle> is a more conventional command and expect the argument 227F<mkbundle> is a more conventional command and expect the argument
215syntax commonly used on unix clones. For example, this command builds 228syntax commonly used on UNIX clones. For example, this command builds
216a new F<perl> binary and includes F<Config.pm> (for F<perl -V>), 229a 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> 230F<AnyEvent::HTTPD>, F<URI> and a custom F<httpd> script (from F<eg/httpd>
218in this distribution): 231in this distribution):
219 232
220 # first make sure we have perl and the required modules 233 # first make sure we have perl and the required modules
… …
229 ./perl -Mhttpd 242 ./perl -Mhttpd
230 243
231As you can see, things are not quite as trivial: the L<Config> module has 244As 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>), 245a 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 246L<AnyEvent> needs at least one event loop backend that we have to
234specifymanually (here L<AnyEvent::Impl::Perl>), and the F<URI> module 247specify manually (here L<AnyEvent::Impl::Perl>), and the F<URI> module
235(required by L<AnyEvent::HTTPD>) implements various URI schemes as extra 248(required by L<AnyEvent::HTTPD>) implements various URI schemes as extra
236modules - 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
237to include that module. 250to include that module. I found out about these dependencies by carefully
251watching any error messages about missing modules...
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
238 262
239=head3 OPTION PROCESSING 263=head3 OPTION PROCESSING
240 264
241All options can be given as arguments on the commandline (typically using 265All 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 266using 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, 267specifying a lot of modules can make the command line very cumbersome,
244you can put all long options into a "bundle specification file" (with or 268you can put all long options into a "bundle specification file" (with or
245without C<--> prefix) and specify this bundle file instead. 269without C<--> prefix) and specify this bundle file instead.
246 270
247For example, the command given earlier could also look like this: 271For example, the command given earlier could also look like this:
248 272
… …
255 use AnyEvent::HTTPD 279 use AnyEvent::HTTPD
256 use URI::http 280 use URI::http
257 add eg/httpd httpd.pm 281 add eg/httpd httpd.pm
258 282
259All options that specify modules or files to be added are processed in the 283All 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> 284order given on the command line (that affects the C<--use> and C<--eval>
261options at the moment). 285options at the moment).
262 286
263=head3 MKBUNDLE OPTIONS 287=head3 MKBUNDLE OPTIONS
264 288
265=over 4 289=over 4
… …
276 300
277Specify the stripping method applied to reduce the file of the perl 301Specify the stripping method applied to reduce the file of the perl
278sources included. 302sources included.
279 303
280The default is C<pod>, which uses the L<Pod::Strip> module to remove all 304The 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. 305pod documentation, which is very fast and reduces file size a lot.
282 306
283The C<ppi> method uses L<PPI> to parse and condense the perl sources. This 307The 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 308saves a lot more than just L<Pod::Strip>, and is generally safer, but
285also a lot slower, so is best used for production builds. 309is also a lot slower, so is best used for production builds. Note that
310this method doesn't optimise for raw file size, but for best compression
311(that means that the uncompressed file size is a bit larger, but the files
312compress better, e.g. with F<upx>).
286 313
314Last not least, if you need accurate line numbers in error messages,
287Last not least, in the unlikely case where C<pod> is too slow, or some 315or in the unlikely case where C<pod> is too slow, or some module gets
288module gets mistreated, you can specify C<none> to not mangle included 316mistreated, you can specify C<none> to not mangle included perl sources in
289perl sources in any way. 317any way.
290 318
291=item --perl 319=item --perl
292 320
293After writing out the bundle files, try to link a new perl interpreter. It 321After 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 322will be called F<perl> and will be left in the current working
295directory. The bundle files will be removed. 323directory. The bundle files will be removed.
296 324
297This switch is automatically ued when F<staticperl> is invoked with the 325This switch is automatically used when F<staticperl> is invoked with the
298C<mkperl> command (instead of C<mkbundle>): 326C<mkperl> command (instead of C<mkbundle>):
299 327
300 # 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 :)
301 staticperl mkperl -Mcommon::sense 329 staticperl mkperl -Mcommon::sense
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
302 352
303=item --use module | -Mmodule 353=item --use module | -Mmodule
304 354
305Include the named module and all direct dependencies. This is done by 355Include the named module and all direct dependencies. This is done by
306C<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
… …
311 361
312 staticperl mkbundle --use AnyEvent --use AnyEvent::Impl::Perl 362 staticperl mkbundle --use AnyEvent --use AnyEvent::Impl::Perl
313 363
314Sometimes you want to load old-style "perl libraries" (F<.pl> files), or 364Sometimes 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 365maybe 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 366single 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 367to quote once more to avoid your shell interpreting it. Common cases that
318need this are F<Config_heavy.pl> and F<utf8_heavy.pl>. 368need this are F<Config_heavy.pl> and F<utf8_heavy.pl>.
319 369
320Example: include the required files for F<perl -V> to work in all its 370Example: include the required files for F<perl -V> to work in all its
321glory (F<Config.pm> is included automatically by this). 371glory (F<Config.pm> is included automatically by this).
… …
338variables or whatever you need. All files C<require>'d or C<use>'d in the 388variables or whatever you need. All files C<require>'d or C<use>'d in the
339script are included in the final bundle. 389script are included in the final bundle.
340 390
341Keep in mind that F<mkbundle> will only C<require> the modules named 391Keep 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 392by the C<--use> option, so do not expect the symbols from modules you
343C<--use>'d earlier on the commandlien to be available. 393C<--use>'d earlier on the command line to be available.
344 394
345Example: force L<AnyEvent> to detect a backend and therefore include it 395Example: force L<AnyEvent> to detect a backend and therefore include it
346in the final bundle. 396in the final bundle.
347 397
348 staticperl mkbundle --eval 'use AnyEvent; AnyEvent::detect' 398 staticperl mkbundle --eval 'use AnyEvent; AnyEvent::detect'
… …
358=item --boot filename 408=item --boot filename
359 409
360Include the given file in the bundle and arrange for it to be executed 410Include 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 411(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 412initialised. This can be used to modify C<@INC> or anything else before
363the perl interpreter executes scripts given on the commandline (or via 413the perl interpreter executes scripts given on the command line (or via
364C<-e>). This works even in an embedded interpreter. 414C<-e>). This works even in an embedded interpreter.
365 415
366=item --add "file" | --add "file alias" 416=item --add "file" | --add "file alias"
367 417
368Adds the given (perl) file into the bundle (and optionally call it 418Adds the given (perl) file into the bundle (and optionally call it
… …
376 426
377 # specification file 427 # specification file
378 add file1 myfiles/file1 428 add file1 myfiles/file1
379 add file2 myfiles/file2 429 add file2 myfiles/file2
380 add file3 myfiles/file3 430 add file3 myfiles/file3
431
432=item --binadd "file" | --add "file alias"
433
434Just like C<--add>, except that it treats the file as binary and adds it
435without any processing.
436
437You should probably add a C</> prefix to avoid clashing with embedded
438perl files (whose paths do not start with C</>), and/or use a special
439directory, such as C</res/name>.
440
441You can later get a copy of these files by calling C<staticperl::find
442"alias">.
381 443
382=item --static 444=item --static
383 445
384When C<--perl> is also given, link statically instead of dynamically. The 446When C<--perl> is also given, link statically instead of dynamically. The
385default is to link the new perl interpreter fully dynamic (that means all 447default is to link the new perl interpreter fully dynamic (that means all
… …
397Any other argument is interpreted as a bundle specification file, which 459Any other argument is interpreted as a bundle specification file, which
398supports most long options (without extra quoting), one option per line. 460supports most long options (without extra quoting), one option per line.
399 461
400=back 462=back
401 463
402=head2 F<STATCPERL> CONFIGURATION AND HOOKS 464=head2 F<STATICPERL> CONFIGURATION AND HOOKS
403 465
404During (each) startup, F<staticperl> tries to source the following shell 466During (each) startup, F<staticperl> tries to source the following shell
405files in order: 467files in order:
406 468
407 /etc/staticperlrc 469 /etc/staticperlrc
… …
423=item C<EMAIL> 485=item C<EMAIL>
424 486
425The e-mail address of the person who built this binary. Has no good 487The e-mail address of the person who built this binary. Has no good
426default, so should be specified by you. 488default, so should be specified by you.
427 489
428=back 490=item C<CPAN>
429 491
492The URL of the CPAN mirror to use (e.g. L<http://mirror.netcologne.de/cpan/>).
493
494=item C<EXTRA_MODULES>
495
496Additional modules installed during F<staticperl install>. Here you can
497set which modules you want have to installed from CPAN.
498
499Example: I really really need EV, AnyEvent, Coro and AnyEvent::AIO.
500
501 EXTRA_MODULES="EV AnyEvent Coro AnyEvent::AIO"
502
503Note that you can also use a C<postinstall> hook to achieve this, and
504more.
505
506=back
507
430=head4 Variables you I<might want> to override 508=head4 Variables you might I<want> to override
431 509
432=over 4 510=over 4
433 511
512=item C<STATICPERL>
513
514The directory where staticperl stores all its files
515(default: F<~/.staticperl>).
516
517=item C<PERL_MM_USE_DEFAULT>, C<EV_EXTRA_DEFS>, ...
518
519Usually set to C<1> to make modules "less inquisitive" during their
520installation, you can set any environment variable you want - some modules
521(such as L<Coro> or L<EV>) use environment variables for further tweaking.
522
434=item C<PERLVER> 523=item C<PERL_VERSION>
435 524
436The perl version to install - default is currently C<5.12.2>, but C<5.8.9> 525The perl version to install - default is currently C<5.12.2>, but C<5.8.9>
437is also a good choice (5.8.9 is much smaller than 5.12.2, while 5.10.1 is 526is also a good choice (5.8.9 is much smaller than 5.12.2, while 5.10.1 is
438about as big as 5.12.2). 527about as big as 5.12.2).
439 528
440=item C<CPAN> 529=item C<PERL_PREFIX>
441 530
442The URL of the CPAN mirror to use (e.g. L<http://mirror.netcologne.de/cpan/>). 531The prefix where perl gets installed (default: F<$STATICPERL/perl>),
532i.e. where the F<bin> and F<lib> subdirectories will end up.
533
534=item C<PERL_CONFIGURE>
535
536Additional Configure options - these are simply passed to the perl
537Configure script. For example, if you wanted to enable dynamic loading,
538you could pass C<-Dusedl>. To enable ithreads (Why would you want that
539insanity? Don't! Use L<forks> instead!) you would pass C<-Duseithreads>
540and so on.
541
542More commonly, you would either activate 64 bit integer support
543(C<-Duse64bitint>), or disable large files support (-Uuselargefiles), to
544reduce filesize further.
443 545
444=item C<PERL_CPPFLAGS>, C<PERL_OPTIMIZE>, C<PERL_LDFLAGS>, C<PERL_LIBS> 546=item C<PERL_CPPFLAGS>, C<PERL_OPTIMIZE>, C<PERL_LDFLAGS>, C<PERL_LIBS>
445 547
446These flags are passed to perl's F<Configure> script, and are generally 548These flags are passed to perl's F<Configure> script, and are generally
447optimised for small size (at the cost of performance). Since they also 549optimised for small size (at the cost of performance). Since they also
448contain subtle workarounds around various build issues, changing these 550contain subtle workarounds around various build issues, changing these
449usually requires understanding their default values - best look at the top 551usually requires understanding their default values - best look at the top
450of the F<staticperl> script for more info on these. 552of the F<staticperl> script for more info on these.
451 553
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 554=back
481 555
482=head4 Variables you I<probably do not want> to override 556=head4 Variables you probably I<do not want> to override
483 557
484=over 4 558=over 4
485 559
486=item C<MKBUNDLE> 560=item C<MKBUNDLE>
487 561
… …
497 571
498=head3 OVERRIDABLE HOOKS 572=head3 OVERRIDABLE HOOKS
499 573
500In addition to environment variables, it is possible to provide some 574In addition to environment variables, it is possible to provide some
501shell functions that are called at specific times. To provide your own 575shell functions that are called at specific times. To provide your own
502commands, justd efine the corresponding function. 576commands, just define the corresponding function.
503 577
504Example: install extra modules from CPAN and from some directories 578Example: install extra modules from CPAN and from some directories
505at F<staticperl install> time. 579at F<staticperl install> time.
506 580
507 postinstall() { 581 postinstall() {
508 rm -rf lib/threads.* # weg mit Schaden 582 rm -rf lib/threads* # weg mit Schaden
509 instcpan IO::AIO EV 583 instcpan IO::AIO EV
510 instsrc ~/src/AnyEvent 584 instsrc ~/src/AnyEvent
511 instsrc ~/src/XML-Sablotron-1.0100001 585 instsrc ~/src/XML-Sablotron-1.0100001
512 instcpan AnyEvent::HTTPD 586 instcpan Anyevent::AIO AnyEvent::HTTPD
513 } 587 }
514 588
515=over 4 589=over 4
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.
516 598
517=item postconfigure 599=item postconfigure
518 600
519Called after configuring, but before building perl. Current working 601Called after configuring, but before building perl. Current working
520directory is the perl source directory. 602directory is the perl source directory.
521 603
522Could 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>)
523do any other modifications. 605or do any other modifications.
524 606
525=item postbuild 607=item postbuild
526 608
527Called after building, but before installing perl. Current working 609Called after building, but before installing perl. Current working
528directory is the perl source directory. 610directory is the perl source directory.
… …
543The script must return with a zero exit status, or the installation will 625The script must return with a zero exit status, or the installation will
544fail. 626fail.
545 627
546=back 628=back
547 629
630=head1 ANATOMY OF A BUNDLE
631
632When not building a new perl binary, C<mkbundle> will leave a number of
633files in the current working directory, which can be used to embed a perl
634interpreter in your program.
635
636Intimate knowledge of L<perlembed> and preferably some experience with
637embedding perl is highly recommended.
638
639C<mkperl> (or the C<--perl> option) basically does this to link the new
640interpreter (it also adds a main program to F<bundle.>):
641
642 $Config{cc} $(cat bundle.ccopts) -o perl bundle.c $(cat bundle.ldopts)
643
644=over 4
645
646=item bundle.h
647
648A header file that contains the prototypes of the few symbols "exported"
649by bundle.c, and also exposes the perl headers to the application.
650
651=over 4
652
653=item staticperl_init ()
654
655Initialises the perl interpreter. You can use the normal perl functions
656after calling this function, for example, to define extra functions or
657to load a .pm file that contains some initialisation code, or the main
658program function:
659
660 XS (xsfunction)
661 {
662 dXSARGS;
663
664 // now we have items, ST(i) etc.
665 }
666
667 static void
668 run_myapp(void)
669 {
670 staticperl_init ();
671 newXSproto ("myapp::xsfunction", xsfunction, __FILE__, "$$;$");
672 eval_pv ("require myapp::main", 1); // executes "myapp/main.pm"
673 }
674
675=item staticperl_xs_init (pTHX)
676
677Sometimes you need direct control over C<perl_parse> and C<perl_run>, in
678which case you do not want to use C<staticperl_init> but call them on your
679own.
680
681Then you need this function - either pass it directly as the C<xs_init>
682function to C<perl_parse>, or call it from your own C<xs_init> function.
683
684=item staticperl_cleanup ()
685
686In the unlikely case that you want to destroy the perl interpreter, here
687is the corresponding function.
688
689=item PerlInterpreter *staticperl
690
691The perl interpreter pointer used by staticperl. Not normally so useful,
692but there it is.
693
694=back
695
696=item bundle.ccopts
697
698Contains the compiler options required to compile at least F<bundle.c> and
699any file that includes F<bundle.h> - you should probably use it in your
700C<CFLAGS>.
701
702=item bundle.ldopts
703
704The linker options needed to link the final program.
705
706=back
707
708=head1 RUNTIME FUNCTIONALITY
709
710Binaries created with C<mkbundle>/C<mkperl> contain extra functions, which
711are required to access the bundled perl sources, but might be useful for
712other purposes.
713
714In addition, for the embedded loading of perl files to work, F<staticperl>
715overrides the C<@INC> array.
716
717=over 4
718
719=item $file = staticperl::find $path
720
721Returns the data associated with the given C<$path>
722(e.g. C<Digest/MD5.pm>, C<auto/POSIX/autosplit.ix>), which is basically
723the UNIX path relative to the perl library directory.
724
725Returns C<undef> if the file isn't embedded.
726
727=item @paths = staticperl::list
728
729Returns the list of all paths embedded in this binary.
730
731=back
732
733=head1 FULLY STATIC BINARIES - BUILDROOT
734
735To make truly static (Linux-) libraries, you might want to have a look at
736buildroot (L<http://buildroot.uclibc.org/>).
737
738Buildroot is primarily meant to set up a cross-compile environment (which
739is not so useful as perl doesn't quite like cross compiles), but it can also compile
740a chroot environment where you can use F<staticperl>.
741
742To do so, download buildroot, and enable "Build options => development
743files in target filesystem" and optionally "Build options => gcc
744optimization level (optimize for size)". At the time of writing, I had
745good experiences with GCC 4.4.x but not GCC 4.5.
746
747To minimise code size, I used C<-pipe -ffunction-sections -fdata-sections
748-finline-limit=8 -fno-builtin-strlen -mtune=i386>. The C<-mtune=i386>
749doesn't decrease codesize much, but it makes the file much more
750compressible.
751
752If you don't need Coro or threads, you can go with "linuxthreads.old" (or
753no thread support). For Coro, it is highly recommended to switch to a
754uClibc newer than 0.9.31 (at the time of this writing, I used the 20101201
755snapshot) and enable NPTL, otherwise Coro needs to be configured with the
756ultra-slow pthreads backend to work around linuxthreads bugs (it also uses
757twice the address space needed for stacks).
758
759If you use C<linuxthreads.old>, then you should also be aware that
760uClibc shares C<errno> between all threads when statically linking. See
761L<http://lists.uclibc.org/pipermail/uclibc/2010-June/044157.html> for a
762workaround (And L<https://bugs.uclibc.org/2089> for discussion).
763
764C<ccache> support is also recommended, especially if you want
765to play around with buildroot options. Enabling the C<miniperl>
766package will probably enable all options required for a successful
767perl build. F<staticperl> itself additionally needs either C<wget>
768(recommended, for CPAN) or C<curl>.
769
770As for shells, busybox should provide all that is needed, but the default
771busybox configuration doesn't include F<comm> which is needed by perl -
772either make a custom busybox config, or compile coreutils.
773
774For the latter route, you might find that bash has some bugs that keep
775it from working properly in a chroot - either use dash (and link it to
776F</bin/sh> inside the chroot) or link busybox to F</bin/sh>, using it's
777built-in ash shell.
778
779Finally, you need F</dev/null> inside the chroot for many scripts to work
780- F<cp /dev/null output/target/dev> or bind-mounting your F</dev> will
781both provide this.
782
783After you have compiled and set up your buildroot target, you can copy
784F<staticperl> from the C<App::Staticperl> distribution or from your
785perl f<bin> directory (if you installed it) into the F<output/target>
786filesystem, chroot inside and run it.
787
548=head1 AUTHOR 788=head1 AUTHOR
549 789
550 Marc Lehmann <schmorp@schmorp.de> 790 Marc Lehmann <schmorp@schmorp.de>
551 http://software.schmorp.de/pkg/staticperl.html 791 http://software.schmorp.de/pkg/staticperl.html

Diff Legend

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