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