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