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

Comparing App-Staticperl/README (file contents):
Revision 1.4 by root, Mon Dec 6 21:19:04 2010 UTC vs.
Revision 1.5 by root, Tue Dec 7 10:40:39 2010 UTC

1NAME 1NAME
2 staticperl - perl, libc, 50 modules all in one 500kb file 2 staticperl - perl, libc, 100 modules, all in one 500kb file
3 3
4SYNOPSIS 4SYNOPSIS
5 staticperl help # print the embedded documentation 5 staticperl help # print the embedded documentation
6 staticperl fetch # fetch and unpack perl sources 6 staticperl fetch # fetch and unpack perl sources
7 staticperl configure # fetch and then configure perl 7 staticperl configure # fetch and then configure perl
… …
31 statically, you can create (or embed) a single file that contains perl 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 32 interpreter, libc, all the modules you need and all the libraries you
33 need. 33 need.
34 34
35 With uClibc and upx on x86, you can create a single 500kb binary that 35 With uClibc and upx on x86, you can create a single 500kb binary that
36 contains perl and 50 modules such as AnyEvent, EV, IO::AIO, Coro and so 36 contains perl and 100 modules such as POSIX, AnyEvent, EV, IO::AIO, Coro
37 on. Or any other choice of modules. 37 and so on. Or any other choice of modules.
38 38
39 The created files do not need write access to the file system (like PAR 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 40 does). In fact, since this script is in many ways similar to
41 PAR::Packer, here are the differences: 41 PAR::Packer, here are the differences:
42 42
… …
261 but is also a lot slower, so is best used for production builds. 261 but is also a lot slower, so is best used for production builds.
262 Note that this method doesn't optimise for raw file size, but for 262 Note that this method doesn't optimise for raw file size, but for
263 best compression (that means that the uncompressed file size is a 263 best compression (that means that the uncompressed file size is a
264 bit larger, but the files compress better, e.g. with upx). 264 bit larger, but the files compress better, e.g. with upx).
265 265
266 Last not least, if you need accurate line numbers in error messages,
266 Last not least, in the unlikely case where "pod" is too slow, or 267 or in the unlikely case where "pod" is too slow, or some module gets
267 some module gets mistreated, you can specify "none" to not mangle 268 mistreated, you can specify "none" to not mangle included perl
268 included perl sources in any way. 269 sources in any way.
269 270
270 --perl 271 --perl
271 After writing out the bundle files, try to link a new perl 272 After writing out the bundle files, try to link a new perl
272 interpreter. It will be called perl and will be left in the current 273 interpreter. It will be called perl and will be left in the current
273 working directory. The bundle files will be removed. 274 working directory. The bundle files will be removed.
… …
355 # specification file 356 # specification file
356 add file1 myfiles/file1 357 add file1 myfiles/file1
357 add file2 myfiles/file2 358 add file2 myfiles/file2
358 add file3 myfiles/file3 359 add file3 myfiles/file3
359 360
361 --binadd "file" | --add "file alias"
362 Just like "--add", except that it treats the file as binary and adds
363 it without any processing.
364
365 You should probably add a "/" prefix to avoid clashing with embedded
366 perl files (whose paths do not start with "/"), and/or use a special
367 directory, such as "/res/name".
368
369 You can later get a copy of these files by calling "staticperl::find
370 "alias"".
371
360 --static 372 --static
361 When "--perl" is also given, link statically instead of dynamically. 373 When "--perl" is also given, link statically instead of dynamically.
362 The default is to link the new perl interpreter fully dynamic (that 374 The default is to link the new perl interpreter fully dynamic (that
363 means all perl modules are linked statically, but all external 375 means all perl modules are linked statically, but all external
364 libraries are still referenced dynamically). 376 libraries are still referenced dynamically).
… …
392 Variables you *should* override 404 Variables you *should* override
393 "EMAIL" 405 "EMAIL"
394 The e-mail address of the person who built this binary. Has no good 406 The e-mail address of the person who built this binary. Has no good
395 default, so should be specified by you. 407 default, so should be specified by you.
396 408
397 Variables you might *want* to override
398 "PERLVER"
399 The perl version to install - default is currently 5.12.2, but 5.8.9
400 is also a good choice (5.8.9 is much smaller than 5.12.2, while
401 5.10.1 is about as big as 5.12.2).
402
403 "CPAN" 409 "CPAN"
404 The URL of the CPAN mirror to use (e.g. 410 The URL of the CPAN mirror to use (e.g.
405 <http://mirror.netcologne.de/cpan/>). 411 <http://mirror.netcologne.de/cpan/>).
406 412
407 "EXTRA_MODULES" 413 "EXTRA_MODULES"
408 Additional modules installed during staticperl install. Here you can 414 Additional modules installed during staticperl install. Here you can
409 set which modules you want have to installed from CPAN. 415 set which modules you want have to installed from CPAN.
410 416
411 Example: I really really need EV, AnyEvent, Coro and IO::AIO. 417 Example: I really really need EV, AnyEvent, Coro and AnyEvent::AIO.
412 418
413 EXTRA_MODULES="EV AnyEvent Coro IO::AIO" 419 EXTRA_MODULES="EV AnyEvent Coro AnyEvent::AIO"
414 420
415 Note that you can also use a "postinstall" hook to achieve this, and 421 Note that you can also use a "postinstall" hook to achieve this, and
416 more. 422 more.
423
424 Variables you might *want* to override
425 "STATICPERL"
426 The directory where staticperl stores all its files (default:
427 ~/.staticperl).
417 428
418 "PERL_MM_USE_DEFAULT", "EV_EXTRA_DEFS", ... 429 "PERL_MM_USE_DEFAULT", "EV_EXTRA_DEFS", ...
419 Usually set to 1 to make modules "less inquisitive" during their 430 Usually set to 1 to make modules "less inquisitive" during their
420 installation, you can set any environment variable you want - some 431 installation, you can set any environment variable you want - some
421 modules (such as Coro or EV) use environment variables for further 432 modules (such as Coro or EV) use environment variables for further
422 tweaking. 433 tweaking.
423 434
424 "STATICPERL" 435 "PERL_VERSION"
425 The directory where staticperl stores all its files (default: 436 The perl version to install - default is currently 5.12.2, but 5.8.9
426 ~/.staticperl). 437 is also a good choice (5.8.9 is much smaller than 5.12.2, while
438 5.10.1 is about as big as 5.12.2).
427 439
428 "PREFIX" 440 "PERL_PREFIX"
429 The prefix where perl gets installed (default: $STATICPERL/perl), 441 The prefix where perl gets installed (default: $STATICPERL/perl),
430 i.e. where the bin and lib subdirectories will end up. 442 i.e. where the bin and lib subdirectories will end up.
443
444 "PERL_CONFIGURE"
445 Additional Configure options - these are simply passed to the perl
446 Configure script. For example, if you wanted to enable dynamic
447 loading, you could pass "-Dusedl". To enable ithreads (Why would you
448 want that insanity? Don't! Use forks instead!) you would pass
449 "-Duseithreads" and so on.
450
451 More commonly, you would either activate 64 bit integer support
452 ("-Duse64bitint"), or disable large files support (-Uuselargefiles),
453 to reduce filesize further.
431 454
432 "PERL_CPPFLAGS", "PERL_OPTIMIZE", "PERL_LDFLAGS", "PERL_LIBS" 455 "PERL_CPPFLAGS", "PERL_OPTIMIZE", "PERL_LDFLAGS", "PERL_LIBS"
433 These flags are passed to perl's Configure script, and are generally 456 These flags are passed to perl's Configure script, and are generally
434 optimised for small size (at the cost of performance). Since they 457 optimised for small size (at the cost of performance). Since they
435 also contain subtle workarounds around various build issues, 458 also contain subtle workarounds around various build issues,
… …
487 functions. 510 functions.
488 511
489 The script must return with a zero exit status, or the installation 512 The script must return with a zero exit status, or the installation
490 will fail. 513 will fail.
491 514
515ANATOMY OF A BUNDLE
516 When not building a new perl binary, "mkbundle" will leave a number of
517 files in the current working directory, which can be used to embed a
518 perl interpreter in your program.
519
520 Intimate knowledge of perlembed and preferably some experience with
521 embedding perl is highly recommended.
522
523 "mkperl" (or the "--perl" option) basically does this to link the new
524 interpreter (it also adds a main program to bundle.):
525
526 $Config{cc} $(cat bundle.ccopts) -o perl bundle.c $(cat bundle.ldopts)
527
528 bundle.h
529 A header file that contains the prototypes of the few symbols
530 "exported" by bundle.c, and also exposes the perl headers to the
531 application.
532
533 staticperl_init ()
534 Initialises the perl interpreter. You can use the normal perl
535 functions after calling this function, for example, to define
536 extra functions or to load a .pm file that contains some
537 initialisation code, or the main program function:
538
539 XS (xsfunction)
540 {
541 dXSARGS;
542
543 // now we have items, ST(i) etc.
544 }
545
546 static void
547 run_myapp(void)
548 {
549 staticperl_init ();
550 newXSproto ("myapp::xsfunction", xsfunction, __FILE__, "$$;$");
551 eval_pv ("require myapp::main", 1); // executes "myapp/main.pm"
552 }
553
554 staticperl_xs_init (pTHX)
555 Sometimes you need direct control over "perl_parse" and
556 "perl_run", in which case you do not want to use
557 "staticperl_init" but call them on your own.
558
559 Then you need this function - either pass it directly as the
560 "xs_init" function to "perl_parse", or call it from your own
561 "xs_init" function.
562
563 staticperl_cleanup ()
564 In the unlikely case that you want to destroy the perl
565 interpreter, here is the corresponding function.
566
567 PerlInterpreter *staticperl
568 The perl interpreter pointer used by staticperl. Not normally so
569 useful, but there it is.
570
571 bundle.ccopts
572 Contains the compiler options required to compile at least bundle.c
573 and any file that includes bundle.h - you should probably use it in
574 your "CFLAGS".
575
576 bundle.ldopts
577 The linker options needed to link the final program.
578
579RUNTIME FUNCTIONALITY
580 Binaries created with "mkbundle"/"mkperl" contain extra functions, which
581 are required to access the bundled perl sources, but might be useful for
582 other purposes.
583
584 In addition, for the embedded loading of perl files to work, staticperl
585 overrides the @INC array.
586
587 $file = staticperl::find $path
588 Returns the data associated with the given $path (e.g.
589 "Digest/MD5.pm", "auto/POSIX/autosplit.ix"), which is basically the
590 UNIX path relative to the perl library directory.
591
592 Returns "undef" if the file isn't embedded.
593
594 @paths = staticperl::list
595 Returns the list of all paths embedded in this binary.
596
597FULLY STATIC BINARIES - BUILDROOT
598 To make truly static (Linux-) libraries, you might want to have a look
599 at buildroot (<http://buildroot.uclibc.org/>).
600
601 Buildroot is primarily meant to set up a cross-compile environment
602 (which is not so useful as perl doesn't quite like cross compiles), but
603 it can also compile a chroot environment where you can use staticperl.
604
605 To do so, download buildroot, and enable "Build options => development
606 files in target filesystem" and optionally "Build options => gcc
607 optimization level (optimize for size)". At the time of writing, I had
608 good experiences with GCC 4.4.x but not GCC 4.5.
609
610 To minimise code size, I used "-pipe -ffunction-sections -fdata-sections
611 -finline-limit=8 -fno-builtin-strlen -mtune=i386". The "-mtune=i386"
612 doesn't decrease codesize much, but it makes the file much more
613 compressible.
614
615 If you don't need Coro or threads, you can go with "linuxthreads.old"
616 (or no thread support). For Coro, it is highly recommended to switch to
617 a uClibc newer than 0.9.31 (at the time of this writing, I used the
618 20101201 snapshot) and enable NPTL, otherwise Coro needs to be
619 configured with the ultra-slow pthreads backend to work around
620 linuxthreads bugs (it also uses twice the address space needed for
621 stacks).
622
623 If you use "linuxthreads.old", then you should also be aware that uClibc
624 shares "errno" between all threads when statically linking. See
625 <http://lists.uclibc.org/pipermail/uclibc/2010-June/044157.html> for a
626 workaround (And <https://bugs.uclibc.org/2089> for discussion).
627
628 "ccache" support is also recommended, especially if you want to play
629 around with buildroot options. Enabling the "miniperl" package will
630 probably enable all options required for a successful perl build.
631 staticperl itself additionally needs either "wget" (recommended, for
632 CPAN) or "curl".
633
634 As for shells, busybox should provide all that is needed, but the
635 default busybox configuration doesn't include comm which is needed by
636 perl - either make a custom busybox config, or compile coreutils.
637
638 For the latter route, you might find that bash has some bugs that keep
639 it from working properly in a chroot - either use dash (and link it to
640 /bin/sh inside the chroot) or link busybox to /bin/sh, using it's
641 built-in ash shell.
642
643 Finally, you need /dev/null inside the chroot for many scripts to work -
644 cp /dev/null output/target/dev or bind-mounting your /dev will both
645 provide this.
646
647 After you have compiled and set up your buildroot target, you can copy
648 staticperl from the "App::Staticperl" distribution or from your perl
649 f<bin> directory (if you installed it) into the output/target
650 filesystem, chroot inside and run it.
651
492AUTHOR 652AUTHOR
493 Marc Lehmann <schmorp@schmorp.de> 653 Marc Lehmann <schmorp@schmorp.de>
494 http://software.schmorp.de/pkg/staticperl.html 654 http://software.schmorp.de/pkg/staticperl.html
495 655

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines