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

File Contents

# User Rev Content
1 root 1.1 NAME
2 root 1.17 staticperl - perl, libc, 100 modules, all in one standalone 500kb file
3 root 1.1
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 root 1.14 staticperl perl ... # invoke the perlinterpreter
13 root 1.1 staticperl cpan # invoke CPAN shell
14 root 1.16 staticperl instsrc path... # install unpacked modules
15 root 1.1 staticperl instcpan modulename... # install modules from CPAN
16     staticperl mkbundle <bundle-args...> # see documentation
17     staticperl mkperl <bundle-args...> # see documentation
18 root 1.7 staticperl mkapp appname <bundle-args...> # see documentation
19 root 1.1
20     Typical Examples:
22     staticperl install # fetch, configure, build and install perl
23     staticperl cpan # run interactive cpan shell
24 root 1.12 staticperl mkperl # build a perl that supports -V
25 root 1.1 staticperl mkperl -MAnyEvent::Impl::Perl -MAnyEvent::HTTPD -MURI -MURI::http
26     # build a perl with the above modules linked in
27 root 1.7 staticperl mkapp myapp --boot mainprog mymodules
28     # build a binary "myapp" from mainprog and mymodules
29 root 1.1
31 root 1.8 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 root 1.2
39     With uClibc and upx on x86, you can create a single 500kb binary that
40 root 1.5 contains perl and 100 modules such as POSIX, AnyEvent, EV, IO::AIO, Coro
41 root 1.15 and so on. Or any other choice of modules (and some other size :).
42 root 1.2
43 root 1.8 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 <>.
47 root 1.2 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:
51     * The generated executables are much smaller than PAR created ones.
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.
59     In addition, staticperl can strip perl sources much more effectively
60     than PAR.
62     * The generated executables start much faster.
64     There is no need to unpack files, or even to parse Zip archives
65     (which is slow and memory-consuming business).
67     * The generated executables don't need a writable filesystem.
69     staticperl loads all required files directly from memory. There is
70     no need to unpack files into a temporary directory.
72 root 1.8 * More control over included files, more burden.
73 root 1.2
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 root 1.8 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 root 1.2
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.
85 root 1.8 All this does not preclude more permissive modes to be implemented
86 root 1.16 in the future, but right now, you have to resolve hidden
87 root 1.8 dependencies manually.
89 root 1.2 * PAR works out of the box, staticperl does not.
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.
96 root 1.6 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.
101 root 1.2 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.
108     It is possible to do program development at this stage, too.
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).
115     This step is very fast (a few seconds if PPI is not used for stripping,
116 root 1.8 or the stripped files are in the cache), and can be tweaked and repeated
117     as often as necessary.
118 root 1.2
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 root 1.9 bin/staticperl, without any installation. The newest (possibly alpha)
125     version can also be downloaded from
126     <>.
127 root 1.2
128     staticperl interprets the first argument as a command to execute,
129     optionally followed by any parameters.
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.
136     The most important command is install, which does basically everything.
137 root 1.12 The default is to download and install perl 5.12.3 and a few modules
138 root 1.2 required by staticperl itself, but all this can (and should) be changed
139     - see CONFIGURATION, below.
141     The command
143     staticperl install
145 root 1.9 is normally all you need: It installs the perl interpreter in
146 root 1.2 ~/.staticperl/perl. It downloads, configures, builds and installs the
147     perl interpreter if required.
149 root 1.9 Most of the following staticperl subcommands simply run one or more
150     steps of this sequence.
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 root 1.2
157     To force recompilation or reinstallation, you need to run staticperl
158     distclean first.
160 root 1.8 staticperl version
161     Prints some info about the version of the staticperl script you are
162     using.
164 root 1.2 staticperl fetch
165     Runs only the download and unpack phase, unless this has already
166     happened.
168     staticperl configure
169     Configures the unpacked perl sources, potentially after downloading
170     them first.
172     staticperl build
173     Builds the configured perl sources, potentially after automatically
174     configuring them.
176     staticperl install
177     Wipes the perl installation directory (usually ~/.staticperl/perl)
178     and installs the perl distribution, potentially after building it
179     first.
181 root 1.14 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.
186     Example: check that the Gtk2 module is installed and loadable.
188     staticperl perl -MGtk2 -e0
190 root 1.2 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 root 1.16 ~/.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 root 1.2
198     Any additional arguments are simply passed to the cpan command.
200     staticperl instcpan module...
201     Tries to install all the modules given and their dependencies, using
202     CPAN.
204     Example:
206     staticperl instcpan EV AnyEvent::HTTPD Coro
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.
214     staticperl clean
215 root 1.6 Deletes the perl source directory (and potentially cleans up other
216     intermediate files). This can be used to clean up files only needed
217 root 1.9 for building perl, without removing the installed perl interpreter.
218 root 1.6
219     At the moment, it doesn't delete downloaded tarballs.
220 root 1.2
221 root 1.9 The exact semantics of this command will probably change.
223 root 1.2 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.
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:
235     staticperl mkbundle mkbundle-args...
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).
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 (for perl -V), AnyEvent::HTTPD, URI
244     and a custom httpd script (from eg/httpd in this distribution):
246     # first make sure we have perl and the required modules
247     staticperl instcpan AnyEvent::HTTPD
249     # now build the perl
250 root 1.12 staticperl mkperl -MAnyEvent::Impl::Perl \
251 root 1.2 -MAnyEvent::HTTPD -MURI::http \
252     --add 'eg/httpd'
254     # finally, invoke it
255     ./perl -Mhttpd
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 (,
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...
266 root 1.7 Instead of building a new perl binary, you can also build a standalone
267     application:
269     # build the app
270     staticperl mkapp app --boot eg/httpd \
271     -MAnyEvent::Impl::Perl -MAnyEvent::HTTPD -MURI::http
273     # run it
274     ./app
276 root 1.10 Here are the three phase 2 commands:
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.
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.
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.
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.
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 root 1.10 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 root 1.2
308 root 1.10 For example, the command given earlier to link a new perl could also
309     look like this:
310 root 1.2
311     staticperl mkperl httpd.bundle
313 root 1.10 With all options stored in the httpd.bundle file (one option per line,
314     everything after the option is an argument):
315 root 1.2
316     use ""
317     use AnyEvent::Impl::Perl
318     use AnyEvent::HTTPD
319     use URI::http
320     add eg/httpd
322     All options that specify modules or files to be added are processed in
323 root 1.10 the order given on the command line.
326 root 1.10 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.
333     Step 0: Generic argument processing.
334     The following options influence staticperl mkbundle itself.
336     "--verbose" | "-v"
337     Increases the verbosity level by one (the default is 1).
339     "--quiet" | "-q"
340     Decreases the verbosity level by one.
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.
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).
355     "--use" module | "-M"module
356 root 1.12 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 root 1.10
360     Example: include AnyEvent and AnyEvent::Impl::Perl.
362     staticperl mkbundle --use AnyEvent --use AnyEvent::Impl::Perl
364     Sometimes you want to load old-style "perl libraries" (.pl
365 root 1.12 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:
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.
376     The import step is done because many modules trigger more
377     dependencies when something is imported than without.
379     anything that contains / or . characters, e.g.,
380     Module/private/
381     The string will be quoted and passed to require, as if you
382     used "require $module". Nothing will be imported.
384     "path" or 'path', e.g. "".
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.
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.
395     staticperl mkbundle -MAnyEvent::Socket # use + import
396     staticperl mkbundle -MAnyEvent/ # require only
397 root 1.10
398     Example: include the required files for perl -V to work in all
399 root 1.12 its glory ( is included automatically by the dependency
400     tracker).
401 root 1.10
402 root 1.12 # shell command
403     staticperl mkbundle
404 root 1.10
405     # bundle specification file
406 root 1.12 use
407 root 1.10
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.
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.
421 root 1.12 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 root 1.10
426     Example: force AnyEvent to detect a backend and therefore
427     include it in the final bundle.
429     staticperl mkbundle --eval 'use AnyEvent; AnyEvent::detect'
431     # or like this
432     staticperl mkbundle -MAnyEvent --eval 'AnyEvent::detect'
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.
438     staticperl mkbundle --eval 'do "bootstrap"' --boot bootstrap
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.
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/
456     This is very useful to include "everything":
458     --incglob '*'
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.
464     --incglob '/unicore/**.pl'
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 root 1.12 the path file will be used as the internal name.
472 root 1.10
473     This switch is used to include extra files into the bundle.
475     Example: embed the file httpd in the current directory as
476 when creating the bundle.
478     staticperl mkperl --add "httpd"
480 root 1.12 # can be accessed via "use httpd"
482     Example: add a file initcode from the current directory.
484     staticperl mkperl --add 'initcode &initcode'
486     # can be accessed via "do '&initcode'"
488 root 1.10 Example: add local files as extra modules in the bundle.
490     # specification file
491     add file1 myfiles/
492     add file2 myfiles/
493     add file3 myfiles/
495     # then later, in perl, use
496     use myfiles::file1;
497     require myfiles::file2;
498     my $res = do "myfiles/";
500 root 1.19 "--addbin" file | "--addbin" "file alias"
501 root 1.10 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).
505 root 1.16 If you specify an alias you should probably add a "/" prefix to
506 root 1.12 avoid clashing with embedded perl files (whose paths never start
507 root 1.16 with "/"), and/or use a special directory prefix, such as
508     "/res/name".
509 root 1.10
510 root 1.16 You can later get a copy of these files by calling "static::find
511     "alias"".
512 root 1.10
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 root 1.16 bundle, without extra ado:
517 root 1.10
518     # a "binary" file, call it ""
519     <<'SOME_MARKER'
520     binary data NOT containing SOME_MARKER
523     # load the binary
524     chomp (my $data = do "");
526 root 1.16 "--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.
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/ 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.
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.
540     #TODO: example
542 root 1.10 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).
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.
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).
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".
564     For example, to include everything except "Devel" modules, but
565     still include Devel::PPPort, you could use this:
567     --incglob '*' -i '/Devel/' -x '/Devel/**'
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:
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.
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).
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.
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.
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.
599     Both .ix and .al files will be detected automatically and added
600     to the bundle.
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.
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.
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.
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.
624     Both the contents of the bundle files and any extra linking is
625     controlled by these options:
627     "--strip" "none"|"pod"|"ppi"
628     Specify the stripping method applied to reduce the file of the
629     perl sources included.
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.
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).
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.
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.
654     This switch is automatically used when staticperl is invoked
655     with the "mkperl" command instead of "mkbundle".
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.
662     staticperl mkperl -Mcommon::sense
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.
669     This switch is automatically used when staticperl is invoked
670     with the "mkapp" command instead of "mkbundle".
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.
677 root 1.12 This means that, by default, it will do nothing but burn a few
678 root 1.10 CPU cycles - for it to do something useful you *must* add some
679     boot code, e.g. with the "--boot" option.
681     Example: create a standalone perl binary called ./myexe that
682     will execute appfile when it is started.
684     staticperl mkbundle --app myexe --boot appfile
686 root 1.12 "--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.
693     Specifically, these are removed:
695     "PERL_HASH_SEED_DEBUG" and "PERL_DEBUG_MSTATS" can cause
696 root 1.17 undesirable output, "PERL5OPT", "PERL_DESTRUCT_LEVEL",
697 root 1.12 "PERL_HASH_SEED" and "PERL_SIGNALS" can alter execution
698     significantly, and "PERL_UNICODE", "PERLIO_DEBUG" and "PERLIO"
699     can affect input and output.
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.
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.
711 root 1.10 "--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.
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).
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.
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.
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.
738     Example: link libcrypt statically into the final binary.
739 root 1.2
740 root 1.10 staticperl mkperl -MIO::AIO --staticlib crypt
742     # ldopts might now contain:
743     # -lm -Wl,-Bstatic -lcrypt -Wl,-Bdynamic -lpthread
744 root 1.2
745 root 1.21 "--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.
750     "--extra-ldflags" string
751     Specifies extra linker flags, used when linking the bundle.
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.
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:
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.
771     Patterns not starting with / will be anchored at the end of the path.
772     That is, will match any file called anywhere in the
773     hierarchy, but not any directories of the same name.
775 root 1.10 A * matches anything within a single path component.
776 root 1.8 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.
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.
784     A ? matches a single character within a component.
785     That is, /Encode/??.pm matches /Encode/, but not the
786     hypothetical /Encode/J/.pm, as ? does not match /.
789     During (each) startup, staticperl tries to source some shell files to
790     allow you to fine-tune/override configuration settings.
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.
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 root 1.2
801     /etc/staticperlrc
802     ~/.staticperlrc
803     $STATICPERL/rc
805     Note that the last file is erased during staticperl distclean, so
806     generally should not be used.
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.
814     "CPAN"
815     The URL of the CPAN mirror to use (e.g.
816     <>).
818 root 1.4 "EXTRA_MODULES"
819     Additional modules installed during staticperl install. Here you can
820     set which modules you want have to installed from CPAN.
822 root 1.5 Example: I really really need EV, AnyEvent, Coro and AnyEvent::AIO.
823 root 1.2
824 root 1.5 EXTRA_MODULES="EV AnyEvent Coro AnyEvent::AIO"
825 root 1.2
826 root 1.4 Note that you can also use a "postinstall" hook to achieve this, and
827     more.
828 root 1.2
829 root 1.5 Variables you might *want* to override
830     "STATICPERL"
831     The directory where staticperl stores all its files (default:
832     ~/.staticperl).
834 root 1.16 "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 root 1.2
839 root 1.5 "PERL_VERSION"
840 root 1.20 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.
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.
848     The default is currently
849, i.e. the latest
850     stableperl release.
851 root 1.2
852 root 1.16 "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.
858 root 1.5 "PERL_PREFIX"
859 root 1.19 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 root 1.2
863 root 1.5 "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.
870     More commonly, you would either activate 64 bit integer support
871     ("-Duse64bitint"), or disable large files support (-Uuselargefiles),
872     to reduce filesize further.
875 root 1.4 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 root 1.9 these, and use a ~/.staticperlrc to override them.
882     Most of the variables override (or modify) the corresponding
883     Configure variable, except "PERL_CCFLAGS", which gets appended.
884 root 1.2
885 root 1.16 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.
889     For other compilers or more customised optimisation settings, you
890     need to adjust these, e.g. in your ~/.staticperlrc.
892     With gcc on x86 and amd64, you can get more space-savings by using:
894     -Os -ffunction-sections -fdata-sections -finline-limit=8 -mpush-args
895     -mno-inline-stringops-dynamically -mno-align-stringops
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):
901     -fomit-frame-pointer -march=pentium3 -mtune=i386
902 root 1.14
903 root 1.3 Variables you probably *do not want* to override
904 root 1.9 "MAKE"
905     The make command to use - default is "make".
907 root 1.2 "MKBUNDLE"
908     Where staticperl writes the "mkbundle" command to (default:
909     $STATICPERL/mkbundle).
912     Additional modules needed by "mkbundle" - should therefore not be
913     changed unless you know what you are doing.
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.
920 root 1.13 The actual order in which hooks are invoked during a full install from
921     scratch is "preconfigure", "patchconfig", "postconfigure", "postbuild",
922     "postinstall".
924 root 1.2 Example: install extra modules from CPAN and from some directories at
925     staticperl install time.
927     postinstall() {
928 root 1.3 rm -rf lib/threads* # weg mit Schaden
929 root 1.2 instcpan IO::AIO EV
930     instsrc ~/src/AnyEvent
931     instsrc ~/src/XML-Sablotron-1.0100001
932 root 1.3 instcpan Anyevent::AIO AnyEvent::HTTPD
933 root 1.2 }
935 root 1.6 preconfigure
936 root 1.13 Called just before running ./Configure in the perl source directory.
937 root 1.6 Current working directory is the perl source directory.
939     This can be used to set any "PERL_xxx" variables, which might be
940     costly to compute.
942 root 1.13 patchconfig
943     Called after running ./Configure in the perl source directory to
944     create ./, but before running ./Configure -S to actually
945     apply the config. Current working directory is the perl source
946     directory.
948     Can be used to tailor/patch or do any other modifications.
950 root 1.2 postconfigure
951     Called after configuring, but before building perl. Current working
952     directory is the perl source directory.
954     postbuild
955     Called after building, but before installing perl. Current working
956     directory is the perl source directory.
958     I have no clue what this could be used for - tell me.
960     postinstall
961     Called after perl and any extra modules have been installed in
962     $PREFIX, but before setting the "installation O.K." flag.
964     The current working directory is $PREFIX, but maybe you should not
965     rely on that.
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.
971     The script must return with a zero exit status, or the installation
972     will fail.
974 root 1.5 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.
979     Intimate knowledge of perlembed and preferably some experience with
980     embedding perl is highly recommended.
982     "mkperl" (or the "--perl" option) basically does this to link the new
983     interpreter (it also adds a main program to bundle.):
985     $Config{cc} $(cat bundle.ccopts) -o perl bundle.c $(cat bundle.ldopts)
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.
992 root 1.12 staticperl_init (xs_init = 0)
993 root 1.5 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:
998     XS (xsfunction)
999     {
1000     dXSARGS;
1002     // now we have items, ST(i) etc.
1003     }
1005     static void
1006     run_myapp(void)
1007     {
1008 root 1.12 staticperl_init (0);
1009 root 1.5 newXSproto ("myapp::xsfunction", xsfunction, __FILE__, "$$;$");
1010     eval_pv ("require myapp::main", 1); // executes "myapp/"
1011     }
1013 root 1.12 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:
1018     static void
1019     xs_init (pTHX)
1020     {
1021     newXSproto ("myapp::xsfunction", xsfunction, __FILE__, "$$;$");
1022     }
1024     static void
1025     run_myapp(void)
1026     {
1027     staticperl_init (xs_init);
1028     }
1030     staticperl_cleanup ()
1031     In the unlikely case that you want to destroy the perl
1032     interpreter, here is the corresponding function.
1034 root 1.5 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.
1039     Then you need this function - either pass it directly as the
1040 root 1.12 "xs_init" function to "perl_parse", or call it as one of the
1041     first things from your own "xs_init" function.
1042 root 1.5
1043     PerlInterpreter *staticperl
1044     The perl interpreter pointer used by staticperl. Not normally so
1045     useful, but there it is.
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".
1052     bundle.ldopts
1053     The linker options needed to link the final program.
1056 root 1.16 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 root 1.20 Data pages in this way are usually freed by the operating system, as
1061     they aren't used more then once.
1062 root 1.16
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.
1067     LAYOUT
1068 root 1.22 Any paths starting with an ampersand (&) or exclamation mark (!) are
1069 root 1.16 reserved by staticperl. They must only be used as described in this
1070     section.
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.
1078     !boot
1079     The bootstrap file, if specified during bundling.
1081     !auto/
1082     Shared objects or dlls corresponding to dynamically-linked perl
1083     extensions are stored with an !auto/ prefix.
1085     !lib/
1086     External shared libraries are stored in this directory.
1088     any letter
1089     Any path starting with a letter is a perl library file. For example,
1090     Coro/ corresponds to the file loaded by "use Coro::AIO", and
1091     Coro/ corresponds to "require "Coro/"".
1092 root 1.5
1093 root 1.16 Obviously, module names shouldn't start with any other characters
1094     than letters :)
1095 root 1.5
1096 root 1.16 FUNCTIONS
1097     $file = static::find $path
1098 root 1.5 Returns the data associated with the given $path (e.g.
1099 root 1.16 "Digest/", "auto/POSIX/autosplit.ix").
1100 root 1.5
1101     Returns "undef" if the file isn't embedded.
1103 root 1.16 @paths = static::list
1104 root 1.5 Returns the list of all paths embedded in this binary.
1106 root 1.16 EXTRA FEATURES
1107     In addition, for the embedded loading of perl files to work, staticperl
1108     overrides the @INC array.
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     (<>). 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.
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 root 1.5
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.
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     "" library:
1134 root 1.12
1135 root 1.8
1136     Many Unicode properties in turn are defined in separate modules,
1137     such as "unicore/" and more specific data tables such as
1138     "unicore/To/" or "unicore/lib/Perl/". These tables
1139     are big (7MB uncompressed, although staticperl contains special
1140 root 1.22 handling for those files), so including them only on demand in your
1141     application might pay off.
1142 root 1.8
1143     To simply include the whole unicode database, use:
1145 root 1.11 --incglob '/unicore/**.pl'
1146 root 1.8
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.
1155     If you want to handle IRIs or IDNs (AnyEvent::Util punycode and idn
1156     functions), you also need to include "AnyEvent/Util/" and
1157     "AnyEvent/Util/".
1159 root 1.10 Or you can use "--usepacklists" and specify "-MAnyEvent" to include
1160 root 1.8 everything.
1162 root 1.14 Cairo
1163     See Glib, same problem, same solution.
1165 root 1.8 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.
1169     Config
1170     The perl -V switch (as well as many modules) needs Config, which in
1171     turn might need "". Including the latter gives you
1172     both.
1174 root 1.14 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.
1181     Gtk2
1182     See Pango, same problems, same solution.
1184 root 1.19 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.
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.
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:
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     }
1206 root 1.14 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.
1211 root 1.8 Term::ReadLine::Perl
1212 root 1.10 Also needs Term::ReadLine::readline, or "--usepacklists".
1213 root 1.8
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 root 1.10 manually, or use "--usepacklists".
1218 root 1.8
1219     RECIPES
1220 root 1.10 Just link everything in
1221 root 1.8 To link just about everything installed in the perl library into a
1222 root 1.10 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):
1225     staticperl mkperl -v --strip ppi --incglob '*'
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 root 1.8
1231 root 1.10 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 <> uses this
1234     approach.
1235 root 1.8
1236 root 1.10 Getting rid of netdb functions
1237 root 1.8 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:
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
1260     done
1261     }
1263 root 1.11 This mostly gains space when linking statically, as the functions
1264 root 1.9 will likely not be linked in. The gain for dynamically-linked
1265 root 1.8 binaries is smaller.
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.
1273     Some guy has made a repository on github
1274     (<>) with some modules
1275     patched to build with staticperl.
1277 root 1.1 AUTHOR
1278     Marc Lehmann <>