ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/App-Staticperl/README
Revision: 1.15
Committed: Tue Jun 14 07:04:43 2011 UTC (13 years, 1 month ago) by root
Branch: MAIN
CVS Tags: rel-1_31
Changes since 1.14: +2 -2 lines
Log Message:
1.31

File Contents

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