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.24 by root, Wed Dec 15 00:17:47 2010 UTC vs.
Revision 1.26 by root, Tue Dec 21 19:14:56 2010 UTC

278 -MAnyEvent::Impl::Perl -MAnyEvent::HTTPD -MURI::http 278 -MAnyEvent::Impl::Perl -MAnyEvent::HTTPD -MURI::http
279 279
280 # run it 280 # run it
281 ./app 281 ./app
282 282
283Here are the three phase 2 commands:
284
285=over 4
286
287=item F<staticperl mkbundle> args...
288
289The "default" bundle command - it interprets the given bundle options and
290writes out F<bundle.h>, F<bundle.c>, F<bundle.ccopts> and F<bundle.ldopts>
291files, useful for embedding.
292
293=item F<staticperl mkperl> args...
294
295Creates a bundle just like F<staticperl mkbundle> (in fact, it's the same
296as invoking F<staticperl mkbundle --perl> args...), but then compiles and
297links a new perl interpreter that embeds the created bundle, then deletes
298all intermediate files.
299
300=item F<staticperl mkapp> filename args...
301
302Does the same as F<staticperl mkbundle> (in fact, it's the same as
303invoking F<staticperl mkbundle --app> filename args...), but then compiles
304and links a new standalone application that simply initialises the perl
305interpreter.
306
307The difference to F<staticperl mkperl> is that the standalone application
308does not act like a perl interpreter would - in fact, by default it would
309just do nothing and exit immediately, so you should specify some code to
310be executed via the F<--boot> option.
311
312=back
313
283=head3 OPTION PROCESSING 314=head3 OPTION PROCESSING
284 315
285All options can be given as arguments on the command line (typically 316All options can be given as arguments on the command line (typically
286using long (e.g. C<--verbose>) or short option (e.g. C<-v>) style). Since 317using long (e.g. C<--verbose>) or short option (e.g. C<-v>) style). Since
287specifying a lot of modules can make the command line very cumbersome, 318specifying a lot of modules can make the command line very cumbersome, you
288you can put all long options into a "bundle specification file" (with or 319can put all long options into a "bundle specification file" (one option
289without C<--> prefix) and specify this bundle file instead. 320per line, with or without C<--> prefix) and specify this bundle file
321instead.
290 322
291For example, the command given earlier could also look like this: 323For example, the command given earlier could also look like this:
292 324
293 staticperl mkperl httpd.bundle 325 staticperl mkperl httpd.bundle
294 326
299 use AnyEvent::HTTPD 331 use AnyEvent::HTTPD
300 use URI::http 332 use URI::http
301 add eg/httpd httpd.pm 333 add eg/httpd httpd.pm
302 334
303All options that specify modules or files to be added are processed in the 335All options that specify modules or files to be added are processed in the
304order given on the command line (that affects the C<--use> and C<--eval> 336order given on the command line.
305options at the moment).
306 337
307=head3 PACKAGE SELECTION WORKFLOW 338=head3 BUNDLE CREATION WORKFLOW
308 339
309F<staticperl mkbundle> has a number of options to control package 340F<staticperl mkbundle> works by first assembling a list of candidate
310selection. This section describes how they interact with each other. Also, 341files and modules to include, then filtering them by include/exclude
311since I am still a newbie w.r.t. these issues, maybe future versions of 342patterns. The remaining modules (together with their direct depdendencies,
312F<staticperl> will change this, so watch out :) 343such as link libraries and AutoLoader files) are then converted into
344bundle files suitable for embedding. Afterwards, F<staticperl mkbundle>
345can optionally build a new perl interpreter or a standalone application.
313 346
314The idiom "in order" means "in order that they are specified on the
315commandline". If you use a bundle specification file, then the options
316will be processed as if they were given in place of the bundle file name.
317
318=over 4 347=over 4
319 348
320=item 1. apply all C<--use>, C<--eval>, C<--add>, C<--addbin> and 349=item Step 0: Generic argument processing.
321C<--incglob> options, in order.
322 350
323In addition, C<--use> and C<--eval> dependencies will be added when the 351The following options influence F<staticperl mkbundle> itself.
324options are processed.
325
326=item 2. apply all C<--include> and C<--exclude> options, in order.
327
328All this step does is potentially reduce the number of files already
329selected or found in phase 1.
330
331=item 3. find all modules (== F<.pm> files), gather their static archives
332(F<.a>) and AutoLoader splitfiles (F<.ix> and F<.al> files), find any
333extra libraries they need for linking (F<extralibs.ld>) and optionally
334evaluate any F<.packlist> files.
335
336This step is required to link against XS extensions and also adds files
337required for L<AutoLoader> to do it's job.
338
339=back
340
341After this, all the files selected for bundling will be read and processed
342(stripped), the bundle files will be written, and optionally a new F<perl>
343or application binary will be linked.
344
345=head3 MKBUNDLE OPTIONS
346 352
347=over 4 353=over 4
348 354
349=item --verbose | -v 355=item --verbose | -v
350 356
352 358
353=item --quiet | -q 359=item --quiet | -q
354 360
355Decreases the verbosity level by one. 361Decreases the verbosity level by one.
356 362
363=item any other argument
364
365Any other argument is interpreted as a bundle specification file, which
366supports most long options (without extra quoting), one option per line.
367
368=back
369
370=item Step 1: gather candidate files and modules
371
372In this step, modules, perl libraries (F<.pl> files) and other files are
373selected for inclusion in the bundle. The relevant options are executed
374in order (this makes a difference mostly for C<--eval>, which can rely on
375earlier C<--use> options to have been executed).
376
377=over 4
378
379=item C<--use> F<module> | C<-M>F<module>
380
381Include the named module and trace direct dependencies. This is done by
382C<require>'ing the module in a subprocess and tracing which other modules
383and files it actually loads.
384
385Example: include AnyEvent and AnyEvent::Impl::Perl.
386
387 staticperl mkbundle --use AnyEvent --use AnyEvent::Impl::Perl
388
389Sometimes you want to load old-style "perl libraries" (F<.pl> files), or
390maybe other weirdly named files. To do that, you need to quote the name in
391single or double quotes. When given on the command line, you probably need
392to quote once more to avoid your shell interpreting it. Common cases that
393need this are F<Config_heavy.pl> and F<utf8_heavy.pl>.
394
395Example: include the required files for F<perl -V> to work in all its
396glory (F<Config.pm> is included automatically by this).
397
398 # bourne shell
399 staticperl mkbundle --use '"Config_heavy.pl"'
400
401 # bundle specification file
402 use "Config_heavy.pl"
403
404The C<-M>module syntax is included as an alias that might be easier to
405remember than C<--use>. Or maybe it confuses people. Time will tell. Or
406maybe not. Sigh.
407
408=item C<--eval> "perl code" | C<-e> "perl code"
409
410Sometimes it is easier (or necessary) to specify dependencies using perl
411code, or maybe one of the modules you use need a special use statement. In
412that case, you can use C<--eval> to execute some perl snippet or set some
413variables or whatever you need. All files C<require>'d or C<use>'d while
414executing the snippet are included in the final bundle.
415
416Keep in mind that F<mkbundle> will only C<require> the modules named
417by the C<--use> option, so do not expect the symbols from modules you
418C<--use>'d earlier on the command line to be available.
419
420Example: force L<AnyEvent> to detect a backend and therefore include it
421in the final bundle.
422
423 staticperl mkbundle --eval 'use AnyEvent; AnyEvent::detect'
424
425 # or like this
426 staticperl mkbundle -MAnyEvent --eval 'AnyEvent::detect'
427
428Example: use a separate "bootstrap" script that C<use>'s lots of modules
429and also include this in the final bundle, to be executed automatically
430when the interpreter is initialised.
431
432 staticperl mkbundle --eval 'do "bootstrap"' --boot bootstrap
433
434=item C<--boot> F<filename>
435
436Include the given file in the bundle and arrange for it to be
437executed (using C<require>) before the main program when the new perl
438is initialised. This can be used to modify C<@INC> or do similar
439modifications before the perl interpreter executes scripts given on the
440command line (or via C<-e>). This works even in an embedded interpreter -
441the file will be executed during interpreter initialisation in that case.
442
443=item C<--incglob> pattern
444
445This goes through all standard library directories and tries to match any
446F<.pm> and F<.pl> files against the extended glob pattern (see below). If
447a file matches, it is added. The pattern is matched against the full path
448of the file (sans the library directory prefix), e.g. F<Sys/Syslog.pm>.
449
450This is very useful to include "everything":
451
452 --incglob '*'
453
454It is also useful for including perl libraries, or trees of those, such as
455the unicode database files needed by some perl builtins, the regex engine
456and other modules.
457
458 --incglob '/unicore/**.pl'
459
460=item C<--add> F<file> | C<--add> "F<file> alias"
461
462Adds the given (perl) file into the bundle (and optionally call it
463"alias"). The F<file> is either an absolute path or a path relative to
464the current directory. If an alias is specified, then this is the name it
465will use for C<@INC> searches, otherfile the F<file> will be used as the
466internal name.
467
468This switch is used to include extra files into the bundle.
469
470Example: embed the file F<httpd> in the current directory as F<httpd.pm>
471when creating the bundle.
472
473 staticperl mkperl --add "httpd httpd.pm"
474
475Example: add local files as extra modules in the bundle.
476
477 # specification file
478 add file1 myfiles/file1.pm
479 add file2 myfiles/file2.pm
480 add file3 myfiles/file3.pl
481
482 # then later, in perl, use
483 use myfiles::file1;
484 require myfiles::file2;
485 my $res = do "myfiles/file3.pl";
486
487=item C<--binadd> F<file> | C<--add> "F<file> alias"
488
489Just like C<--add>, except that it treats the file as binary and adds it
490without any postprocessing (perl files might get stripped to reduce their
491size).
492
493You should probably add a C</> prefix to avoid clashing with embedded perl
494files (whose paths do not start with C</>), and/or use a special directory
495prefix, such as C</res/name>.
496
497You can later get a copy of these files by calling C<staticperl::find
498"alias">.
499
500An alternative way to embed binary files is to convert them to perl and
501use C<do> to get the contents - this method is a bit cumbersome, but works
502both inside and outside of a staticperl bundle:
503
504 # a "binary" file, call it "bindata.pl"
505 <<'SOME_MARKER'
506 binary data NOT containing SOME_MARKER
507 SOME_MARKER
508
509 # load the binary
510 chomp (my $data = do "bindata.pl");
511
512=back
513
514=item Step 2: filter all files using C<--include> and C<--exclude> options.
515
516After all candidate files and modules are added, they are I<filtered>
517by a combination of C<--include> and C<--exclude> patterns (there is an
518implicit C<--include **> at the end, so if no filters are specified, all
519files are included).
520
521All that this step does is potentially reduce the number of files that are
522to be included - no new files are added during this step.
523
524=over 4
525
526=item C<--include> pattern | C<-i> pattern | C<--exclude> pattern | C<-x> pattern
527
528These specify an include or exclude pattern to be applied to the candidate
529file list. An include makes sure that the given files will be part of the
530resulting file set, an exclude will exclude remaining files. The patterns
531are "extended glob patterns" (see below).
532
533The patterns are applied "in order" - files included via earlier
534C<--include> specifications cannot be removed by any following
535C<--exclude>, and likewise, and file excluded by an earlier C<--exclude>
536cannot be added by any following C<--include>.
537
538For example, to include everything except C<Devel> modules, but still
539include F<Devel::PPPort>, you could use this:
540
541 --incglob '*' -i '/Devel/PPPort.pm' -x '/Devel/**'
542
543=back
544
545=item Step 3: add any extra or "hidden" dependencies.
546
547F<staticperl> currently knows about three extra types of depdendencies
548that are added automatically. Only one (F<.packlist> files) is currently
549optional and can be influenced, the others are always included:
550
551=over 4
552
553=item C<--usepacklist>
554
555Read F<.packlist> files for each distribution that happens to match a
556module name you specified. Sounds weird, and it is, so expect semantics to
557change somehow in the future.
558
559The idea is that most CPAN distributions have a F<.pm> file that matches
560the name of the distribution (which is rather reasonable after all).
561
562If this switch is enabled, then if any of the F<.pm> files that have been
563selected match an install distribution, then all F<.pm>, F<.pl>, F<.al>
564and F<.ix> files installed by this distribution are also included.
565
566For example, using this switch, when the L<URI> module is specified, then
567all L<URI> submodules that have been installed via the CPAN distribution
568are included as well, so you don't have to manually specify them.
569
570=item L<AutoLoader> splitfiles
571
572Some modules use L<AutoLoader> - less commonly (hopefully) used functions
573are split into separate F<.al> files, and an index (F<.ix>) file contains
574the prototypes.
575
576Both F<.ix> and F<.al> files will be detected automatically and added to
577the bundle.
578
579=item link libraries (F<.a> files)
580
581Modules using XS (or any other non-perl language extension compiled at
582installation time) will have a static archive (typically F<.a>). These
583will automatically be added to the linker options in F<bundle.ldopts>.
584
585Should F<staticperl> find a dynamic link library (typically F<.so>) it
586will warn about it - obviously this shouldn't happen unless you use
587F<staticperl> on the wrong perl, or one (probably wrongly) configured to
588use dynamic loading.
589
590=item extra libraries (F<extralibs.ld>)
591
592Some modules need linking against external libraries - these are found in
593F<extralibs.ld> and added to F<bundle.ldopts>.
594
595=back
596
597=item Step 4: write bundle files and optionally link a program
598
599At this point, the select files will be read, processed (stripped) and
600finally the bundle files get written to disk, and F<staticperl mkbundle>
601is normally finished. Optionally, it can go a step further and either link
602a new F<perl> binary with all selected modules and files inside, or build
603a standalone application.
604
605Both the contents of the bundle files and any extra linking is controlled
606by these options:
607
608=over 4
609
357=item --strip none|pod|ppi 610=item C<--strip> C<none>|C<pod>|C<ppi>
358 611
359Specify the stripping method applied to reduce the file of the perl 612Specify the stripping method applied to reduce the file of the perl
360sources included. 613sources included.
361 614
362The default is C<pod>, which uses the L<Pod::Strip> module to remove all 615The default is C<pod>, which uses the L<Pod::Strip> module to remove all
380After writing out the bundle files, try to link a new perl interpreter. It 633After writing out the bundle files, try to link a new perl interpreter. It
381will be called F<perl> and will be left in the current working 634will be called F<perl> and will be left in the current working
382directory. The bundle files will be removed. 635directory. The bundle files will be removed.
383 636
384This switch is automatically used when F<staticperl> is invoked with the 637This switch is automatically used when F<staticperl> is invoked with the
385C<mkperl> command (instead of C<mkbundle>): 638C<mkperl> command instead of C<mkbundle>.
386 639
387 # build a new ./perl with only common::sense in it - very small :) 640Example: build a new F<./perl> binary with only L<common::sense> inside -
641it will be even smaller than the standard perl interpreter as none of the
642modules of the base distribution (such as L<Fcntl>) will be included.
643
388 staticperl mkperl -Mcommon::sense 644 staticperl mkperl -Mcommon::sense
389 645
390=item --app name 646=item --app name
391 647
392After writing out the bundle files, try to link a new standalone 648After writing out the bundle files, try to link a new standalone
393program. It will be called C<name>, and the bundle files get removed after 649program. It will be called C<name>, and the bundle files get removed after
394linking it. 650linking it.
651
652This switch is automatically used when F<staticperl> is invoked with the
653C<mkapp> command instead of C<mkbundle>.
395 654
396The difference to the (mutually exclusive) C<--perl> option is that the 655The difference to the (mutually exclusive) C<--perl> option is that the
397binary created by this option will not try to act as a perl interpreter - 656binary created by this option will not try to act as a perl interpreter -
398instead it will simply initialise the perl interpreter, clean it up and 657instead it will simply initialise the perl interpreter, clean it up and
399exit. 658exit.
400 659
401This switch is automatically used when F<staticperl> is invoked with the 660This means that, by default, it will do nothing but burna few CPU cycles
402C<mkapp> command (instead of C<mkbundle>):
403
404To let it do something useful you I<must> add some boot code, e.g. with 661- for it to do something useful you I<must> add some boot code, e.g. with
405the C<--boot> option. 662the C<--boot> option.
406 663
407Example: create a standalone perl binary that will execute F<appfile> when 664Example: create a standalone perl binary called F<./myexe> that will
408it is started. 665execute F<appfile> when it is started.
409 666
410 staticperl mkbundle --app myexe --boot appfile 667 staticperl mkbundle --app myexe --boot appfile
411 668
412=item --use module | -Mmodule
413
414Include the named module and all direct dependencies. This is done by
415C<require>'ing the module in a subprocess and tracing which other modules
416and files it actually loads. If the module uses L<AutoLoader>, then all
417splitfiles will be included as well.
418
419Example: include AnyEvent and AnyEvent::Impl::Perl.
420
421 staticperl mkbundle --use AnyEvent --use AnyEvent::Impl::Perl
422
423Sometimes you want to load old-style "perl libraries" (F<.pl> files), or
424maybe other weirdly named files. To do that, you need to quote the name in
425single or double quotes. When given on the command line, you probably need
426to quote once more to avoid your shell interpreting it. Common cases that
427need this are F<Config_heavy.pl> and F<utf8_heavy.pl>.
428
429Example: include the required files for F<perl -V> to work in all its
430glory (F<Config.pm> is included automatically by this).
431
432 # bourne shell
433 staticperl mkbundle --use '"Config_heavy.pl"'
434
435 # bundle specification file
436 use "Config_heavy.pl"
437
438The C<-Mmodule> syntax is included as an alias that might be easier to
439remember than C<use>. Or maybe it confuses people. Time will tell. Or
440maybe not. Argh.
441
442=item --eval "perl code" | -e "perl code"
443
444Sometimes it is easier (or necessary) to specify dependencies using perl
445code, or maybe one of the modules you use need a special use statement. In
446that case, you can use C<eval> to execute some perl snippet or set some
447variables or whatever you need. All files C<require>'d or C<use>'d in the
448script are included in the final bundle.
449
450Keep in mind that F<mkbundle> will only C<require> the modules named
451by the C<--use> option, so do not expect the symbols from modules you
452C<--use>'d earlier on the command line to be available.
453
454Example: force L<AnyEvent> to detect a backend and therefore include it
455in the final bundle.
456
457 staticperl mkbundle --eval 'use AnyEvent; AnyEvent::detect'
458
459 # or like this
460 staticperl mkbundle -MAnyEvent --eval 'use AnyEvent; AnyEvent::detect'
461
462Example: use a separate "bootstrap" script that C<use>'s lots of modules
463and include this in the final bundle, to be executed automatically.
464
465 staticperl mkbundle --eval 'do "bootstrap"' --boot bootstrap
466
467=item --boot filename
468
469Include the given file in the bundle and arrange for it to be executed
470(using a C<require>) before anything else when the new perl is
471initialised. This can be used to modify C<@INC> or anything else before
472the perl interpreter executes scripts given on the command line (or via
473C<-e>). This works even in an embedded interpreter.
474
475=item --usepacklist
476
477Read F<.packlist> files for each distribution that happens to match a
478module name you specified. Sounds weird, and it is, so expect semantics to
479change somehow in the future.
480
481The idea is that most CPAN distributions have a F<.pm> file that matches
482the name of the distribution (which is rather reasonable after all).
483
484If this switch is enabled, then if any of the F<.pm> files that have been
485selected match an install distribution, then all F<.pm>, F<.pl>, F<.al>
486and F<.ix> files installed by this distribution are also included.
487
488For example, using this switch, when the L<URI> module is specified, then
489all L<URI> submodules that have been installed via the CPAN distribution
490are included as well, so you don't have to manually specify them.
491
492=item --incglob pattern
493
494This goes through all library directories and tries to match any F<.pm>
495and F<.pl> files against the extended glob pattern (see below). If a file
496matches, it is added. This switch will automatically detect L<AutoLoader>
497files and the required link libraries for XS modules, but it will I<not>
498scan the file for dependencies (at the moment).
499
500This is mainly useful to include "everything":
501
502 --incglob '*'
503
504Or to include perl libraries, or trees of those, such as the unicode
505database files needed by many other modules:
506
507 --incglob '/unicore/**.pl'
508
509=item --add file | --add "file alias"
510
511Adds the given (perl) file into the bundle (and optionally call it
512"alias"). This is useful to include any custom files into the bundle.
513
514Example: embed the file F<httpd> as F<httpd.pm> when creating the bundle.
515
516 staticperl mkperl --add "httpd httpd.pm"
517
518It is also a great way to add any custom modules:
519
520 # specification file
521 add file1 myfiles/file1
522 add file2 myfiles/file2
523 add file3 myfiles/file3
524
525=item --binadd file | --add "file alias"
526
527Just like C<--add>, except that it treats the file as binary and adds it
528without any processing.
529
530You should probably add a C</> prefix to avoid clashing with embedded
531perl files (whose paths do not start with C</>), and/or use a special
532directory, such as C</res/name>.
533
534You can later get a copy of these files by calling C<staticperl::find
535"alias">.
536
537=item --include pattern | -i pattern | --exclude pattern | -x pattern
538
539These two options define an include/exclude filter that is used after all
540files selected by the other options have been found. Each include/exclude
541is applied to all files found so far - an include makes sure that the
542given files will be part of the resulting file set, an exclude will
543exclude files. The patterns are "extended glob patterns" (see below).
544
545For example, to include everything, except C<Devel> modules, but still
546include F<Devel::PPPort>, you could use this:
547
548 --incglob '*' -i '/Devel/PPPort.pm' -x '/Devel/**'
549
550=item --static 669=item --static
551 670
552When C<--perl> is also given, link statically instead of dynamically. The 671Add C<-static> to F<bundle.ldopts>, which means a fully static (if
672supported by the OS) executable will be created. This is not immensely
673useful when just creating the bundle files, but is most useful when
674linking a binary with the C<--perl> or C<--app> options.
675
553default is to link the new perl interpreter fully dynamic (that means all 676The default is to link the new binary dynamically (that means all perl
554perl modules are linked statically, but all external libraries are still 677modules are linked statically, but all external libraries are still
555referenced dynamically). 678referenced dynamically).
556 679
557Keep in mind that Solaris doesn't support static linking at all, and 680Keep in mind that Solaris doesn't support static linking at all, and
558systems based on GNU libc don't really support it in a usable fashion 681systems based on GNU libc don't really support it in a very usable
559either. Try uClibc if you want to create fully statically linked 682fashion either. Try uClibc if you want to create fully statically linked
560executables, or try the C<--staticlibs> option to link only some libraries 683executables, or try the C<--staticlib> option to link only some libraries
561statically. 684statically.
562 685
563=item --staticlib libname 686=item --staticlib libname
564 687
565When not linking fully statically, this option allows you to link specific 688When not linking fully statically, this option allows you to link specific
573 696
574Example: link libcrypt statically into the binary. 697Example: link libcrypt statically into the binary.
575 698
576 staticperl mkperl -MIO::AIO --staticlib crypt 699 staticperl mkperl -MIO::AIO --staticlib crypt
577 700
578 # ldopts might nwo contain: 701 # ldopts might now contain:
579 # -lm -Wl,-Bstatic -lcrypt -Wl,-Bdynamic -lpthread 702 # -lm -Wl,-Bstatic -lcrypt -Wl,-Bdynamic -lpthread
580 703
581=item any other argument 704=back
582
583Any other argument is interpreted as a bundle specification file, which
584supports most long options (without extra quoting), one option per line.
585 705
586=back 706=back
587 707
588=head3 EXTENDED GLOB PATTERNS 708=head3 EXTENDED GLOB PATTERNS
589 709

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines