ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/App-Staticperl/staticperl.pod
(Generate patch)

Comparing App-Staticperl/staticperl.pod (file contents):
Revision 1.3 by root, Mon Dec 6 21:10:41 2010 UTC vs.
Revision 1.15 by root, Wed Dec 8 23:01:30 2010 UTC

1=head1 NAME 1=head1 NAME
2 2
3staticperl - perl, libc, 50 modules all in one 500kb file 3staticperl - perl, libc, 100 modules, all in one 500kb file
4 4
5=head1 SYNOPSIS 5=head1 SYNOPSIS
6 6
7 staticperl help # print the embedded documentation 7 staticperl help # print the embedded documentation
8 staticperl fetch # fetch and unpack perl sources 8 staticperl fetch # fetch and unpack perl sources
14 staticperl cpan # invoke CPAN shell 14 staticperl cpan # invoke CPAN shell
15 staticperl instmod path... # install unpacked modules 15 staticperl instmod path... # install unpacked modules
16 staticperl instcpan modulename... # install modules from CPAN 16 staticperl instcpan modulename... # install modules from CPAN
17 staticperl mkbundle <bundle-args...> # see documentation 17 staticperl mkbundle <bundle-args...> # see documentation
18 staticperl mkperl <bundle-args...> # see documentation 18 staticperl mkperl <bundle-args...> # see documentation
19 staticperl mkapp appname <bundle-args...> # see documentation
19 20
20Typical Examples: 21Typical Examples:
21 22
22 staticperl install # fetch, configure, build and install perl 23 staticperl install # fetch, configure, build and install perl
23 staticperl cpan # run interactive cpan shell 24 staticperl cpan # run interactive cpan shell
24 staticperl mkperl -M '"Config_heavy.pl"' # build a perl that supports -V 25 staticperl mkperl -M '"Config_heavy.pl"' # build a perl that supports -V
25 staticperl mkperl -MAnyEvent::Impl::Perl -MAnyEvent::HTTPD -MURI -MURI::http 26 staticperl mkperl -MAnyEvent::Impl::Perl -MAnyEvent::HTTPD -MURI -MURI::http
26 # build a perl with the above modules linked in 27 # build a perl with the above modules linked in
28 staticperl mkapp myapp --boot mainprog mymodules
29 # build a binary "myapp" from mainprog and mymodules
27 30
28=head1 DESCRIPTION 31=head1 DESCRIPTION
29 32
30This script helps you creating single-file perl interpreters, or embedding 33This script helps you creating single-file perl interpreters, or embedding
31a perl interpreter in your applications. Single-file means that it is 34a perl interpreter in your applications. Single-file means that it is
32fully self-contained - no separate shared objects, no autoload fragments, 35fully self-contained - no separate shared objects, no autoload fragments,
33no .pm or .pl files are needed. And when linking statically, you can 36no .pm or .pl files are needed. And when linking statically, you can
34create (or embed) a single file that contains perl interpreter, libc, all 37create (or embed) a single file that contains perl interpreter, libc, all
35the modules you need and all the libraries you need. 38the modules you need and all the libraries you need.
36 39
37With F<uClibc> and F<upx> on x86, you can create a single 500kb binary that 40With F<uClibc> and F<upx> on x86, you can create a single 500kb binary
38contains perl and 50 modules such as AnyEvent, EV, IO::AIO, Coro and so 41that contains perl and 100 modules such as POSIX, AnyEvent, EV, IO::AIO,
39on. Or any other choice of modules. 42Coro and so on. Or any other choice of modules.
40 43
41The created files do not need write access to the file system (like PAR 44The created files do not need write access to the file system (like PAR
42does). In fact, since this script is in many ways similar to PAR::Packer, 45does). In fact, since this script is in many ways similar to PAR::Packer,
43here are the differences: 46here are the differences:
44 47
81Maintaining your own custom perl build can be a pain in the ass, and while 84Maintaining your own custom perl build can be a pain in the ass, and while
82F<staticperl> tries to make this easy, it still requires a custom perl 85F<staticperl> tries to make this easy, it still requires a custom perl
83build and possibly fiddling with some modules. PAR is likely to produce 86build and possibly fiddling with some modules. PAR is likely to produce
84results faster. 87results faster.
85 88
89Ok, PAR never has worked for me out of the box, and for some people,
90F<staticperl> does work out of the box, as they don't count "fiddling with
91module use lists" against it, but nevertheless, F<staticperl> is certainly
92a bit more difficult to use.
93
86=back 94=back
87 95
88=head1 HOW DOES IT WORK? 96=head1 HOW DOES IT WORK?
89 97
90Simple: F<staticperl> downloads, compile and installs a perl version of 98Simple: F<staticperl> downloads, compile and installs a perl version of
184command by specifying all the directories with modules in them that you 192command by specifying all the directories with modules in them that you
185want to have built. 193want to have built.
186 194
187=item F<staticperl clean> 195=item F<staticperl clean>
188 196
189Runs F<make distclean> in the perl source directory (and potentially 197Deletes the perl source directory (and potentially cleans up other
190cleans up other intermediate files). This can be used to clean up 198intermediate files). This can be used to clean up files only needed for
191intermediate files without removing the installed perl interpreter. 199building perl, without removing the installed perl interpreter, or to
200force a re-build from scratch.
201
202At the moment, it doesn't delete downloaded tarballs.
192 203
193=item F<staticperl distclean> 204=item F<staticperl distclean>
194 205
195This wipes your complete F<~/.staticperl> directory. Be careful with this, 206This wipes your complete F<~/.staticperl> directory. Be careful with this,
196it nukes your perl download, perl sources, perl distribution and any 207it nukes your perl download, perl sources, perl distribution and any
236(required by L<AnyEvent::HTTPD>) implements various URI schemes as extra 247(required by L<AnyEvent::HTTPD>) implements various URI schemes as extra
237modules - since L<AnyEvent::HTTPD> only needs C<http> URIs, we only need 248modules - since L<AnyEvent::HTTPD> only needs C<http> URIs, we only need
238to include that module. I found out about these dependencies by carefully 249to include that module. I found out about these dependencies by carefully
239watching any error messages about missing modules... 250watching any error messages about missing modules...
240 251
252Instead of building a new perl binary, you can also build a standalone
253application:
254
255 # build the app
256 staticperl mkapp app --boot eg/httpd \
257 -MAnyEvent::Impl::Perl -MAnyEvent::HTTPD -MURI::http
258
259 # run it
260 ./app
261
241=head3 OPTION PROCESSING 262=head3 OPTION PROCESSING
242 263
243All options can be given as arguments on the command line (typically 264All options can be given as arguments on the command line (typically
244using long (e.g. C<--verbose>) or short option (e.g. C<-v>) style). Since 265using long (e.g. C<--verbose>) or short option (e.g. C<-v>) style). Since
245specifying a lot of modules can make the command line very cumbersome, 266specifying a lot of modules can make the command line very cumbersome,
287is also a lot slower, so is best used for production builds. Note that 308is also a lot slower, so is best used for production builds. Note that
288this method doesn't optimise for raw file size, but for best compression 309this method doesn't optimise for raw file size, but for best compression
289(that means that the uncompressed file size is a bit larger, but the files 310(that means that the uncompressed file size is a bit larger, but the files
290compress better, e.g. with F<upx>). 311compress better, e.g. with F<upx>).
291 312
313Last not least, if you need accurate line numbers in error messages,
292Last not least, in the unlikely case where C<pod> is too slow, or some 314or in the unlikely case where C<pod> is too slow, or some module gets
293module gets mistreated, you can specify C<none> to not mangle included 315mistreated, you can specify C<none> to not mangle included perl sources in
294perl sources in any way. 316any way.
295 317
296=item --perl 318=item --perl
297 319
298After writing out the bundle files, try to link a new perl interpreter. It 320After writing out the bundle files, try to link a new perl interpreter. It
299will be called F<perl> and will be left in the current working 321will be called F<perl> and will be left in the current working
302This switch is automatically used when F<staticperl> is invoked with the 324This switch is automatically used when F<staticperl> is invoked with the
303C<mkperl> command (instead of C<mkbundle>): 325C<mkperl> command (instead of C<mkbundle>):
304 326
305 # build a new ./perl with only common::sense in it - very small :) 327 # build a new ./perl with only common::sense in it - very small :)
306 staticperl mkperl -Mcommon::sense 328 staticperl mkperl -Mcommon::sense
329
330=item --app name
331
332After writing out the bundle files, try to link a new standalone
333program. It will be called C<name>, and the bundle files get removed after
334linking it.
335
336The difference to the (mutually exclusive) C<--perl> option is that the
337binary created by this option will not try to act as a perl interpreter -
338instead it will simply initialise the perl interpreter, clean it up and
339exit.
340
341This switch is automatically used when F<staticperl> is invoked with the
342C<mkapp> command (instead of C<mkbundle>):
343
344To let it do something useful you I<must> add some boot code, e.g. with
345the C<--boot> option.
346
347Example: create a standalone perl binary that will execute F<appfile> when
348it is started.
349
350 staticperl mkbundle --app myexe --boot appfile
307 351
308=item --use module | -Mmodule 352=item --use module | -Mmodule
309 353
310Include the named module and all direct dependencies. This is done by 354Include the named module and all direct dependencies. This is done by
311C<require>'ing the module in a subprocess and tracing which other modules 355C<require>'ing the module in a subprocess and tracing which other modules
382 # specification file 426 # specification file
383 add file1 myfiles/file1 427 add file1 myfiles/file1
384 add file2 myfiles/file2 428 add file2 myfiles/file2
385 add file3 myfiles/file3 429 add file3 myfiles/file3
386 430
431=item --binadd "file" | --add "file alias"
432
433Just like C<--add>, except that it treats the file as binary and adds it
434without any processing.
435
436You should probably add a C</> prefix to avoid clashing with embedded
437perl files (whose paths do not start with C</>), and/or use a special
438directory, such as C</res/name>.
439
440You can later get a copy of these files by calling C<staticperl::find
441"alias">.
442
387=item --static 443=item --static
388 444
389When C<--perl> is also given, link statically instead of dynamically. The 445When C<--perl> is also given, link statically instead of dynamically. The
390default is to link the new perl interpreter fully dynamic (that means all 446default is to link the new perl interpreter fully dynamic (that means all
391perl modules are linked statically, but all external libraries are still 447perl modules are linked statically, but all external libraries are still
402Any other argument is interpreted as a bundle specification file, which 458Any other argument is interpreted as a bundle specification file, which
403supports most long options (without extra quoting), one option per line. 459supports most long options (without extra quoting), one option per line.
404 460
405=back 461=back
406 462
407=head2 F<STATCPERL> CONFIGURATION AND HOOKS 463=head2 F<STATICPERL> CONFIGURATION AND HOOKS
408 464
409During (each) startup, F<staticperl> tries to source the following shell 465During (each) startup, F<staticperl> tries to source the following shell
410files in order: 466files in order:
411 467
412 /etc/staticperlrc 468 /etc/staticperlrc
428=item C<EMAIL> 484=item C<EMAIL>
429 485
430The e-mail address of the person who built this binary. Has no good 486The e-mail address of the person who built this binary. Has no good
431default, so should be specified by you. 487default, so should be specified by you.
432 488
433=back 489=item C<CPAN>
434 490
491The URL of the CPAN mirror to use (e.g. L<http://mirror.netcologne.de/cpan/>).
492
493=item C<EXTRA_MODULES>
494
495Additional modules installed during F<staticperl install>. Here you can
496set which modules you want have to installed from CPAN.
497
498Example: I really really need EV, AnyEvent, Coro and AnyEvent::AIO.
499
500 EXTRA_MODULES="EV AnyEvent Coro AnyEvent::AIO"
501
502Note that you can also use a C<postinstall> hook to achieve this, and
503more.
504
505=back
506
435=head4 Variables you I<might want> to override 507=head4 Variables you might I<want> to override
436 508
437=over 4 509=over 4
438 510
511=item C<STATICPERL>
512
513The directory where staticperl stores all its files
514(default: F<~/.staticperl>).
515
516=item C<PERL_MM_USE_DEFAULT>, C<EV_EXTRA_DEFS>, ...
517
518Usually set to C<1> to make modules "less inquisitive" during their
519installation, you can set any environment variable you want - some modules
520(such as L<Coro> or L<EV>) use environment variables for further tweaking.
521
439=item C<PERLVER> 522=item C<PERL_VERSION>
440 523
441The perl version to install - default is currently C<5.12.2>, but C<5.8.9> 524The perl version to install - default is currently C<5.12.2>, but C<5.8.9>
442is also a good choice (5.8.9 is much smaller than 5.12.2, while 5.10.1 is 525is also a good choice (5.8.9 is much smaller than 5.12.2, while 5.10.1 is
443about as big as 5.12.2). 526about as big as 5.12.2).
444 527
445=item C<CPAN> 528=item C<PERL_PREFIX>
446 529
447The URL of the CPAN mirror to use (e.g. L<http://mirror.netcologne.de/cpan/>). 530The prefix where perl gets installed (default: F<$STATICPERL/perl>),
531i.e. where the F<bin> and F<lib> subdirectories will end up.
532
533=item C<PERL_CONFIGURE>
534
535Additional Configure options - these are simply passed to the perl
536Configure script. For example, if you wanted to enable dynamic loading,
537you could pass C<-Dusedl>. To enable ithreads (Why would you want that
538insanity? Don't! Use L<forks> instead!) you would pass C<-Duseithreads>
539and so on.
540
541More commonly, you would either activate 64 bit integer support
542(C<-Duse64bitint>), or disable large files support (-Uuselargefiles), to
543reduce filesize further.
448 544
449=item C<PERL_CPPFLAGS>, C<PERL_OPTIMIZE>, C<PERL_LDFLAGS>, C<PERL_LIBS> 545=item C<PERL_CPPFLAGS>, C<PERL_OPTIMIZE>, C<PERL_LDFLAGS>, C<PERL_LIBS>
450 546
451These flags are passed to perl's F<Configure> script, and are generally 547These flags are passed to perl's F<Configure> script, and are generally
452optimised for small size (at the cost of performance). Since they also 548optimised for small size (at the cost of performance). Since they also
453contain subtle workarounds around various build issues, changing these 549contain subtle workarounds around various build issues, changing these
454usually requires understanding their default values - best look at the top 550usually requires understanding their default values - best look at the top
455of the F<staticperl> script for more info on these. 551of the F<staticperl> script for more info on these.
456 552
457=item C<STATICPERL>
458
459The directory where staticperl stores all its files
460(default: F<~/.staticperl>).
461
462=item C<PREFIX>
463
464The prefix where perl gets installed (default: F<$STATICPERL/perl>),
465i.e. where the F<bin> and F<lib> subdirectories will end up.
466
467=item C<PERL_MM_USE_DEFAULT>, C<EV_EXTRA_DEFS>, others
468
469Usually set to C<1> to make modules "less inquisitive" during their
470installation, you can set any environment variable you want - some modules
471(such as L<Coro> or L<EV>) use environment variables for further tweaking.
472
473=item C<EXTRA_MODULES>
474
475Additional modules installed during F<staticperl install>. Here you can
476set which modules you want have to installed from CPAN.
477
478Example: I really really need EV, AnyEvent, Coro and IO::AIO.
479
480 EXTRA_MODULES="EV AnyEvent Coro IO::AIO"
481
482Note that you can also use a C<postinstall> hook to achieve this, and
483more.
484
485=back 553=back
486 554
487=head4 Variables you I<probably do not want> to override 555=head4 Variables you probably I<do not want> to override
488 556
489=over 4 557=over 4
490 558
491=item C<MKBUNDLE> 559=item C<MKBUNDLE>
492 560
508 576
509Example: install extra modules from CPAN and from some directories 577Example: install extra modules from CPAN and from some directories
510at F<staticperl install> time. 578at F<staticperl install> time.
511 579
512 postinstall() { 580 postinstall() {
513 rm -rf lib/threads.* # weg mit Schaden 581 rm -rf lib/threads* # weg mit Schaden
514 instcpan IO::AIO EV 582 instcpan IO::AIO EV
515 instsrc ~/src/AnyEvent 583 instsrc ~/src/AnyEvent
516 instsrc ~/src/XML-Sablotron-1.0100001 584 instsrc ~/src/XML-Sablotron-1.0100001
517 instcpan AnyEvent::HTTPD 585 instcpan Anyevent::AIO AnyEvent::HTTPD
518 } 586 }
519 587
520=over 4 588=over 4
589
590=item preconfigure
591
592Called just before running F<./Configur> in the perl source
593directory. Current working directory is the perl source directory.
594
595This can be used to set any C<PERL_xxx> variables, which might be costly
596to compute.
521 597
522=item postconfigure 598=item postconfigure
523 599
524Called after configuring, but before building perl. Current working 600Called after configuring, but before building perl. Current working
525directory is the perl source directory. 601directory is the perl source directory.
526 602
527Could be used to tailor/patch config.sh (followed by F<./Configure -S>) or 603Could be used to tailor/patch config.sh (followed by F<sh Configure -S>)
528do any other modifications. 604or do any other modifications.
529 605
530=item postbuild 606=item postbuild
531 607
532Called after building, but before installing perl. Current working 608Called after building, but before installing perl. Current working
533directory is the perl source directory. 609directory is the perl source directory.
548The script must return with a zero exit status, or the installation will 624The script must return with a zero exit status, or the installation will
549fail. 625fail.
550 626
551=back 627=back
552 628
629=head1 ANATOMY OF A BUNDLE
630
631When not building a new perl binary, C<mkbundle> will leave a number of
632files in the current working directory, which can be used to embed a perl
633interpreter in your program.
634
635Intimate knowledge of L<perlembed> and preferably some experience with
636embedding perl is highly recommended.
637
638C<mkperl> (or the C<--perl> option) basically does this to link the new
639interpreter (it also adds a main program to F<bundle.>):
640
641 $Config{cc} $(cat bundle.ccopts) -o perl bundle.c $(cat bundle.ldopts)
642
643=over 4
644
645=item bundle.h
646
647A header file that contains the prototypes of the few symbols "exported"
648by bundle.c, and also exposes the perl headers to the application.
649
650=over 4
651
652=item staticperl_init ()
653
654Initialises the perl interpreter. You can use the normal perl functions
655after calling this function, for example, to define extra functions or
656to load a .pm file that contains some initialisation code, or the main
657program function:
658
659 XS (xsfunction)
660 {
661 dXSARGS;
662
663 // now we have items, ST(i) etc.
664 }
665
666 static void
667 run_myapp(void)
668 {
669 staticperl_init ();
670 newXSproto ("myapp::xsfunction", xsfunction, __FILE__, "$$;$");
671 eval_pv ("require myapp::main", 1); // executes "myapp/main.pm"
672 }
673
674=item staticperl_xs_init (pTHX)
675
676Sometimes you need direct control over C<perl_parse> and C<perl_run>, in
677which case you do not want to use C<staticperl_init> but call them on your
678own.
679
680Then you need this function - either pass it directly as the C<xs_init>
681function to C<perl_parse>, or call it from your own C<xs_init> function.
682
683=item staticperl_cleanup ()
684
685In the unlikely case that you want to destroy the perl interpreter, here
686is the corresponding function.
687
688=item PerlInterpreter *staticperl
689
690The perl interpreter pointer used by staticperl. Not normally so useful,
691but there it is.
692
693=back
694
695=item bundle.ccopts
696
697Contains the compiler options required to compile at least F<bundle.c> and
698any file that includes F<bundle.h> - you should probably use it in your
699C<CFLAGS>.
700
701=item bundle.ldopts
702
703The linker options needed to link the final program.
704
705=back
706
707=head1 RUNTIME FUNCTIONALITY
708
709Binaries created with C<mkbundle>/C<mkperl> contain extra functions, which
710are required to access the bundled perl sources, but might be useful for
711other purposes.
712
713In addition, for the embedded loading of perl files to work, F<staticperl>
714overrides the C<@INC> array.
715
716=over 4
717
718=item $file = staticperl::find $path
719
720Returns the data associated with the given C<$path>
721(e.g. C<Digest/MD5.pm>, C<auto/POSIX/autosplit.ix>), which is basically
722the UNIX path relative to the perl library directory.
723
724Returns C<undef> if the file isn't embedded.
725
726=item @paths = staticperl::list
727
728Returns the list of all paths embedded in this binary.
729
730=back
731
732=head1 FULLY STATIC BINARIES - BUILDROOT
733
734To make truly static (Linux-) libraries, you might want to have a look at
735buildroot (L<http://buildroot.uclibc.org/>).
736
737Buildroot is primarily meant to set up a cross-compile environment (which
738is not so useful as perl doesn't quite like cross compiles), but it can also compile
739a chroot environment where you can use F<staticperl>.
740
741To do so, download buildroot, and enable "Build options => development
742files in target filesystem" and optionally "Build options => gcc
743optimization level (optimize for size)". At the time of writing, I had
744good experiences with GCC 4.4.x but not GCC 4.5.
745
746To minimise code size, I used C<-pipe -ffunction-sections -fdata-sections
747-finline-limit=8 -fno-builtin-strlen -mtune=i386>. The C<-mtune=i386>
748doesn't decrease codesize much, but it makes the file much more
749compressible.
750
751If you don't need Coro or threads, you can go with "linuxthreads.old" (or
752no thread support). For Coro, it is highly recommended to switch to a
753uClibc newer than 0.9.31 (at the time of this writing, I used the 20101201
754snapshot) and enable NPTL, otherwise Coro needs to be configured with the
755ultra-slow pthreads backend to work around linuxthreads bugs (it also uses
756twice the address space needed for stacks).
757
758If you use C<linuxthreads.old>, then you should also be aware that
759uClibc shares C<errno> between all threads when statically linking. See
760L<http://lists.uclibc.org/pipermail/uclibc/2010-June/044157.html> for a
761workaround (And L<https://bugs.uclibc.org/2089> for discussion).
762
763C<ccache> support is also recommended, especially if you want
764to play around with buildroot options. Enabling the C<miniperl>
765package will probably enable all options required for a successful
766perl build. F<staticperl> itself additionally needs either C<wget>
767(recommended, for CPAN) or C<curl>.
768
769As for shells, busybox should provide all that is needed, but the default
770busybox configuration doesn't include F<comm> which is needed by perl -
771either make a custom busybox config, or compile coreutils.
772
773For the latter route, you might find that bash has some bugs that keep
774it from working properly in a chroot - either use dash (and link it to
775F</bin/sh> inside the chroot) or link busybox to F</bin/sh>, using it's
776built-in ash shell.
777
778Finally, you need F</dev/null> inside the chroot for many scripts to work
779- F<cp /dev/null output/target/dev> or bind-mounting your F</dev> will
780both provide this.
781
782After you have compiled and set up your buildroot target, you can copy
783F<staticperl> from the C<App::Staticperl> distribution or from your
784perl f<bin> directory (if you installed it) into the F<output/target>
785filesystem, chroot inside and run it.
786
553=head1 AUTHOR 787=head1 AUTHOR
554 788
555 Marc Lehmann <schmorp@schmorp.de> 789 Marc Lehmann <schmorp@schmorp.de>
556 http://software.schmorp.de/pkg/staticperl.html 790 http://software.schmorp.de/pkg/staticperl.html

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines