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 cpan # invoke CPAN shell |
13 |
staticperl instmod path... # install unpacked modules |
14 |
staticperl instcpan modulename... # install modules from CPAN |
15 |
staticperl mkbundle <bundle-args...> # see documentation |
16 |
staticperl mkperl <bundle-args...> # see documentation |
17 |
staticperl mkapp appname <bundle-args...> # see documentation |
18 |
|
19 |
Typical Examples: |
20 |
|
21 |
staticperl install # fetch, configure, build and install perl |
22 |
staticperl cpan # run interactive cpan shell |
23 |
staticperl mkperl -M '"Config_heavy.pl"' # build a perl that supports -V |
24 |
staticperl mkperl -MAnyEvent::Impl::Perl -MAnyEvent::HTTPD -MURI -MURI::http |
25 |
# build a perl with the above modules linked in |
26 |
staticperl mkapp myapp --boot mainprog mymodules |
27 |
# build a binary "myapp" from mainprog and mymodules |
28 |
|
29 |
DESCRIPTION |
30 |
This script helps you creating single-file perl interpreters, or |
31 |
embedding a perl interpreter in your applications. Single-file means |
32 |
that it is fully self-contained - no separate shared objects, no |
33 |
autoload fragments, no .pm or .pl files are needed. And when linking |
34 |
statically, you can create (or embed) a single file that contains perl |
35 |
interpreter, libc, all the modules you need and all the libraries you |
36 |
need. |
37 |
|
38 |
With uClibc and upx on x86, you can create a single 500kb binary that |
39 |
contains perl and 100 modules such as POSIX, AnyEvent, EV, IO::AIO, Coro |
40 |
and so on. Or any other choice of modules. |
41 |
|
42 |
The created files do not need write access to the file system (like PAR |
43 |
does). In fact, since this script is in many ways similar to |
44 |
PAR::Packer, here are the differences: |
45 |
|
46 |
* The generated executables are much smaller than PAR created ones. |
47 |
|
48 |
Shared objects and the perl binary contain a lot of extra info, |
49 |
while the static nature of staticperl allows the linker to remove |
50 |
all functionality and meta-info not required by the final |
51 |
executable. Even extensions statically compiled into perl at build |
52 |
time will only be present in the final executable when needed. |
53 |
|
54 |
In addition, staticperl can strip perl sources much more effectively |
55 |
than PAR. |
56 |
|
57 |
* The generated executables start much faster. |
58 |
|
59 |
There is no need to unpack files, or even to parse Zip archives |
60 |
(which is slow and memory-consuming business). |
61 |
|
62 |
* The generated executables don't need a writable filesystem. |
63 |
|
64 |
staticperl loads all required files directly from memory. There is |
65 |
no need to unpack files into a temporary directory. |
66 |
|
67 |
* More control over included files. |
68 |
|
69 |
PAR tries to be maintenance and hassle-free - it tries to include |
70 |
more files than necessary to make sure everything works out of the |
71 |
box. The extra files (such as the unicode database) can take |
72 |
substantial amounts of memory and file size. |
73 |
|
74 |
With staticperl, the burden is mostly with the developer - only |
75 |
direct compile-time dependencies and AutoLoader are handled |
76 |
automatically. This means the modules to include often need to be |
77 |
tweaked manually. |
78 |
|
79 |
* PAR works out of the box, staticperl does not. |
80 |
|
81 |
Maintaining your own custom perl build can be a pain in the ass, and |
82 |
while staticperl tries to make this easy, it still requires a custom |
83 |
perl build and possibly fiddling with some modules. PAR is likely to |
84 |
produce results faster. |
85 |
|
86 |
Ok, PAR never has worked for me out of the box, and for some people, |
87 |
staticperl does work out of the box, as they don't count "fiddling |
88 |
with module use lists" against it, but nevertheless, staticperl is |
89 |
certainly a bit more difficult to use. |
90 |
|
91 |
HOW DOES IT WORK? |
92 |
Simple: staticperl downloads, compile and installs a perl version of |
93 |
your choice in ~/.staticperl. You can add extra modules either by |
94 |
letting staticperl install them for you automatically, or by using CPAN |
95 |
and doing it interactively. This usually takes 5-10 minutes, depending |
96 |
on the speed of your computer and your internet connection. |
97 |
|
98 |
It is possible to do program development at this stage, too. |
99 |
|
100 |
Afterwards, you create a list of files and modules you want to include, |
101 |
and then either build a new perl binary (that acts just like a normal |
102 |
perl except everything is compiled in), or you create bundle files |
103 |
(basically C sources you can use to embed all files into your project). |
104 |
|
105 |
This step is very fast (a few seconds if PPI is not used for stripping, |
106 |
more seconds otherwise, as PPI is very slow), and can be tweaked and |
107 |
repeated as often as necessary. |
108 |
|
109 |
THE STATICPERL SCRIPT |
110 |
This module installs a script called staticperl into your perl binary |
111 |
directory. The script is fully self-contained, and can be used without |
112 |
perl (for example, in an uClibc chroot environment). In fact, it can be |
113 |
extracted from the "App::Staticperl" distribution tarball as |
114 |
bin/staticperl, without any installation. |
115 |
|
116 |
staticperl interprets the first argument as a command to execute, |
117 |
optionally followed by any parameters. |
118 |
|
119 |
There are two command categories: the "phase 1" commands which deal with |
120 |
installing perl and perl modules, and the "phase 2" commands, which deal |
121 |
with creating binaries and bundle files. |
122 |
|
123 |
PHASE 1 COMMANDS: INSTALLING PERL |
124 |
The most important command is install, which does basically everything. |
125 |
The default is to download and install perl 5.12.2 and a few modules |
126 |
required by staticperl itself, but all this can (and should) be changed |
127 |
- see CONFIGURATION, below. |
128 |
|
129 |
The command |
130 |
|
131 |
staticperl install |
132 |
|
133 |
Is normally all you need: It installs the perl interpreter in |
134 |
~/.staticperl/perl. It downloads, configures, builds and installs the |
135 |
perl interpreter if required. |
136 |
|
137 |
Most of the following commands simply run one or more steps of this |
138 |
sequence. |
139 |
|
140 |
To force recompilation or reinstallation, you need to run staticperl |
141 |
distclean first. |
142 |
|
143 |
staticperl fetch |
144 |
Runs only the download and unpack phase, unless this has already |
145 |
happened. |
146 |
|
147 |
staticperl configure |
148 |
Configures the unpacked perl sources, potentially after downloading |
149 |
them first. |
150 |
|
151 |
staticperl build |
152 |
Builds the configured perl sources, potentially after automatically |
153 |
configuring them. |
154 |
|
155 |
staticperl install |
156 |
Wipes the perl installation directory (usually ~/.staticperl/perl) |
157 |
and installs the perl distribution, potentially after building it |
158 |
first. |
159 |
|
160 |
staticperl cpan [args...] |
161 |
Starts an interactive CPAN shell that you can use to install further |
162 |
modules. Installs the perl first if necessary, but apart from that, |
163 |
no magic is involved: you could just as well run it manually via |
164 |
~/.staticperl/perl/bin/cpan. |
165 |
|
166 |
Any additional arguments are simply passed to the cpan command. |
167 |
|
168 |
staticperl instcpan module... |
169 |
Tries to install all the modules given and their dependencies, using |
170 |
CPAN. |
171 |
|
172 |
Example: |
173 |
|
174 |
staticperl instcpan EV AnyEvent::HTTPD Coro |
175 |
|
176 |
staticperl instsrc directory... |
177 |
In the unlikely case that you have unpacked perl modules around and |
178 |
want to install from these instead of from CPAN, you can do this |
179 |
using this command by specifying all the directories with modules in |
180 |
them that you want to have built. |
181 |
|
182 |
staticperl clean |
183 |
Deletes the perl source directory (and potentially cleans up other |
184 |
intermediate files). This can be used to clean up files only needed |
185 |
for building perl, without removing the installed perl interpreter, |
186 |
or to force a re-build from scratch. |
187 |
|
188 |
At the moment, it doesn't delete downloaded tarballs. |
189 |
|
190 |
staticperl distclean |
191 |
This wipes your complete ~/.staticperl directory. Be careful with |
192 |
this, it nukes your perl download, perl sources, perl distribution |
193 |
and any installed modules. It is useful if you wish to start over |
194 |
"from scratch" or when you want to uninstall staticperl. |
195 |
|
196 |
PHASE 2 COMMANDS: BUILDING PERL BUNDLES |
197 |
Building (linking) a new perl binary is handled by a separate script. To |
198 |
make it easy to use staticperl from a chroot, the script is embedded |
199 |
into staticperl, which will write it out and call for you with any |
200 |
arguments you pass: |
201 |
|
202 |
staticperl mkbundle mkbundle-args... |
203 |
|
204 |
In the oh so unlikely case of something not working here, you can run |
205 |
the script manually as well (by default it is written to |
206 |
~/.staticperl/mkbundle). |
207 |
|
208 |
mkbundle is a more conventional command and expect the argument syntax |
209 |
commonly used on UNIX clones. For example, this command builds a new |
210 |
perl binary and includes Config.pm (for perl -V), AnyEvent::HTTPD, URI |
211 |
and a custom httpd script (from eg/httpd in this distribution): |
212 |
|
213 |
# first make sure we have perl and the required modules |
214 |
staticperl instcpan AnyEvent::HTTPD |
215 |
|
216 |
# now build the perl |
217 |
staticperl mkperl -M'"Config_heavy.pl"' -MAnyEvent::Impl::Perl \ |
218 |
-MAnyEvent::HTTPD -MURI::http \ |
219 |
--add 'eg/httpd httpd.pm' |
220 |
|
221 |
# finally, invoke it |
222 |
./perl -Mhttpd |
223 |
|
224 |
As you can see, things are not quite as trivial: the Config module has a |
225 |
hidden dependency which is not even a perl module (Config_heavy.pl), |
226 |
AnyEvent needs at least one event loop backend that we have to specify |
227 |
manually (here AnyEvent::Impl::Perl), and the URI module (required by |
228 |
AnyEvent::HTTPD) implements various URI schemes as extra modules - since |
229 |
AnyEvent::HTTPD only needs "http" URIs, we only need to include that |
230 |
module. I found out about these dependencies by carefully watching any |
231 |
error messages about missing modules... |
232 |
|
233 |
Instead of building a new perl binary, you can also build a standalone |
234 |
application: |
235 |
|
236 |
# build the app |
237 |
staticperl mkapp app --boot eg/httpd \ |
238 |
-MAnyEvent::Impl::Perl -MAnyEvent::HTTPD -MURI::http |
239 |
|
240 |
# run it |
241 |
./app |
242 |
|
243 |
OPTION PROCESSING |
244 |
All options can be given as arguments on the command line (typically |
245 |
using long (e.g. "--verbose") or short option (e.g. "-v") style). Since |
246 |
specifying a lot of modules can make the command line very cumbersome, |
247 |
you can put all long options into a "bundle specification file" (with or |
248 |
without "--" prefix) and specify this bundle file instead. |
249 |
|
250 |
For example, the command given earlier could also look like this: |
251 |
|
252 |
staticperl mkperl httpd.bundle |
253 |
|
254 |
And all options could be in httpd.bundle: |
255 |
|
256 |
use "Config_heavy.pl" |
257 |
use AnyEvent::Impl::Perl |
258 |
use AnyEvent::HTTPD |
259 |
use URI::http |
260 |
add eg/httpd httpd.pm |
261 |
|
262 |
All options that specify modules or files to be added are processed in |
263 |
the order given on the command line (that affects the "--use" and |
264 |
"--eval" options at the moment). |
265 |
|
266 |
MKBUNDLE OPTIONS |
267 |
--verbose | -v |
268 |
Increases the verbosity level by one (the default is 1). |
269 |
|
270 |
--quiet | -q |
271 |
Decreases the verbosity level by one. |
272 |
|
273 |
--strip none|pod|ppi |
274 |
Specify the stripping method applied to reduce the file of the perl |
275 |
sources included. |
276 |
|
277 |
The default is "pod", which uses the Pod::Strip module to remove all |
278 |
pod documentation, which is very fast and reduces file size a lot. |
279 |
|
280 |
The "ppi" method uses PPI to parse and condense the perl sources. |
281 |
This saves a lot more than just Pod::Strip, and is generally safer, |
282 |
but is also a lot slower, so is best used for production builds. |
283 |
Note that this method doesn't optimise for raw file size, but for |
284 |
best compression (that means that the uncompressed file size is a |
285 |
bit larger, but the files compress better, e.g. with upx). |
286 |
|
287 |
Last not least, if you need accurate line numbers in error messages, |
288 |
or in the unlikely case where "pod" is too slow, or some module gets |
289 |
mistreated, you can specify "none" to not mangle included perl |
290 |
sources in any way. |
291 |
|
292 |
--perl |
293 |
After writing out the bundle files, try to link a new perl |
294 |
interpreter. It will be called perl and will be left in the current |
295 |
working directory. The bundle files will be removed. |
296 |
|
297 |
This switch is automatically used when staticperl is invoked with |
298 |
the "mkperl" command (instead of "mkbundle"): |
299 |
|
300 |
# build a new ./perl with only common::sense in it - very small :) |
301 |
staticperl mkperl -Mcommon::sense |
302 |
|
303 |
--app name |
304 |
After writing out the bundle files, try to link a new standalone |
305 |
program. It will be called "name", and the bundle files get removed |
306 |
after linking it. |
307 |
|
308 |
The difference to the (mutually exclusive) "--perl" option is that |
309 |
the binary created by this option will not try to act as a perl |
310 |
interpreter - instead it will simply initialise the perl |
311 |
interpreter, clean it up and exit. |
312 |
|
313 |
This switch is automatically used when staticperl is invoked with |
314 |
the "mkapp" command (instead of "mkbundle"): |
315 |
|
316 |
To let it do something useful you *must* add some boot code, e.g. |
317 |
with the "--boot" option. |
318 |
|
319 |
Example: create a standalone perl binary that will execute appfile |
320 |
when it is started. |
321 |
|
322 |
staticperl mkbundle --app myexe --boot appfile |
323 |
|
324 |
--use module | -Mmodule |
325 |
Include the named module and all direct dependencies. This is done |
326 |
by "require"'ing the module in a subprocess and tracing which other |
327 |
modules and files it actually loads. If the module uses AutoLoader, |
328 |
then all splitfiles will be included as well. |
329 |
|
330 |
Example: include AnyEvent and AnyEvent::Impl::Perl. |
331 |
|
332 |
staticperl mkbundle --use AnyEvent --use AnyEvent::Impl::Perl |
333 |
|
334 |
Sometimes you want to load old-style "perl libraries" (.pl files), |
335 |
or maybe other weirdly named files. To do that, you need to quote |
336 |
the name in single or double quotes. When given on the command line, |
337 |
you probably need to quote once more to avoid your shell |
338 |
interpreting it. Common cases that need this are Config_heavy.pl and |
339 |
utf8_heavy.pl. |
340 |
|
341 |
Example: include the required files for perl -V to work in all its |
342 |
glory (Config.pm is included automatically by this). |
343 |
|
344 |
# bourne shell |
345 |
staticperl mkbundle --use '"Config_heavy.pl"' |
346 |
|
347 |
# bundle specification file |
348 |
use "Config_heavy.pl" |
349 |
|
350 |
The "-Mmodule" syntax is included as an alias that might be easier |
351 |
to remember than "use". Or maybe it confuses people. Time will tell. |
352 |
Or maybe not. Argh. |
353 |
|
354 |
--eval "perl code" | -e "perl code" |
355 |
Sometimes it is easier (or necessary) to specify dependencies using |
356 |
perl code, or maybe one of the modules you use need a special use |
357 |
statement. In that case, you can use "eval" to execute some perl |
358 |
snippet or set some variables or whatever you need. All files |
359 |
"require"'d or "use"'d in the script are included in the final |
360 |
bundle. |
361 |
|
362 |
Keep in mind that mkbundle will only "require" the modules named by |
363 |
the "--use" option, so do not expect the symbols from modules you |
364 |
"--use"'d earlier on the command line to be available. |
365 |
|
366 |
Example: force AnyEvent to detect a backend and therefore include it |
367 |
in the final bundle. |
368 |
|
369 |
staticperl mkbundle --eval 'use AnyEvent; AnyEvent::detect' |
370 |
|
371 |
# or like this |
372 |
staticperl mkbundle -MAnyEvent --eval 'use AnyEvent; AnyEvent::detect' |
373 |
|
374 |
Example: use a separate "bootstrap" script that "use"'s lots of |
375 |
modules and include this in the final bundle, to be executed |
376 |
automatically. |
377 |
|
378 |
staticperl mkbundle --eval 'do "bootstrap"' --boot bootstrap |
379 |
|
380 |
--boot filename |
381 |
Include the given file in the bundle and arrange for it to be |
382 |
executed (using a "require") before anything else when the new perl |
383 |
is initialised. This can be used to modify @INC or anything else |
384 |
before the perl interpreter executes scripts given on the command |
385 |
line (or via "-e"). This works even in an embedded interpreter. |
386 |
|
387 |
--add "file" | --add "file alias" |
388 |
Adds the given (perl) file into the bundle (and optionally call it |
389 |
"alias"). This is useful to include any custom files into the |
390 |
bundle. |
391 |
|
392 |
Example: embed the file httpd as httpd.pm when creating the bundle. |
393 |
|
394 |
staticperl mkperl --add "httpd httpd.pm" |
395 |
|
396 |
It is also a great way to add any custom modules: |
397 |
|
398 |
# specification file |
399 |
add file1 myfiles/file1 |
400 |
add file2 myfiles/file2 |
401 |
add file3 myfiles/file3 |
402 |
|
403 |
--binadd "file" | --add "file alias" |
404 |
Just like "--add", except that it treats the file as binary and adds |
405 |
it without any processing. |
406 |
|
407 |
You should probably add a "/" prefix to avoid clashing with embedded |
408 |
perl files (whose paths do not start with "/"), and/or use a special |
409 |
directory, such as "/res/name". |
410 |
|
411 |
You can later get a copy of these files by calling "staticperl::find |
412 |
"alias"". |
413 |
|
414 |
--static |
415 |
When "--perl" is also given, link statically instead of dynamically. |
416 |
The default is to link the new perl interpreter fully dynamic (that |
417 |
means all perl modules are linked statically, but all external |
418 |
libraries are still referenced dynamically). |
419 |
|
420 |
Keep in mind that Solaris doesn't support static linking at all, and |
421 |
systems based on GNU libc don't really support it in a usable |
422 |
fashion either. Try uClibc if you want to create fully statically |
423 |
linked executables, or try the "--staticlibs" option to link only |
424 |
some libraries statically. |
425 |
|
426 |
any other argument |
427 |
Any other argument is interpreted as a bundle specification file, |
428 |
which supports most long options (without extra quoting), one option |
429 |
per line. |
430 |
|
431 |
STATCPERL CONFIGURATION AND HOOKS |
432 |
During (each) startup, staticperl tries to source the following shell |
433 |
files in order: |
434 |
|
435 |
/etc/staticperlrc |
436 |
~/.staticperlrc |
437 |
$STATICPERL/rc |
438 |
|
439 |
They can be used to override shell variables, or define functions to be |
440 |
called at specific phases. |
441 |
|
442 |
Note that the last file is erased during staticperl distclean, so |
443 |
generally should not be used. |
444 |
|
445 |
CONFIGURATION VARIABLES |
446 |
Variables you *should* override |
447 |
"EMAIL" |
448 |
The e-mail address of the person who built this binary. Has no good |
449 |
default, so should be specified by you. |
450 |
|
451 |
"CPAN" |
452 |
The URL of the CPAN mirror to use (e.g. |
453 |
<http://mirror.netcologne.de/cpan/>). |
454 |
|
455 |
"EXTRA_MODULES" |
456 |
Additional modules installed during staticperl install. Here you can |
457 |
set which modules you want have to installed from CPAN. |
458 |
|
459 |
Example: I really really need EV, AnyEvent, Coro and AnyEvent::AIO. |
460 |
|
461 |
EXTRA_MODULES="EV AnyEvent Coro AnyEvent::AIO" |
462 |
|
463 |
Note that you can also use a "postinstall" hook to achieve this, and |
464 |
more. |
465 |
|
466 |
Variables you might *want* to override |
467 |
"STATICPERL" |
468 |
The directory where staticperl stores all its files (default: |
469 |
~/.staticperl). |
470 |
|
471 |
"PERL_MM_USE_DEFAULT", "EV_EXTRA_DEFS", ... |
472 |
Usually set to 1 to make modules "less inquisitive" during their |
473 |
installation, you can set any environment variable you want - some |
474 |
modules (such as Coro or EV) use environment variables for further |
475 |
tweaking. |
476 |
|
477 |
"PERL_VERSION" |
478 |
The perl version to install - default is currently 5.12.2, but 5.8.9 |
479 |
is also a good choice (5.8.9 is much smaller than 5.12.2, while |
480 |
5.10.1 is about as big as 5.12.2). |
481 |
|
482 |
"PERL_PREFIX" |
483 |
The prefix where perl gets installed (default: $STATICPERL/perl), |
484 |
i.e. where the bin and lib subdirectories will end up. |
485 |
|
486 |
"PERL_CONFIGURE" |
487 |
Additional Configure options - these are simply passed to the perl |
488 |
Configure script. For example, if you wanted to enable dynamic |
489 |
loading, you could pass "-Dusedl". To enable ithreads (Why would you |
490 |
want that insanity? Don't! Use forks instead!) you would pass |
491 |
"-Duseithreads" and so on. |
492 |
|
493 |
More commonly, you would either activate 64 bit integer support |
494 |
("-Duse64bitint"), or disable large files support (-Uuselargefiles), |
495 |
to reduce filesize further. |
496 |
|
497 |
"PERL_CPPFLAGS", "PERL_OPTIMIZE", "PERL_LDFLAGS", "PERL_LIBS" |
498 |
These flags are passed to perl's Configure script, and are generally |
499 |
optimised for small size (at the cost of performance). Since they |
500 |
also contain subtle workarounds around various build issues, |
501 |
changing these usually requires understanding their default values - |
502 |
best look at the top of the staticperl script for more info on |
503 |
these. |
504 |
|
505 |
Variables you probably *do not want* to override |
506 |
"MKBUNDLE" |
507 |
Where staticperl writes the "mkbundle" command to (default: |
508 |
$STATICPERL/mkbundle). |
509 |
|
510 |
"STATICPERL_MODULES" |
511 |
Additional modules needed by "mkbundle" - should therefore not be |
512 |
changed unless you know what you are doing. |
513 |
|
514 |
OVERRIDABLE HOOKS |
515 |
In addition to environment variables, it is possible to provide some |
516 |
shell functions that are called at specific times. To provide your own |
517 |
commands, just define the corresponding function. |
518 |
|
519 |
Example: install extra modules from CPAN and from some directories at |
520 |
staticperl install time. |
521 |
|
522 |
postinstall() { |
523 |
rm -rf lib/threads* # weg mit Schaden |
524 |
instcpan IO::AIO EV |
525 |
instsrc ~/src/AnyEvent |
526 |
instsrc ~/src/XML-Sablotron-1.0100001 |
527 |
instcpan Anyevent::AIO AnyEvent::HTTPD |
528 |
} |
529 |
|
530 |
preconfigure |
531 |
Called just before running ./Configur in the perl source directory. |
532 |
Current working directory is the perl source directory. |
533 |
|
534 |
This can be used to set any "PERL_xxx" variables, which might be |
535 |
costly to compute. |
536 |
|
537 |
postconfigure |
538 |
Called after configuring, but before building perl. Current working |
539 |
directory is the perl source directory. |
540 |
|
541 |
Could be used to tailor/patch config.sh (followed by sh Configure |
542 |
-S) or do any other modifications. |
543 |
|
544 |
postbuild |
545 |
Called after building, but before installing perl. Current working |
546 |
directory is the perl source directory. |
547 |
|
548 |
I have no clue what this could be used for - tell me. |
549 |
|
550 |
postinstall |
551 |
Called after perl and any extra modules have been installed in |
552 |
$PREFIX, but before setting the "installation O.K." flag. |
553 |
|
554 |
The current working directory is $PREFIX, but maybe you should not |
555 |
rely on that. |
556 |
|
557 |
This hook is most useful to customise the installation, by deleting |
558 |
files, or installing extra modules using the "instcpan" or "instsrc" |
559 |
functions. |
560 |
|
561 |
The script must return with a zero exit status, or the installation |
562 |
will fail. |
563 |
|
564 |
ANATOMY OF A BUNDLE |
565 |
When not building a new perl binary, "mkbundle" will leave a number of |
566 |
files in the current working directory, which can be used to embed a |
567 |
perl interpreter in your program. |
568 |
|
569 |
Intimate knowledge of perlembed and preferably some experience with |
570 |
embedding perl is highly recommended. |
571 |
|
572 |
"mkperl" (or the "--perl" option) basically does this to link the new |
573 |
interpreter (it also adds a main program to bundle.): |
574 |
|
575 |
$Config{cc} $(cat bundle.ccopts) -o perl bundle.c $(cat bundle.ldopts) |
576 |
|
577 |
bundle.h |
578 |
A header file that contains the prototypes of the few symbols |
579 |
"exported" by bundle.c, and also exposes the perl headers to the |
580 |
application. |
581 |
|
582 |
staticperl_init () |
583 |
Initialises the perl interpreter. You can use the normal perl |
584 |
functions after calling this function, for example, to define |
585 |
extra functions or to load a .pm file that contains some |
586 |
initialisation code, or the main program function: |
587 |
|
588 |
XS (xsfunction) |
589 |
{ |
590 |
dXSARGS; |
591 |
|
592 |
// now we have items, ST(i) etc. |
593 |
} |
594 |
|
595 |
static void |
596 |
run_myapp(void) |
597 |
{ |
598 |
staticperl_init (); |
599 |
newXSproto ("myapp::xsfunction", xsfunction, __FILE__, "$$;$"); |
600 |
eval_pv ("require myapp::main", 1); // executes "myapp/main.pm" |
601 |
} |
602 |
|
603 |
staticperl_xs_init (pTHX) |
604 |
Sometimes you need direct control over "perl_parse" and |
605 |
"perl_run", in which case you do not want to use |
606 |
"staticperl_init" but call them on your own. |
607 |
|
608 |
Then you need this function - either pass it directly as the |
609 |
"xs_init" function to "perl_parse", or call it from your own |
610 |
"xs_init" function. |
611 |
|
612 |
staticperl_cleanup () |
613 |
In the unlikely case that you want to destroy the perl |
614 |
interpreter, here is the corresponding function. |
615 |
|
616 |
PerlInterpreter *staticperl |
617 |
The perl interpreter pointer used by staticperl. Not normally so |
618 |
useful, but there it is. |
619 |
|
620 |
bundle.ccopts |
621 |
Contains the compiler options required to compile at least bundle.c |
622 |
and any file that includes bundle.h - you should probably use it in |
623 |
your "CFLAGS". |
624 |
|
625 |
bundle.ldopts |
626 |
The linker options needed to link the final program. |
627 |
|
628 |
RUNTIME FUNCTIONALITY |
629 |
Binaries created with "mkbundle"/"mkperl" contain extra functions, which |
630 |
are required to access the bundled perl sources, but might be useful for |
631 |
other purposes. |
632 |
|
633 |
In addition, for the embedded loading of perl files to work, staticperl |
634 |
overrides the @INC array. |
635 |
|
636 |
$file = staticperl::find $path |
637 |
Returns the data associated with the given $path (e.g. |
638 |
"Digest/MD5.pm", "auto/POSIX/autosplit.ix"), which is basically the |
639 |
UNIX path relative to the perl library directory. |
640 |
|
641 |
Returns "undef" if the file isn't embedded. |
642 |
|
643 |
@paths = staticperl::list |
644 |
Returns the list of all paths embedded in this binary. |
645 |
|
646 |
FULLY STATIC BINARIES - BUILDROOT |
647 |
To make truly static (Linux-) libraries, you might want to have a look |
648 |
at buildroot (<http://buildroot.uclibc.org/>). |
649 |
|
650 |
Buildroot is primarily meant to set up a cross-compile environment |
651 |
(which is not so useful as perl doesn't quite like cross compiles), but |
652 |
it can also compile a chroot environment where you can use staticperl. |
653 |
|
654 |
To do so, download buildroot, and enable "Build options => development |
655 |
files in target filesystem" and optionally "Build options => gcc |
656 |
optimization level (optimize for size)". At the time of writing, I had |
657 |
good experiences with GCC 4.4.x but not GCC 4.5. |
658 |
|
659 |
To minimise code size, I used "-pipe -ffunction-sections -fdata-sections |
660 |
-finline-limit=8 -fno-builtin-strlen -mtune=i386". The "-mtune=i386" |
661 |
doesn't decrease codesize much, but it makes the file much more |
662 |
compressible. |
663 |
|
664 |
If you don't need Coro or threads, you can go with "linuxthreads.old" |
665 |
(or no thread support). For Coro, it is highly recommended to switch to |
666 |
a uClibc newer than 0.9.31 (at the time of this writing, I used the |
667 |
20101201 snapshot) and enable NPTL, otherwise Coro needs to be |
668 |
configured with the ultra-slow pthreads backend to work around |
669 |
linuxthreads bugs (it also uses twice the address space needed for |
670 |
stacks). |
671 |
|
672 |
If you use "linuxthreads.old", then you should also be aware that uClibc |
673 |
shares "errno" between all threads when statically linking. See |
674 |
<http://lists.uclibc.org/pipermail/uclibc/2010-June/044157.html> for a |
675 |
workaround (And <https://bugs.uclibc.org/2089> for discussion). |
676 |
|
677 |
"ccache" support is also recommended, especially if you want to play |
678 |
around with buildroot options. Enabling the "miniperl" package will |
679 |
probably enable all options required for a successful perl build. |
680 |
staticperl itself additionally needs either "wget" (recommended, for |
681 |
CPAN) or "curl". |
682 |
|
683 |
As for shells, busybox should provide all that is needed, but the |
684 |
default busybox configuration doesn't include comm which is needed by |
685 |
perl - either make a custom busybox config, or compile coreutils. |
686 |
|
687 |
For the latter route, you might find that bash has some bugs that keep |
688 |
it from working properly in a chroot - either use dash (and link it to |
689 |
/bin/sh inside the chroot) or link busybox to /bin/sh, using it's |
690 |
built-in ash shell. |
691 |
|
692 |
Finally, you need /dev/null inside the chroot for many scripts to work - |
693 |
cp /dev/null output/target/dev or bind-mounting your /dev will both |
694 |
provide this. |
695 |
|
696 |
After you have compiled and set up your buildroot target, you can copy |
697 |
staticperl from the "App::Staticperl" distribution or from your perl |
698 |
f<bin> directory (if you installed it) into the output/target |
699 |
filesystem, chroot inside and run it. |
700 |
|
701 |
AUTHOR |
702 |
Marc Lehmann <schmorp@schmorp.de> |
703 |
http://software.schmorp.de/pkg/staticperl.html |
704 |
|