ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/App-Staticperl/README
Revision: 1.22
Committed: Tue Feb 15 18:37:34 2022 UTC (2 years, 1 month ago) by root
Branch: MAIN
CVS Tags: rel-1_46, HEAD
Changes since 1.21: +3 -3 lines
Log Message:
1.46

File Contents

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