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

Diff Legend

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