ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/App-Staticperl/staticperl.pod
Revision: 1.67
Committed: Fri Aug 4 03:58:52 2023 UTC (8 months, 1 week ago) by root
Branch: MAIN
CVS Tags: HEAD
Changes since 1.66: +39 -38 lines
Log Message:
*** empty log message ***

File Contents

# Content
1 =head1 NAME
2
3 staticperl - perl, libc, 100 modules, all in one standalone 500kb file
4
5 =head1 SYNOPSIS
6
7 staticperl help # print the embedded documentation
8 staticperl fetch # fetch and unpack perl sources
9 staticperl configure # fetch and then configure perl
10 staticperl build # configure and then build perl
11 staticperl install # build and then install perl
12 staticperl clean # clean most intermediate files (restart at configure)
13 staticperl distclean # delete everything installed by this script
14 staticperl perl ... # invoke the perlinterpreter
15 staticperl cpan # invoke CPAN shell
16 staticperl instsrc path... # install unpacked modules
17 staticperl instcpan modulename... # install modules from CPAN
18 staticperl mkbundle <bundle-args...> # see documentation
19 staticperl mkperl <bundle-args...> # see documentation
20 staticperl mkapp appname <bundle-args...> # see documentation
21
22 Typical Examples:
23
24 staticperl install # fetch, configure, build and install perl
25 staticperl cpan # run interactive cpan shell
26 staticperl mkperl -MConfig_heavy.pl # build a perl that supports -V
27 staticperl mkperl -MAnyEvent::Impl::Perl -MAnyEvent::HTTPD -MURI -MURI::http
28 # build a perl with the above modules linked in
29 staticperl mkapp myapp --boot mainprog mymodules
30 # build a binary "myapp" from mainprog and mymodules
31
32 =head1 DESCRIPTION
33
34 This script helps you to create single-file perl interpreters
35 or applications, or embedding a perl interpreter in your
36 applications. Single-file means that it is fully self-contained - no
37 separate shared objects, no autoload fragments, no .pm or .pl files are
38 needed. And when linking statically, you can create (or embed) a single
39 file that contains perl interpreter, libc, all the modules you need, all
40 the libraries you need and of course your actual program.
41
42 With F<uClibc> and F<upx> on x86, you can create a single 500kb binary
43 that contains perl and 100 modules such as POSIX, AnyEvent, EV, IO::AIO,
44 Coro and so on. Or any other choice of modules (and some other size :).
45
46 To see how this turns out, you can try out smallperl and bigperl, two
47 pre-built static and compressed perl binaries with many and even more
48 modules: just follow the links at L<http://staticperl.schmorp.de/>.
49
50 The created files do not need write access to the file system (like PAR
51 does). In fact, since this script is in many ways similar to PAR::Packer,
52 here are the differences:
53
54 =over 4
55
56 =item * The generated executables are much smaller than PAR created ones.
57
58 Shared objects and the perl binary contain a lot of extra info, while
59 the static nature of F<staticperl> allows the linker to remove all
60 functionality and meta-info not required by the final executable. Even
61 extensions statically compiled into perl at build time will only be
62 present in the final executable when needed.
63
64 In addition, F<staticperl> can strip perl sources much more effectively
65 than PAR.
66
67 =item * The generated executables start much faster.
68
69 There is no need to unpack files, or even to parse Zip archives (which is
70 slow and memory-consuming business).
71
72 =item * The generated executables don't need a writable filesystem.
73
74 F<staticperl> loads all required files directly from memory. There is no
75 need to unpack files into a temporary directory.
76
77 =item * More control over included files, more burden.
78
79 PAR tries to be maintenance and hassle-free - it tries to include more
80 files than necessary to make sure everything works out of the box. It
81 mostly succeeds at this, but he extra files (such as the unicode database)
82 can take substantial amounts of memory and file size.
83
84 With F<staticperl>, the burden is mostly with the developer - only direct
85 compile-time dependencies and L<AutoLoader> are handled automatically.
86 This means the modules to include often need to be tweaked manually.
87
88 All this does not preclude more permissive modes to be implemented in
89 the future, but right now, you have to resolve hidden dependencies
90 manually.
91
92 =item * PAR works out of the box, F<staticperl> does not.
93
94 Maintaining your own custom perl build can be a pain in the ass, and while
95 F<staticperl> tries to make this easy, it still requires a custom perl
96 build and possibly fiddling with some modules. PAR is likely to produce
97 results faster.
98
99 Ok, PAR never has worked for me out of the box, and for some people,
100 F<staticperl> does work out of the box, as they don't count "fiddling with
101 module use lists" against it, but nevertheless, F<staticperl> is certainly
102 a bit more difficult to use.
103
104 =back
105
106 =head1 HOW DOES IT WORK?
107
108 Simple: F<staticperl> downloads, compile and installs a perl version of
109 your choice in F<~/.staticperl>. You can add extra modules either by
110 letting F<staticperl> install them for you automatically, or by using CPAN
111 and doing it interactively. This usually takes 5-10 minutes, depending on
112 the speed of your computer and your internet connection.
113
114 It is possible to do program development at this stage, too.
115
116 Afterwards, you create a list of files and modules you want to include,
117 and then either build a new perl binary (that acts just like a normal perl
118 except everything is compiled in), or you create bundle files (basically C
119 sources you can use to embed all files into your project).
120
121 This step is very fast (a few seconds if PPI is not used for stripping, or
122 the stripped files are in the cache), and can be tweaked and repeated as
123 often as necessary.
124
125 =head1 THE F<STATICPERL> SCRIPT
126
127 This module installs a script called F<staticperl> into your perl
128 binary directory. The script is fully self-contained, and can be
129 used without perl (for example, in an uClibc/dietlibc/musl chroot
130 environment). In fact, it can be extracted from the C<App::Staticperl>
131 distribution tarball as F<bin/staticperl>, without any installation. The
132 newest (possibly alpha) version can also be downloaded from
133 L<http://staticperl.schmorp.de/staticperl>.
134
135 F<staticperl> interprets the first argument as a command to execute,
136 optionally followed by any parameters.
137
138 There are two command categories: the "phase 1" commands which deal with
139 installing perl and perl modules, and the "phase 2" commands, which deal
140 with creating binaries and bundle files.
141
142 =head2 PHASE 1 COMMANDS: INSTALLING PERL
143
144 The most important command is F<install>, which does basically
145 everything. The default is to download and install perl 5.12.3 and a few
146 modules required by F<staticperl> itself, but all this can (and should) be
147 changed - see L<CONFIGURATION>, below.
148
149 The command
150
151 staticperl install
152
153 is normally all you need: It installs the perl interpreter in
154 F<~/.staticperl/perl>. It downloads, configures, builds and installs the
155 perl interpreter if required.
156
157 Most of the following F<staticperl> subcommands simply run one or more
158 steps of this sequence.
159
160 If it fails, then most commonly because the compiler options I selected
161 are not supported by your compiler - either edit the F<staticperl> script
162 yourself or create F<~/.staticperl> shell script where your set working
163 C<PERL_CCFLAGS> etc. variables.
164
165 To force recompilation or reinstallation, you need to run F<staticperl
166 distclean> first.
167
168 =over 4
169
170 =item F<staticperl version>
171
172 Prints some info about the version of the F<staticperl> script you are using.
173
174 =item F<staticperl fetch>
175
176 Runs only the download and unpack phase, unless this has already happened.
177
178 =item F<staticperl configure>
179
180 Configures the unpacked perl sources, potentially after downloading them first.
181
182 =item F<staticperl build>
183
184 Builds the configured perl sources, potentially after automatically
185 configuring them.
186
187 =item F<staticperl install>
188
189 Wipes the perl installation directory (usually F<~/.staticperl/perl>) and
190 installs the perl distribution, potentially after building it first.
191
192 =item F<staticperl perl> [args...]
193
194 Invokes the compiled perl interpreter with the given
195 arguments. Basically the same as starting perl directly (usually via
196 F<~/.staticperl/bin/perl>), but beats typing the path sometimes.
197
198 Example: check that the Gtk2 module is installed and loadable.
199
200 staticperl perl -MGtk2 -e0
201
202 =item F<staticperl cpan> [args...]
203
204 Starts an interactive CPAN shell that you can use to install further
205 modules. Installs the perl first if necessary, but apart from that,
206 no magic is involved: you could just as well run it manually via
207 F<~/.staticperl/perl/bin/cpan>, except that F<staticperl> additionally
208 sets the environment variable C<$PERL> to the path of the perl
209 interpreter, which is handy in subshells.
210
211 Any additional arguments are simply passed to the F<cpan> command.
212
213 =item F<staticperl instcpan> module...
214
215 Tries to install all the modules given and their dependencies, using CPAN.
216
217 Example:
218
219 staticperl instcpan EV AnyEvent::HTTPD Coro
220
221 =item F<staticperl instsrc> directory...
222
223 In the unlikely case that you have unpacked perl modules around and want
224 to install from these instead of from CPAN, you can do this using this
225 command by specifying all the directories with modules in them that you
226 want to have built.
227
228 =item F<staticperl clean>
229
230 Deletes the perl source directory (and potentially cleans up other
231 intermediate files). This can be used to clean up files only needed for
232 building perl, without removing the installed perl interpreter.
233
234 At the moment, it doesn't delete downloaded tarballs.
235
236 The exact semantics of this command will probably change.
237
238 =item F<staticperl distclean>
239
240 This wipes your complete F<~/.staticperl> directory. Be careful with this,
241 it nukes your perl download, perl sources, perl distribution and any
242 installed modules. It is useful if you wish to start over "from scratch"
243 or when you want to uninstall F<staticperl>.
244
245 =back
246
247 =head2 PHASE 2 COMMANDS: BUILDING PERL BUNDLES
248
249 Building (linking) a new F<perl> binary is handled by a separate
250 script. To make it easy to use F<staticperl> from a F<chroot>, the script
251 is embedded into F<staticperl>, which will write it out and call for you
252 with any arguments you pass:
253
254 staticperl mkbundle mkbundle-args...
255
256 In the oh so unlikely case of something not working here, you
257 can run the script manually as well (by default it is written to
258 F<~/.staticperl/mkbundle>).
259
260 F<mkbundle> is a more conventional command and expect the argument
261 syntax commonly used on UNIX clones. For example, this command builds
262 a new F<perl> binary and includes F<Config.pm> (for F<perl -V>),
263 F<AnyEvent::HTTPD>, F<URI> and a custom F<httpd> script (from F<eg/httpd>
264 in this distribution):
265
266 # first make sure we have perl and the required modules
267 staticperl instcpan AnyEvent::HTTPD
268
269 # now build the perl
270 staticperl mkperl -MConfig_heavy.pl -MAnyEvent::Impl::Perl \
271 -MAnyEvent::HTTPD -MURI::http \
272 --add 'eg/httpd httpd.pm'
273
274 # finally, invoke it
275 ./perl -Mhttpd
276
277 As you can see, things are not quite as trivial: the L<Config> module has
278 a hidden dependency which is not even a perl module (F<Config_heavy.pl>),
279 L<AnyEvent> needs at least one event loop backend that we have to
280 specify manually (here L<AnyEvent::Impl::Perl>), and the F<URI> module
281 (required by L<AnyEvent::HTTPD>) implements various URI schemes as extra
282 modules - since L<AnyEvent::HTTPD> only needs C<http> URIs, we only need
283 to include that module. I found out about these dependencies by carefully
284 watching any error messages about missing modules...
285
286 Instead of building a new perl binary, you can also build a standalone
287 application:
288
289 # build the app
290 staticperl mkapp app --boot eg/httpd \
291 -MAnyEvent::Impl::Perl -MAnyEvent::HTTPD -MURI::http
292
293 # run it
294 ./app
295
296 Here are the three phase 2 commands:
297
298 =over 4
299
300 =item F<staticperl mkbundle> args...
301
302 The "default" bundle command - it interprets the given bundle options and
303 writes out F<bundle.h>, F<bundle.c>, F<bundle.ccopts> and F<bundle.ldopts>
304 files, useful for embedding.
305
306 =item F<staticperl mkperl> args...
307
308 Creates a bundle just like F<staticperl mkbundle> (in fact, it's the same
309 as invoking F<staticperl mkbundle --perl> args...), but then compiles and
310 links a new perl interpreter that embeds the created bundle, then deletes
311 all intermediate files.
312
313 =item F<staticperl mkapp> filename args...
314
315 Does the same as F<staticperl mkbundle> (in fact, it's the same as
316 invoking F<staticperl mkbundle --app> filename args...), but then compiles
317 and links a new standalone application that simply initialises the perl
318 interpreter.
319
320 The difference to F<staticperl mkperl> is that the standalone application
321 does not act like a perl interpreter would - in fact, by default it would
322 just do nothing and exit immediately, so you should specify some code to
323 be executed via the F<--boot> option.
324
325 =back
326
327 =head3 OPTION PROCESSING
328
329 All options can be given as arguments on the command line (typically
330 using long (e.g. C<--verbose>) or short option (e.g. C<-v>) style). Since
331 specifying a lot of options can make the command line very long and
332 unwieldy, you can put all long options into a "bundle specification file"
333 (one option per line, with or without C<--> prefix) and specify this
334 bundle file instead.
335
336 For example, the command given earlier to link a new F<perl> could also
337 look like this:
338
339 staticperl mkperl httpd.bundle
340
341 With all options stored in the F<httpd.bundle> file (one option per line,
342 everything after the option is an argument):
343
344 use "Config_heavy.pl"
345 use AnyEvent::Impl::Perl
346 use AnyEvent::HTTPD
347 use URI::http
348 add eg/httpd httpd.pm
349
350 All options that specify modules or files to be added are processed in the
351 order given on the command line.
352
353 =head3 BUNDLE CREATION WORKFLOW / STATICPERL MKBUNDLE OPTIONS
354
355 F<staticperl mkbundle> works by first assembling a list of candidate
356 files and modules to include, then filtering them by include/exclude
357 patterns. The remaining modules (together with their direct dependencies,
358 such as link libraries and L<AutoLoader> files) are then converted into
359 bundle files suitable for embedding. F<staticperl mkbundle> can then
360 optionally build a new perl interpreter or a standalone application.
361
362 =over 4
363
364 =item Step 0: Generic argument processing.
365
366 The following options influence F<staticperl mkbundle> itself.
367
368 =over 4
369
370 =item C<--verbose> | C<-v>
371
372 Increases the verbosity level by one (the default is C<1>).
373
374 =item C<--quiet> | C<-q>
375
376 Decreases the verbosity level by one.
377
378 =item any other argument
379
380 Any other argument is interpreted as a bundle specification file, which
381 supports all options (without extra quoting), one option per line, in the
382 format C<option> or C<option argument>. They will effectively be expanded
383 and processed as if they were directly written on the command line, in
384 place of the file name.
385
386 =back
387
388 =item Step 1: gather candidate files and modules
389
390 In this step, modules, perl libraries (F<.pl> files) and other files are
391 selected for inclusion in the bundle. The relevant options are executed
392 in order (this makes a difference mostly for C<--eval>, which can rely on
393 earlier C<--use> options to have been executed).
394
395 =over 4
396
397 =item C<--use> F<module> | C<-M>F<module>
398
399 Include the named module or perl library and trace direct
400 dependencies. This is done by loading the module in a subprocess and
401 tracing which other modules and files it actually loads.
402
403 Example: include AnyEvent and AnyEvent::Impl::Perl.
404
405 staticperl mkbundle --use AnyEvent --use AnyEvent::Impl::Perl
406
407 Sometimes you want to load old-style "perl libraries" (F<.pl> files), or
408 maybe other weirdly named files. To support this, the C<--use> option
409 actually tries to do what you mean, depending on the string you specify:
410
411 =over 4
412
413 =item a possibly valid module name, e.g. F<common::sense>, F<Carp>,
414 F<Coro::Mysql>.
415
416 If the string contains no quotes, no F</> and no F<.>, then C<--use>
417 assumes that it is a normal module name. It will create a new package and
418 evaluate a C<use module> in it, i.e. it will load the package and do a
419 default import.
420
421 The import step is done because many modules trigger more dependencies
422 when something is imported than without.
423
424 =item anything that contains F</> or F<.> characters,
425 e.g. F<utf8_heavy.pl>, F<Module/private/data.pl>.
426
427 The string will be quoted and passed to require, as if you used C<require
428 $module>. Nothing will be imported.
429
430 =item "path" or 'path', e.g. C<"utf8_heavy.pl">.
431
432 If you enclose the name into single or double quotes, then the quotes will
433 be removed and the resulting string will be passed to require. This syntax
434 is form compatibility with older versions of staticperl and should not be
435 used anymore.
436
437 =back
438
439 Example: C<use> AnyEvent::Socket, once using C<use> (importing the
440 symbols), and once via C<require>, not importing any symbols. The first
441 form is preferred as many modules load some extra dependencies when asked
442 to export symbols.
443
444 staticperl mkbundle -MAnyEvent::Socket # use + import
445 staticperl mkbundle -MAnyEvent/Socket.pm # require only
446
447 Example: include the required files for F<perl -V> to work in all its
448 glory (F<Config.pm> is included automatically by the dependency tracker).
449
450 # shell command
451 staticperl mkbundle -MConfig_heavy.pl
452
453 # bundle specification file
454 use Config_heavy.pl
455
456 The C<-M>module syntax is included as a convenience that might be easier
457 to remember than C<--use> - it's the same switch as perl itself uses
458 to load modules. Or maybe it confuses people. Time will tell. Or maybe
459 not. Sigh.
460
461 =item C<--eval> "perl code" | C<-e> "perl code"
462
463 Sometimes it is easier (or necessary) to specify dependencies using perl
464 code, or maybe one of the modules you use need a special use statement. In
465 that case, you can use C<--eval> to execute some perl snippet or set some
466 variables or whatever you need. All files C<require>'d or C<use>'d while
467 executing the snippet are included in the final bundle.
468
469 Keep in mind that F<mkbundle> will not import any symbols from the modules
470 named by the C<--use> option, so do not expect the symbols from modules
471 you C<--use>'d earlier on the command line to be available.
472
473 Example: force L<AnyEvent> to detect a backend and therefore include it
474 in the final bundle.
475
476 staticperl mkbundle --eval 'use AnyEvent; AnyEvent::detect'
477
478 # or like this
479 staticperl mkbundle -MAnyEvent --eval 'AnyEvent::detect'
480
481 Example: use a separate "bootstrap" script that C<use>'s lots of modules
482 and also include this in the final bundle, to be executed automatically
483 when the interpreter is initialised.
484
485 staticperl mkbundle --eval 'do "bootstrap"' --boot bootstrap
486
487 =item C<--boot> F<filename>
488
489 Include the given file in the bundle and arrange for it to be
490 executed (using C<require>) before the main program when the new perl
491 is initialised. This can be used to modify C<@INC> or do similar
492 modifications before the perl interpreter executes scripts given on the
493 command line (or via C<-e>). This works even in an embedded interpreter -
494 the file will be executed during interpreter initialisation in that case.
495
496 =item C<--incglob> pattern
497
498 This goes through all standard library directories and tries to match any
499 F<.pm> and F<.pl> files against the extended glob pattern (see below). If
500 a file matches, it is added. The pattern is matched against the full path
501 of the file (sans the library directory prefix), e.g. F<Sys/Syslog.pm>.
502
503 This is very useful to include "everything":
504
505 --incglob '*'
506
507 It is also useful for including perl libraries, or trees of those, such as
508 the unicode database files needed by some perl built-ins, the regex engine
509 and other modules.
510
511 --incglob '/unicore/**.pl'
512
513 =item C<--add> F<file> | C<--add> "F<file> alias"
514
515 Adds the given (perl) file into the bundle (and optionally call it
516 "alias"). The F<file> is either an absolute path or a path relative to the
517 current directory. If an alias is specified, then this is the name it will
518 use for C<@INC> searches, otherwise the path F<file> will be used as the
519 internal name.
520
521 This switch is used to include extra files into the bundle.
522
523 Example: embed the file F<httpd> in the current directory as F<httpd.pm>
524 when creating the bundle.
525
526 staticperl mkperl --add "httpd httpd.pm"
527
528 # can be accessed via "use httpd"
529
530 Example: add a file F<initcode> from the current directory.
531
532 staticperl mkperl --add 'initcode &initcode'
533
534 # can be accessed via "do '&initcode'"
535
536 Example: add local files as extra modules in the bundle.
537
538 # specification file
539 add file1 myfiles/file1.pm
540 add file2 myfiles/file2.pm
541 add file3 myfiles/file3.pl
542
543 # then later, in perl, use
544 use myfiles::file1;
545 require myfiles::file2;
546 my $res = do "myfiles/file3.pl";
547
548 =item C<--addbin> F<file> | C<--addbin> "F<file> alias"
549
550 Just like C<--add>, except that it treats the file as binary and adds it
551 without any post-processing (perl files might get stripped to reduce their
552 size).
553
554 If you specify an alias you should probably add a C</> prefix to avoid
555 clashing with embedded perl files (whose paths never start with C</>),
556 and/or use a special directory prefix, such as C</res/name>.
557
558 You can later get a copy of these files by calling C<static::find
559 "alias">.
560
561 An alternative way to embed binary files is to convert them to perl and
562 use C<do> to get the contents - this method is a bit cumbersome, but works
563 both inside and outside of a staticperl bundle, without extra ado:
564
565 # a "binary" file, call it "bindata.pl"
566 <<'SOME_MARKER'
567 binary data NOT containing SOME_MARKER
568 SOME_MARKER
569
570 # load the binary
571 chomp (my $data = do "bindata.pl");
572
573 =item C<--allow-dynamic>
574
575 By default, when F<mkbundle> hits a dynamic perl extension (e.g. a F<.so>
576 or F<.dll> file), it will stop with a fatal error.
577
578 When this option is enabled, F<mkbundle> packages the shared
579 object into the bundle instead, with a prefix of F<!>
580 (e.g. F<!auto/List/Util/Util.so>). What you do with that is currently up
581 to you, F<staticperl> has no special support for this at the moment, apart
582 from working around the lack of availability of F<PerlIO::scalar> while
583 bootstrapping, at a speed cost.
584
585 One way to deal with this is to write all files starting with F<!> into
586 some directory and then C<unshift> that path onto C<@INC>.
587
588 (TODO for future self: write and insert a suitable example here, if
589 somebody requests it).
590
591 =back
592
593 =item Step 2: filter all files using C<--include> and C<--exclude> options.
594
595 After all candidate files and modules are added, they are I<filtered>
596 by a combination of C<--include> and C<--exclude> patterns (there is an
597 implicit C<--include *> at the end, so if no filters are specified, all
598 files are included).
599
600 All that this step does is potentially reduce the number of files that are
601 to be included - no new files are added during this step.
602
603 =over 4
604
605 =item C<--include> pattern | C<-i> pattern | C<--exclude> pattern | C<-x> pattern
606
607 These specify an include or exclude pattern to be applied to the candidate
608 file list. An include makes sure that the given files will be part of the
609 resulting file set, an exclude will exclude remaining files. The patterns
610 are "extended glob patterns" (see below).
611
612 The patterns are applied "in order" - files included via earlier
613 C<--include> specifications cannot be removed by any following
614 C<--exclude>, and likewise, and file excluded by an earlier C<--exclude>
615 cannot be added by any following C<--include>.
616
617 For example, to include everything except C<Devel> modules, but still
618 include F<Devel::PPPort>, you could use this:
619
620 --incglob '*' -i '/Devel/PPPort.pm' -x '/Devel/**'
621
622 =back
623
624 =item Step 3: add any extra or "hidden" dependencies.
625
626 F<staticperl> currently knows about three extra types of depdendencies
627 that are added automatically. Only one (F<.packlist> files) is currently
628 optional and can be influenced, the others are always included:
629
630 =over 4
631
632 =item C<--usepacklists>
633
634 Read F<.packlist> files for each distribution that happens to match a
635 module name you specified. Sounds weird, and it is, so expect semantics to
636 change somehow in the future.
637
638 The idea is that most CPAN distributions have a F<.pm> file that matches
639 the name of the distribution (which is rather reasonable after all).
640
641 If this switch is enabled, then if any of the F<.pm> files that have been
642 selected match an install distribution, then all F<.pm>, F<.pl>, F<.al>
643 and F<.ix> files installed by this distribution are also included.
644
645 For example, using this switch, when the L<URI> module is specified, then
646 all L<URI> submodules that have been installed via the CPAN distribution
647 are included as well, so you don't have to manually specify them.
648
649 =item L<AutoLoader> splitfiles
650
651 Some modules use L<AutoLoader> - less commonly (hopefully) used functions
652 are split into separate F<.al> files, and an index (F<.ix>) file contains
653 the prototypes.
654
655 Both F<.ix> and F<.al> files will be detected automatically and added to
656 the bundle.
657
658 =item link libraries (F<.a> files)
659
660 Modules using XS (or any other non-perl language extension compiled at
661 installation time) will have a static archive (typically F<.a>). These
662 will automatically be added to the linker options in F<bundle.ldopts>.
663
664 Should F<staticperl> find a dynamic link library (typically F<.so>) it
665 will warn about it - obviously this shouldn't happen unless you use
666 F<staticperl> on the wrong perl, or one (probably wrongly) configured to
667 use dynamic loading.
668
669 =item extra libraries (F<extralibs.ld>)
670
671 Some modules need linking against external libraries - these are found in
672 F<extralibs.ld> and added to F<bundle.ldopts>.
673
674 =back
675
676 =item Step 4: write bundle files and optionally link a program
677
678 At this point, the select files will be read, processed (stripped) and
679 finally the bundle files get written to disk, and F<staticperl mkbundle>
680 is normally finished. Optionally, it can go a step further and either link
681 a new F<perl> binary with all selected modules and files inside, or build
682 a standalone application.
683
684 Both the contents of the bundle files and any extra linking is controlled
685 by these options:
686
687 =over 4
688
689 =item C<--strip> C<none>|C<pod>|C<ppi>
690
691 Specify the stripping method applied to reduce the file of the perl
692 sources included.
693
694 The default is C<pod>, which uses the L<Pod::Strip> module to remove all
695 pod documentation, which is very fast and reduces file size a lot.
696
697 The C<ppi> method uses L<PPI> to parse and condense the perl sources. This
698 saves a lot more than just L<Pod::Strip>, and is generally safer,
699 but is also a lot slower (some files take almost a minute to strip -
700 F<staticperl> maintains a cache of stripped files to speed up subsequent
701 runs for this reason). Note that this method doesn't optimise for raw file
702 size, but for best compression (that means that the uncompressed file size
703 is a bit larger, but the files compress better, e.g. with F<upx>).
704
705 Last not least, if you need accurate line numbers in error messages,
706 or in the unlikely case where C<pod> is too slow, or some module gets
707 mistreated, you can specify C<none> to not mangle included perl sources in
708 any way.
709
710 =item C<--compress> C<none>|C<lzf>
711
712 Compress each included library file with C<lzf> (default), or do not
713 compress (C<none>). LZF compression typically halves the size of the
714 included library data at almost no overhead, but is counterproductive if
715 you are using another compression solution such as C<UPX>, so it can be
716 disabled.
717
718 =item C<--perl>
719
720 After writing out the bundle files, try to link a new perl interpreter. It
721 will be called F<perl> and will be left in the current working
722 directory. The bundle files will be removed.
723
724 This switch is automatically used when F<staticperl> is invoked with the
725 C<mkperl> command instead of C<mkbundle>.
726
727 Example: build a new F<./perl> binary with only L<common::sense> inside -
728 it will be even smaller than the standard perl interpreter as none of the
729 modules of the base distribution (such as L<Fcntl>) will be included.
730
731 staticperl mkperl -Mcommon::sense
732
733 =item C<--app> F<name>
734
735 After writing out the bundle files, try to link a new standalone
736 program. It will be called C<name>, and the bundle files get removed after
737 linking it.
738
739 This switch is automatically used when F<staticperl> is invoked with the
740 C<mkapp> command instead of C<mkbundle>.
741
742 The difference to the (mutually exclusive) C<--perl> option is that the
743 binary created by this option will not try to act as a perl interpreter -
744 instead it will simply initialise the perl interpreter, clean it up and
745 exit.
746
747 This means that, by default, it will do nothing but burn a few CPU cycles
748 - for it to do something useful you I<must> add some boot code, e.g. with
749 the C<--boot> option.
750
751 Example: create a standalone perl binary called F<./myexe> that will
752 execute F<appfile> when it is started.
753
754 staticperl mkbundle --app myexe --boot appfile
755
756 =item C<--ignore-env>
757
758 Generates extra code to unset some environment variables before
759 initialising/running perl. Perl supports a lot of environment variables
760 that might alter execution in ways that might be undesirable for
761 standalone applications, and this option removes those known to cause
762 trouble.
763
764 Specifically, these are removed:
765
766 C<PERL_HASH_SEED_DEBUG> and C<PERL_DEBUG_MSTATS> can cause undesirable
767 output, C<PERL5OPT>, C<PERL_DESTRUCT_LEVEL>, C<PERL_HASH_SEED> and
768 C<PERL_SIGNALS> can alter execution significantly, and C<PERL_UNICODE>,
769 C<PERLIO_DEBUG> and C<PERLIO> can affect input and output.
770
771 The variables C<PERL_LIB> and C<PERL5_LIB> are always ignored because the
772 startup code used by F<staticperl> overrides C<@INC> in all cases.
773
774 This option will not make your program more secure (unless you are
775 running with elevated privileges), but it will reduce the surprise effect
776 when a user has these environment variables set and doesn't expect your
777 standalone program to act like a perl interpreter.
778
779 =item C<--static>
780
781 Add C<-static> to F<bundle.ldopts>, which means a fully static (if
782 supported by the OS) executable will be created. This is not immensely
783 useful when just creating the bundle files, but is most useful when
784 linking a binary with the C<--perl> or C<--app> options.
785
786 The default is to link the new binary dynamically (that means all perl
787 modules are linked statically, but all external libraries are still
788 referenced dynamically).
789
790 Keep in mind that Solaris doesn't support static linking at all, and
791 systems based on GNU libc don't really support it in a very usable fashion
792 either. Try dietlibc or musl if you want to create fully statically linked
793 executables, or try the C<--staticlib> option to link only some libraries
794 statically.
795
796 =item C<--staticlib> libname
797
798 When not linking fully statically, this option allows you to link specific
799 libraries statically. What it does is simply replace all occurrences of
800 C<-llibname> with the GCC-specific C<-Wl,-Bstatic -llibname -Wl,-Bdynamic>
801 option.
802
803 This will have no effect unless the library is actually linked against,
804 specifically, C<--staticlib> will not link against the named library
805 unless it would be linked against anyway.
806
807 Example: link libcrypt statically into the final binary.
808
809 staticperl mkperl -MIO::AIO --staticlib crypt
810
811 # ldopts might now contain:
812 # -lm -Wl,-Bstatic -lcrypt -Wl,-Bdynamic -lpthread
813
814 =item C<--extra-cflags> string
815
816 Specifies extra compiler flags, used when compiling the bundle file. The
817 flags are appended to all the existing flags, so can be sued to override
818 settings.
819
820 =item C<--extra-ldflags> string
821
822 Specifies extra linker flags, used when linking the bundle.
823
824 =item C<--extra-libs> string
825
826 Extra linker flags, appended at the end when linking. The difference to
827 C<--extra-ldflags> is that the ldflags are appended to the flags, before
828 the objects and libraries, and the extra libs are added at the end.
829
830 =back
831
832 =back
833
834 =head3 EXTENDED GLOB PATTERNS
835
836 Some options of F<staticperl mkbundle> expect an I<extended glob
837 pattern>. This is neither a normal shell glob nor a regex, but something
838 in between. The idea has been copied from rsync, and there are the current
839 matching rules:
840
841 =over 4
842
843 =item Patterns starting with F</> will be a anchored at the root of the library tree.
844
845 That is, F</unicore> will match the F<unicore> directory in C<@INC>, but
846 nothing inside, and neither any other file or directory called F<unicore>
847 anywhere else in the hierarchy.
848
849 =item Patterns not starting with F</> will be anchored at the end of the path.
850
851 That is, F<idna.pl> will match any file called F<idna.pl> anywhere in the
852 hierarchy, but not any directories of the same name.
853
854 =item A F<*> matches anything within a single path component.
855
856 That is, F</unicore/*.pl> would match all F<.pl> files directly inside
857 C</unicore>, not any deeper level F<.pl> files. Or in other words, F<*>
858 will not match slashes.
859
860 =item A F<**> matches anything.
861
862 That is, F</unicore/**.pl> would match all F<.pl> files under F</unicore>,
863 no matter how deeply nested they are inside subdirectories.
864
865 =item A F<?> matches a single character within a component.
866
867 That is, F</Encode/??.pm> matches F</Encode/JP.pm>, but not the
868 hypothetical F</Encode/J/.pm>, as F<?> does not match F</>.
869
870 =back
871
872 =head2 F<STATICPERL> CONFIGURATION AND HOOKS
873
874 During (each) startup, F<staticperl> tries to source some shell files to
875 allow you to fine-tune/override configuration settings.
876
877 In them you can override shell variables, or define shell functions
878 ("hooks") to be called at specific phases during installation. For
879 example, you could define a C<postinstall> hook to install additional
880 modules from CPAN each time you start from scratch.
881
882 If the environment variable C<$STATICPERLRC> is set, then F<staticperl>
883 will try to source the file named with it only. Otherwise, it tries the
884 following shell files in order:
885
886 /etc/staticperlrc
887 ~/.staticperlrc
888 $STATICPERL/rc
889
890 Note that the last file is erased during F<staticperl distclean>, so
891 generally should not be used.
892
893 =head3 CONFIGURATION VARIABLES
894
895 =head4 Variables you I<should> override
896
897 =over 4
898
899 =item C<EMAIL>
900
901 The e-mail address of the person who built this binary. Has no good
902 default, so should be specified by you.
903
904 =item C<CPAN>
905
906 The URL of the CPAN mirror to use (e.g. L<http://mirror.netcologne.de/cpan/>).
907
908 =item C<EXTRA_MODULES>
909
910 Additional modules installed during F<staticperl install>. Here you can
911 set which modules you want have to installed from CPAN.
912
913 Example: I really really need EV, AnyEvent, Coro and AnyEvent::AIO.
914
915 EXTRA_MODULES="EV AnyEvent Coro AnyEvent::AIO"
916
917 Note that you can also use a C<postinstall> hook to achieve this, and
918 more.
919
920 =back
921
922 =head4 Variables you might I<want> to override
923
924 =over 4
925
926 =item C<STATICPERL>
927
928 The directory where staticperl stores all its files
929 (default: F<~/.staticperl>).
930
931 =item C<DLCACHE>
932
933 The path to a directory (will be created if it doesn't exist) where
934 downloaded perl sources are being cached, to avoid downloading them
935 again. The default is empty, which means there is no cache.
936
937 =item C<PERL_VERSION>
938
939 The perl version to install - C<5.12.5> is a good choice for small builds,
940 but C<5.8.9> is also a good choice (5.8.9 is much smaller than 5.12.5), if
941 it builds on your system.
942
943 You can also set this variable to the absolute URL of a tarball (F<.tar>,
944 F<.tar.gz>, F<.tar.bz2>, F<.tar.lzma> or F<.tar.xz>), or to the absolute
945 path of an unpacked perl source tree, which will be copied.
946
947 The default is currently
948 F<http://stableperl.schmorp.de/dist/latest.tar.gz>, i.e. the latest
949 stableperl release.
950
951 =item C<PERL_MM_USE_DEFAULT>, C<EV_EXTRA_DEFS>, ...
952
953 Usually set to C<1> to make modules "less inquisitive" during their
954 installation. You can set (and export!) any environment variable you want
955 - some modules (such as L<Coro> or L<EV>) use environment variables for
956 further tweaking.
957
958 =item C<PERL_PREFIX>
959
960 The directory where perl gets installed (default: F<$STATICPERL/perl>),
961 i.e. where the F<bin> and F<lib> subdirectories will end up. Previous
962 contents will be removed on installation.
963
964 =item C<PERL_CONFIGURE>
965
966 Additional Configure options - these are simply passed to the perl
967 Configure script. For example, if you wanted to enable dynamic loading,
968 you could pass C<-Dusedl>. To enable ithreads (Why would you want that
969 insanity? Don't! Use L<Coro> or L<forks> instead!) you would pass
970 C<-Duseithreads> and so on.
971
972 More commonly, you would either activate 64 bit integer support
973 (C<-Duse64bitint>), or disable large files support (C<-Uuselargefiles>),
974 to reduce file size further.
975
976 =item C<PERL_CC>, C<PERL_CCFLAGS>, C<PERL_OPTIMIZE>, C<PERL_LDFLAGS>, C<PERL_LIBS>
977
978 These flags are passed to perl's F<Configure> script, and are generally
979 optimised for small size (at the cost of performance). Since they also
980 contain subtle workarounds around various build issues, changing these
981 usually requires understanding their default values - best look at
982 the top of the F<staticperl> script for more info on these, and use a
983 F<~/.staticperlrc> to override them.
984
985 Most of the variables override (or modify) the corresponding F<Configure>
986 variable, except C<PERL_CCFLAGS>, which gets appended.
987
988 The default for C<PERL_OPTIMIZE> is C<-Os> (assuming gcc or compatible
989 compilers), and for C<PERL_LIBS> is C<-lm -lcrypt>, which should be good
990 for most (but not all) systems.
991
992 For other compilers or more customised optimisation settings, you need to
993 adjust these, e.g. in your F<~/.staticperlrc>.
994
995 With gcc on x86 and amd64, you can often get more space-savings by using:
996
997 -Os -ffunction-sections -fdata-sections -finline-limit=8 -mpush-args
998 -mno-inline-stringops-dynamically -mno-align-stringops
999
1000 And on x86 and pentium3 and newer (basically everything you might ever
1001 want to run on), adding these is even better for space-savings (use
1002 C<-mtune=core2> or something newer for much faster code, too):
1003
1004 -fomit-frame-pointer -march=pentium3 -mtune=i386
1005
1006 =back
1007
1008 =head4 Variables you probably I<do not want> to override
1009
1010 =over 4
1011
1012 =item C<MAKE>
1013
1014 The make command to use - default is C<make>.
1015
1016 =item C<MKBUNDLE>
1017
1018 Where F<staticperl> writes the C<mkbundle> command to
1019 (default: F<$STATICPERL/mkbundle>).
1020
1021 =item C<STATICPERL_MODULES>
1022
1023 Additional modules needed by C<mkbundle> - should therefore not be changed
1024 unless you know what you are doing.
1025
1026 =back
1027
1028 =head3 OVERRIDABLE HOOKS
1029
1030 In addition to environment variables, it is possible to provide some
1031 shell functions that are called at specific times. To provide your own
1032 commands, just define the corresponding function.
1033
1034 The actual order in which hooks are invoked during a full install
1035 from scratch is C<preconfigure>, C<patchconfig>, C<postconfigure>,
1036 C<postbuild>, C<postinstall>.
1037
1038 Example: install extra modules from CPAN and from some directories
1039 at F<staticperl install> time.
1040
1041 postinstall() {
1042 rm -rf lib/threads* # weg mit Schaden
1043 instcpan IO::AIO EV
1044 instsrc ~/src/AnyEvent
1045 instsrc ~/src/XML-Sablotron-1.0100001
1046 instcpan Anyevent::AIO AnyEvent::HTTPD
1047 }
1048
1049 =over 4
1050
1051 =item preconfigure
1052
1053 Called just before running F<./Configure> in the perl source
1054 directory. Current working directory is the perl source directory.
1055
1056 This can be used to set any C<PERL_xxx> variables, which might be costly
1057 to compute.
1058
1059 =item patchconfig
1060
1061 Called after running F<./Configure> in the perl source directory to create
1062 F<./config.sh>, but before running F<./Configure -S> to actually apply the
1063 config. Current working directory is the perl source directory.
1064
1065 Can be used to tailor/patch F<config.sh> or do any other modifications.
1066
1067 =item postconfigure
1068
1069 Called after configuring, but before building perl. Current working
1070 directory is the perl source directory.
1071
1072 =item postbuild
1073
1074 Called after building, but before installing perl. Current working
1075 directory is the perl source directory.
1076
1077 I have no clue what this could be used for - tell me.
1078
1079 =item postcpanconfig
1080
1081 Called just after CPAN has been configured, but before it has been used to
1082 install anything. You can further change the configuration like this:
1083
1084 "$PERL_PREFIX"/bin/perl -MCPAN::MyConfig -MCPAN -e '
1085 CPAN::Shell->o (conf => urllist => push => "'"$CPAN"'");
1086 ' || fatal "error while initialising CPAN in postcpanconfig"
1087
1088 =item postinstall
1089
1090 Called after perl and any extra modules have been installed in C<$PREFIX>,
1091 but before setting the "installation O.K." flag.
1092
1093 The current working directory is C<$PREFIX>, but maybe you should not rely
1094 on that.
1095
1096 This hook is most useful to customise the installation, by deleting files,
1097 or installing extra modules using the C<instcpan> or C<instsrc> functions.
1098
1099 The script must return with a zero exit status, or the installation will
1100 fail.
1101
1102 =back
1103
1104 =head1 ANATOMY OF A BUNDLE
1105
1106 When not building a new perl binary, C<mkbundle> will leave a number of
1107 files in the current working directory, which can be used to embed a perl
1108 interpreter in your program.
1109
1110 Intimate knowledge of L<perlembed> and preferably some experience with
1111 embedding perl is highly recommended.
1112
1113 C<mkperl> (or the C<--perl> option) basically does this to link the new
1114 interpreter (it also adds a main program to F<bundle.>):
1115
1116 $Config{cc} $(cat bundle.ccopts) -o perl bundle.c $(cat bundle.ldopts)
1117
1118 =over 4
1119
1120 =item bundle.h
1121
1122 A header file that contains the prototypes of the few symbols "exported"
1123 by bundle.c, and also exposes the perl headers to the application.
1124
1125 =over 4
1126
1127 =item staticperl_init (xs_init = 0)
1128
1129 Initialises the perl interpreter. You can use the normal perl functions
1130 after calling this function, for example, to define extra functions or
1131 to load a .pm file that contains some initialisation code, or the main
1132 program function:
1133
1134 XS (xsfunction)
1135 {
1136 dXSARGS;
1137
1138 // now we have items, ST(i) etc.
1139 }
1140
1141 static void
1142 run_myapp(void)
1143 {
1144 staticperl_init (0);
1145 newXSproto ("myapp::xsfunction", xsfunction, __FILE__, "$$;$");
1146 eval_pv ("require myapp::main", 1); // executes "myapp/main.pm"
1147 }
1148
1149 When your boot code already wants to access some XS functions at compile
1150 time, then you need to supply an C<xs_init> function pointer that is
1151 called as soon as perl is initialised enough to define XS functions, but
1152 before the preamble code is executed:
1153
1154 static void
1155 xs_init (pTHX)
1156 {
1157 newXSproto ("myapp::xsfunction", xsfunction, __FILE__, "$$;$");
1158 }
1159
1160 static void
1161 run_myapp(void)
1162 {
1163 staticperl_init (xs_init);
1164 }
1165
1166 =item staticperl_cleanup ()
1167
1168 In the unlikely case that you want to destroy the perl interpreter, here
1169 is the corresponding function.
1170
1171 =item staticperl_xs_init (pTHX)
1172
1173 Sometimes you need direct control over C<perl_parse> and C<perl_run>, in
1174 which case you do not want to use C<staticperl_init> but call them on your
1175 own.
1176
1177 Then you need this function - either pass it directly as the C<xs_init>
1178 function to C<perl_parse>, or call it as one of the first things from your
1179 own C<xs_init> function.
1180
1181 =item PerlInterpreter *staticperl
1182
1183 The perl interpreter pointer used by staticperl. Not normally so useful,
1184 but there it is.
1185
1186 =back
1187
1188 =item bundle.ccopts
1189
1190 Contains the compiler options required to compile at least F<bundle.c> and
1191 any file that includes F<bundle.h> - you should probably use it in your
1192 C<CFLAGS>.
1193
1194 =item bundle.ldopts
1195
1196 The linker options needed to link the final program.
1197
1198 =back
1199
1200 =head1 RUNTIME FUNCTIONALITY
1201
1202 Binaries created with C<mkbundle>/C<mkperl> contain extra functionality,
1203 mostly related to the extra files bundled in the binary (the virtual
1204 filesystem). All of this data is statically compiled into the binary, and
1205 accessing means copying it from a read-only section of your binary. Data
1206 pages in this way are usually freed by the operating system, as they aren't
1207 used more then once.
1208
1209 =head2 VIRTUAL FILESYSTEM
1210
1211 Every bundle has a virtual filesystem. The only information stored in it
1212 is the path and contents of each file that was bundled.
1213
1214 =head3 LAYOUT
1215
1216 Any paths starting with an ampersand (F<&>) or exclamation mark (F<!>) are
1217 reserved by F<staticperl>. They must only be used as described in this
1218 section.
1219
1220 =over 4
1221
1222 =item !
1223
1224 All files that typically cannot be loaded from memory (such as dynamic
1225 objects or shared libraries), but have to reside in the filesystem, are
1226 prefixed with F<!>. Typically these files get written out to some
1227 (semi-)temporary directory shortly after program startup, or before being
1228 used.
1229
1230 =item !boot
1231
1232 The bootstrap file, if specified during bundling.
1233
1234 =item !auto/
1235
1236 Shared objects or dlls corresponding to dynamically-linked perl extensions
1237 are stored with an F<!auto/> prefix.
1238
1239 =item !lib/
1240
1241 External shared libraries are stored in this directory.
1242
1243 =item any letter
1244
1245 Any path starting with a letter is a perl library file. For example,
1246 F<Coro/AIO.pm> corresponds to the file loaded by C<use Coro::AIO>, and
1247 F<Coro/jit.pl> corresponds to C<require "Coro/jit.pl">.
1248
1249 Obviously, module names shouldn't start with any other characters than
1250 letters :)
1251
1252 =back
1253
1254 =head3 FUNCTIONS
1255
1256 =over 4
1257
1258 =item $file = static::find $path
1259
1260 Returns the data associated with the given C<$path>
1261 (e.g. C<Digest/MD5.pm>, C<auto/POSIX/autosplit.ix>).
1262
1263 Returns C<undef> if the file isn't embedded.
1264
1265 =item @paths = static::list
1266
1267 Returns the list of all paths embedded in this binary.
1268
1269 =back
1270
1271 =head2 EXTRA FEATURES
1272
1273 In addition, for the embedded loading of perl files to work, F<staticperl>
1274 overrides the C<@INC> array.
1275
1276 =head1 FULLY STATIC BINARIES - ALPINE LINUX
1277
1278 This section once contained a way to build fully static (including
1279 uClibc) binaries with buildroot. Unfortunately, buildroot no longer
1280 supports a compiler, so I recommend using alpine linux instead
1281 (L<http://alpinelinux.org/>). Get yourself a VM (e.g. with qemu), run an
1282 older alpine linux verison in it (e.g. 2.4), copy staticperl inside and
1283 use it.
1284
1285 The reason you might want an older alpine linux is that uClibc can be
1286 quite dependent on kernel versions, so the newest version of alpine linux
1287 might need a newer kernel then you might want for, if you plan to run your
1288 binaries on on other kernels.
1289
1290 =head1 RECIPES / SPECIFIC MODULES
1291
1292 This section contains some common(?) recipes and information about
1293 problems with some common modules or perl constructs that require extra
1294 files to be included.
1295
1296 =head2 MODULES
1297
1298 =over 4
1299
1300 =item utf8
1301
1302 Some functionality in the C<utf8> module, such as swash handling
1303 (used for unicode character ranges in regexes) is implemented in the
1304 C<utf8_heavy.pl> library:
1305
1306 -Mutf8_heavy.pl
1307
1308 Many Unicode properties in turn are defined in separate modules,
1309 such as C<unicore/Heavy.pl> and more specific data tables such as
1310 C<unicore/To/Digit.pl> or C<unicore/lib/Perl/Word.pl>. These tables
1311 are big (7MB uncompressed, although F<staticperl> contains special
1312 handling for those files), so including them only on demand in your
1313 application might pay off.
1314
1315 To simply include the whole unicode database, use:
1316
1317 --incglob '/unicore/**.pl'
1318
1319 =item AnyEvent
1320
1321 AnyEvent needs a backend implementation that it will load in a delayed
1322 fashion. The L<AnyEvent::Impl::Perl> backend is the default choice
1323 for AnyEvent if it can't find anything else, and is usually a safe
1324 fallback. If you plan to use e.g. L<EV> (L<POE>...), then you need to
1325 include the L<AnyEvent::Impl::EV> (L<AnyEvent::Impl::POE>...) backend as
1326 well.
1327
1328 If you want to handle IRIs or IDNs (L<AnyEvent::Util> punycode and idn
1329 functions), you also need to include C<"AnyEvent/Util/idna.pl"> and
1330 C<"AnyEvent/Util/uts46data.pl">.
1331
1332 Or you can use C<--usepacklists> and specify C<-MAnyEvent> to include
1333 everything.
1334
1335 =item Cairo
1336
1337 See Glib, same problem, same solution.
1338
1339 =item Carp
1340
1341 Carp had (in older versions of perl) a dependency on L<Carp::Heavy>. As of
1342 perl 5.12.2 (maybe earlier), this dependency no longer exists.
1343
1344 =item Config
1345
1346 The F<perl -V> switch (as well as many modules) needs L<Config>, which in
1347 turn might need L<"Config_heavy.pl">. Including the latter gives you
1348 both.
1349
1350 =item Glib
1351
1352 Glib literally requires Glib to be installed already to build - it tries
1353 to fake this by running Glib out of the build directory before being
1354 built. F<staticperl> tries to work around this by forcing C<MAN1PODS> and
1355 C<MAN3PODS> to be empty via the C<PERL_MM_OPT> environment variable.
1356
1357 =item Gtk2
1358
1359 See Pango, same problems, same solution.
1360
1361 =item Net::SSLeay
1362
1363 This module hasn't been significantly updated since OpenSSL is called
1364 OpenSSL, and fails to properly link against dependent libraries, most
1365 commonly, it forgets to specify C<-ldl> when linking.
1366
1367 On GNU/Linux systems this usually goes undetected, as perl usually links
1368 against C<-ldl> itself and OpenSSL just happens to pick it up that way, by
1369 chance.
1370
1371 For static builds, you either have to configure C<-ldl> manually, or you
1372 can use the following snippet in your C<postinstall> hook which patches
1373 Net::SSLeay after installation, which happens to work most of the time:
1374
1375 postinstall() {
1376 # first install it
1377 instcpan Net::SSLeay
1378 # then add -ldl for future linking
1379 chmod u+w "$PERL_PREFIX"/lib/auto/Net/SSLeay/extralibs.ld
1380 echo " -ldl" >>"$PERL_PREFIX"/lib/auto/Net/SSLeay/extralibs.ld
1381 }
1382
1383 =item Pango
1384
1385 In addition to the C<MAN3PODS> problem in Glib, Pango also routes around
1386 L<ExtUtils::MakeMaker> by compiling its files on its own. F<staticperl>
1387 tries to patch L<ExtUtils::MM_Unix> to route around Pango.
1388
1389 =item Term::ReadLine::Perl
1390
1391 Also needs L<Term::ReadLine::readline>, or C<--usepacklists>.
1392
1393 =item URI
1394
1395 URI implements schemes as separate modules - the generic URL scheme is
1396 implemented in L<URI::_generic>, HTTP is implemented in L<URI::http>. If
1397 you need to use any of these schemes, you should include these manually,
1398 or use C<--usepacklists>.
1399
1400 =back
1401
1402 =head2 RECIPES
1403
1404 =over 4
1405
1406 =item Just link everything in
1407
1408 To link just about everything installed in the perl library into a new
1409 perl, try this (the first time this runs it will take a long time, as a
1410 lot of files need to be parsed):
1411
1412 staticperl mkperl -v --strip ppi --incglob '*'
1413
1414 If you don't mind the extra megabytes, this can be a very effective way of
1415 creating bundles without having to worry about forgetting any modules.
1416
1417 You get even more useful variants of this method by first selecting
1418 everything, and then excluding stuff you are reasonable sure not to need -
1419 L<bigperl|http://staticperl.schmorp.de/bigperl.html> uses this approach.
1420
1421 =item Getting rid of netdb functions
1422
1423 The perl core has lots of netdb functions (C<getnetbyname>, C<getgrent>
1424 and so on) that few applications use. You can avoid compiling them in by
1425 putting the following fragment into a C<preconfigure> hook:
1426
1427 preconfigure() {
1428 for sym in \
1429 d_getgrnam_r d_endgrent d_endgrent_r d_endhent \
1430 d_endhostent_r d_endnent d_endnetent_r d_endpent \
1431 d_endprotoent_r d_endpwent d_endpwent_r d_endsent \
1432 d_endservent_r d_getgrent d_getgrent_r d_getgrgid_r \
1433 d_getgrnam_r d_gethbyaddr d_gethent d_getsbyport \
1434 d_gethostbyaddr_r d_gethostbyname_r d_gethostent_r \
1435 d_getlogin_r d_getnbyaddr d_getnbyname d_getnent \
1436 d_getnetbyaddr_r d_getnetbyname_r d_getnetent_r \
1437 d_getpent d_getpbyname d_getpbynumber d_getprotobyname_r \
1438 d_getprotobynumber_r d_getprotoent_r d_getpwent \
1439 d_getpwent_r d_getpwnam_r d_getpwuid_r d_getsent \
1440 d_getservbyname_r d_getservbyport_r d_getservent_r \
1441 d_getspnam_r d_getsbyname
1442 # d_gethbyname
1443 do
1444 PERL_CONFIGURE="$PERL_CONFIGURE -U$sym"
1445 done
1446 }
1447
1448 This mostly gains space when linking statically, as the functions will
1449 likely not be linked in. The gain for dynamically-linked binaries is
1450 smaller.
1451
1452 Also, this leaves C<gethostbyname> in - not only is it actually used
1453 often, the L<Socket> module also exposes it, so leaving it out usually
1454 gains little. Why Socket exposes a C function that is in the core already
1455 is anybody's guess.
1456
1457 =back
1458
1459 =head1 ADDITIONAL RESOURCES
1460
1461 Some guy has made a repository on github
1462 (L<https://github.com/gh0stwizard/staticperl-modules>) with some modules
1463 patched to build with staticperl.
1464
1465 =head1 AUTHOR
1466
1467 Marc Lehmann <schmorp@schmorp.de>
1468 http://software.schmorp.de/pkg/staticperl.html
1469