ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/App-Staticperl/staticperl.pod
Revision: 1.13
Committed: Tue Dec 7 19:55:56 2010 UTC (13 years, 6 months ago) by root
Branch: MAIN
CVS Tags: rel-0_2
Changes since 1.12: +5 -0 lines
Log Message:
*** empty log message ***

File Contents

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