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

Comparing App-Staticperl/README (file contents):
Revision 1.9 by root, Wed Dec 15 00:18:04 2010 UTC vs.
Revision 1.10 by root, Wed Dec 22 01:23:37 2010 UTC

… …
259 -MAnyEvent::Impl::Perl -MAnyEvent::HTTPD -MURI::http 259 -MAnyEvent::Impl::Perl -MAnyEvent::HTTPD -MURI::http
260 260
261 # run it 261 # run it
262 ./app 262 ./app
263 263
264 Here are the three phase 2 commands:
265
266 staticperl mkbundle args...
267 The "default" bundle command - it interprets the given bundle
268 options and writes out bundle.h, bundle.c, bundle.ccopts and
269 bundle.ldopts files, useful for embedding.
270
271 staticperl mkperl args...
272 Creates a bundle just like staticperl mkbundle (in fact, it's the
273 same as invoking staticperl mkbundle --perl args...), but then
274 compiles and links a new perl interpreter that embeds the created
275 bundle, then deletes all intermediate files.
276
277 staticperl mkapp filename args...
278 Does the same as staticperl mkbundle (in fact, it's the same as
279 invoking staticperl mkbundle --app filename args...), but then
280 compiles and links a new standalone application that simply
281 initialises the perl interpreter.
282
283 The difference to staticperl mkperl is that the standalone
284 application does not act like a perl interpreter would - in fact, by
285 default it would just do nothing and exit immediately, so you should
286 specify some code to be executed via the --boot option.
287
264 OPTION PROCESSING 288 OPTION PROCESSING
265 All options can be given as arguments on the command line (typically 289 All options can be given as arguments on the command line (typically
266 using long (e.g. "--verbose") or short option (e.g. "-v") style). Since 290 using long (e.g. "--verbose") or short option (e.g. "-v") style). Since
267 specifying a lot of modules can make the command line very cumbersome, 291 specifying a lot of options can make the command line very long and
268 you can put all long options into a "bundle specification file" (with or 292 unwieldy, you can put all long options into a "bundle specification
269 without "--" prefix) and specify this bundle file instead. 293 file" (one option per line, with or without "--" prefix) and specify
294 this bundle file instead.
270 295
271 For example, the command given earlier could also look like this: 296 For example, the command given earlier to link a new perl could also
297 look like this:
272 298
273 staticperl mkperl httpd.bundle 299 staticperl mkperl httpd.bundle
274 300
275 And all options could be in httpd.bundle: 301 With all options stored in the httpd.bundle file (one option per line,
302 everything after the option is an argument):
276 303
277 use "Config_heavy.pl" 304 use "Config_heavy.pl"
278 use AnyEvent::Impl::Perl 305 use AnyEvent::Impl::Perl
279 use AnyEvent::HTTPD 306 use AnyEvent::HTTPD
280 use URI::http 307 use URI::http
281 add eg/httpd httpd.pm 308 add eg/httpd httpd.pm
282 309
283 All options that specify modules or files to be added are processed in 310 All options that specify modules or files to be added are processed in
284 the order given on the command line (that affects the "--use" and 311 the order given on the command line.
285 "--eval" options at the moment).
286 312
287 PACKAGE SELECTION WORKFLOW 313 BUNDLE CREATION WORKFLOW / STATICPELR MKBUNDLE OPTIONS
288 staticperl mkbundle has a number of options to control package 314 staticperl mkbundle works by first assembling a list of candidate files
289 selection. This section describes how they interact with each other. 315 and modules to include, then filtering them by include/exclude patterns.
290 Also, since I am still a newbie w.r.t. these issues, maybe future 316 The remaining modules (together with their direct dependencies, such as
291 versions of staticperl will change this, so watch out :) 317 link libraries and AutoLoader files) are then converted into bundle
318 files suitable for embedding. staticperl mkbundle can then optionally
319 build a new perl interpreter or a standalone application.
292 320
293 The idiom "in order" means "in order that they are specified on the 321 Step 0: Generic argument processing.
294 commandline". If you use a bundle specification file, then the options 322 The following options influence staticperl mkbundle itself.
295 will be processed as if they were given in place of the bundle file
296 name.
297 323
298 1. apply all "--use", "--eval", "--add", "--addbin" and "--incglob"
299 options, in order.
300 In addition, "--use" and "--eval" dependencies will be added when
301 the options are processed.
302
303 2. apply all "--include" and "--exclude" options, in order.
304 All this step does is potentially reduce the number of files already
305 selected or found in phase 1.
306
307 3. find all modules (== .pm files), gather their static archives (.a)
308 and AutoLoader splitfiles (.ix and .al files), find any extra libraries
309 they need for linking (extralibs.ld) and optionally evaluate any
310 .packlist files.
311 This step is required to link against XS extensions and also adds
312 files required for AutoLoader to do it's job.
313
314 After this, all the files selected for bundling will be read and
315 processed (stripped), the bundle files will be written, and optionally a
316 new perl or application binary will be linked.
317
318 MKBUNDLE OPTIONS
319 --verbose | -v 324 "--verbose" | "-v"
320 Increases the verbosity level by one (the default is 1). 325 Increases the verbosity level by one (the default is 1).
321 326
322 --quiet | -q 327 "--quiet" | "-q"
323 Decreases the verbosity level by one. 328 Decreases the verbosity level by one.
324 329
325 --strip none|pod|ppi 330 any other argument
326 Specify the stripping method applied to reduce the file of the perl 331 Any other argument is interpreted as a bundle specification
327 sources included. 332 file, which supports all options (without extra quoting), one
333 option per line, in the format "option" or "option argument".
334 They will effectively be expanded and processed as if they were
335 directly written on the command line, in place of the file name.
328 336
329 The default is "pod", which uses the Pod::Strip module to remove all 337 Step 1: gather candidate files and modules
330 pod documentation, which is very fast and reduces file size a lot. 338 In this step, modules, perl libraries (.pl files) and other files
339 are selected for inclusion in the bundle. The relevant options are
340 executed in order (this makes a difference mostly for "--eval",
341 which can rely on earlier "--use" options to have been executed).
331 342
332 The "ppi" method uses PPI to parse and condense the perl sources.
333 This saves a lot more than just Pod::Strip, and is generally safer,
334 but is also a lot slower (some files take almost a minute to strip -
335 staticperl maintains a cache of stripped files to speed up
336 subsequent runs for this reason). Note that this method doesn't
337 optimise for raw file size, but for best compression (that means
338 that the uncompressed file size is a bit larger, but the files
339 compress better, e.g. with upx).
340
341 Last not least, if you need accurate line numbers in error messages,
342 or in the unlikely case where "pod" is too slow, or some module gets
343 mistreated, you can specify "none" to not mangle included perl
344 sources in any way.
345
346 --perl
347 After writing out the bundle files, try to link a new perl
348 interpreter. It will be called perl and will be left in the current
349 working directory. The bundle files will be removed.
350
351 This switch is automatically used when staticperl is invoked with
352 the "mkperl" command (instead of "mkbundle"):
353
354 # build a new ./perl with only common::sense in it - very small :)
355 staticperl mkperl -Mcommon::sense
356
357 --app name
358 After writing out the bundle files, try to link a new standalone
359 program. It will be called "name", and the bundle files get removed
360 after linking it.
361
362 The difference to the (mutually exclusive) "--perl" option is that
363 the binary created by this option will not try to act as a perl
364 interpreter - instead it will simply initialise the perl
365 interpreter, clean it up and exit.
366
367 This switch is automatically used when staticperl is invoked with
368 the "mkapp" command (instead of "mkbundle"):
369
370 To let it do something useful you *must* add some boot code, e.g.
371 with the "--boot" option.
372
373 Example: create a standalone perl binary that will execute appfile
374 when it is started.
375
376 staticperl mkbundle --app myexe --boot appfile
377
378 --use module | -Mmodule 343 "--use" module | "-M"module
379 Include the named module and all direct dependencies. This is done 344 Include the named module and trace direct dependencies. This is
380 by "require"'ing the module in a subprocess and tracing which other 345 done by "require"'ing the module in a subprocess and tracing
381 modules and files it actually loads. If the module uses AutoLoader, 346 which other modules and files it actually loads.
382 then all splitfiles will be included as well.
383 347
384 Example: include AnyEvent and AnyEvent::Impl::Perl. 348 Example: include AnyEvent and AnyEvent::Impl::Perl.
385 349
386 staticperl mkbundle --use AnyEvent --use AnyEvent::Impl::Perl 350 staticperl mkbundle --use AnyEvent --use AnyEvent::Impl::Perl
387 351
388 Sometimes you want to load old-style "perl libraries" (.pl files), 352 Sometimes you want to load old-style "perl libraries" (.pl
389 or maybe other weirdly named files. To do that, you need to quote 353 files), or maybe other weirdly named files. To do that, you need
390 the name in single or double quotes. When given on the command line, 354 to quote the name in single or double quotes (this is because
391 you probably need to quote once more to avoid your shell 355 staticperl *literally* just adds the string after the "require"
392 interpreting it. Common cases that need this are Config_heavy.pl and 356 - which acts different when confronted with quoted vs. unquoted
393 utf8_heavy.pl. 357 strings). When given on the command line, you probably need to
358 quote once more to avoid your shell interpreting it. Common
359 cases that need this are Config_heavy.pl and utf8_heavy.pl.
394 360
395 Example: include the required files for perl -V to work in all its 361 Example: include the required files for perl -V to work in all
396 glory (Config.pm is included automatically by this). 362 its glory (Config.pm is included automatically by this).
397 363
398 # bourne shell 364 # bourne shell
399 staticperl mkbundle --use '"Config_heavy.pl"' 365 staticperl mkbundle --use '"Config_heavy.pl"'
400 366
401 # bundle specification file 367 # bundle specification file
402 use "Config_heavy.pl" 368 use "Config_heavy.pl"
403 369
404 The "-Mmodule" syntax is included as an alias that might be easier 370 The "-M"module syntax is included as a convenience that might be
405 to remember than "use". Or maybe it confuses people. Time will tell. 371 easier to remember than "--use" - it's the same switch as perl
406 Or maybe not. Argh. 372 itself uses to load modules. Or maybe it confuses people. Time
373 will tell. Or maybe not. Sigh.
407 374
408 --eval "perl code" | -e "perl code" 375 "--eval" "perl code" | "-e" "perl code"
409 Sometimes it is easier (or necessary) to specify dependencies using 376 Sometimes it is easier (or necessary) to specify dependencies
410 perl code, or maybe one of the modules you use need a special use 377 using perl code, or maybe one of the modules you use need a
411 statement. In that case, you can use "eval" to execute some perl 378 special use statement. In that case, you can use "--eval" to
412 snippet or set some variables or whatever you need. All files 379 execute some perl snippet or set some variables or whatever you
413 "require"'d or "use"'d in the script are included in the final 380 need. All files "require"'d or "use"'d while executing the
414 bundle. 381 snippet are included in the final bundle.
415 382
416 Keep in mind that mkbundle will only "require" the modules named by 383 Keep in mind that mkbundle will only "require" the modules named
417 the "--use" option, so do not expect the symbols from modules you 384 by the "--use" option, so do not expect the symbols from modules
418 "--use"'d earlier on the command line to be available. 385 you "--use"'d earlier on the command line to be available.
419 386
420 Example: force AnyEvent to detect a backend and therefore include it 387 Example: force AnyEvent to detect a backend and therefore
421 in the final bundle. 388 include it in the final bundle.
422 389
423 staticperl mkbundle --eval 'use AnyEvent; AnyEvent::detect' 390 staticperl mkbundle --eval 'use AnyEvent; AnyEvent::detect'
424 391
425 # or like this 392 # or like this
426 staticperl mkbundle -MAnyEvent --eval 'use AnyEvent; AnyEvent::detect' 393 staticperl mkbundle -MAnyEvent --eval 'AnyEvent::detect'
427 394
428 Example: use a separate "bootstrap" script that "use"'s lots of 395 Example: use a separate "bootstrap" script that "use"'s lots of
429 modules and include this in the final bundle, to be executed 396 modules and also include this in the final bundle, to be
430 automatically. 397 executed automatically when the interpreter is initialised.
431 398
432 staticperl mkbundle --eval 'do "bootstrap"' --boot bootstrap 399 staticperl mkbundle --eval 'do "bootstrap"' --boot bootstrap
433 400
434 --boot filename 401 "--boot" filename
435 Include the given file in the bundle and arrange for it to be 402 Include the given file in the bundle and arrange for it to be
436 executed (using a "require") before anything else when the new perl 403 executed (using "require") before the main program when the new
437 is initialised. This can be used to modify @INC or anything else 404 perl is initialised. This can be used to modify @INC or do
438 before the perl interpreter executes scripts given on the command 405 similar modifications before the perl interpreter executes
439 line (or via "-e"). This works even in an embedded interpreter. 406 scripts given on the command line (or via "-e"). This works even
407 in an embedded interpreter - the file will be executed during
408 interpreter initialisation in that case.
440 409
410 "--incglob" pattern
411 This goes through all standard library directories and tries to
412 match any .pm and .pl files against the extended glob pattern
413 (see below). If a file matches, it is added. The pattern is
414 matched against the full path of the file (sans the library
415 directory prefix), e.g. Sys/Syslog.pm.
416
417 This is very useful to include "everything":
418
419 --incglob '*'
420
421 It is also useful for including perl libraries, or trees of
422 those, such as the unicode database files needed by some perl
423 built-ins, the regex engine and other modules.
424
425 --incglob '/unicore/**.pl'
426
427 "--add" file | "--add" "file alias"
428 Adds the given (perl) file into the bundle (and optionally call
429 it "alias"). The file is either an absolute path or a path
430 relative to the current directory. If an alias is specified,
431 then this is the name it will use for @INC searches, otherwise
432 the file will be used as the internal name.
433
434 This switch is used to include extra files into the bundle.
435
436 Example: embed the file httpd in the current directory as
437 httpd.pm when creating the bundle.
438
439 staticperl mkperl --add "httpd httpd.pm"
440
441 Example: add local files as extra modules in the bundle.
442
443 # specification file
444 add file1 myfiles/file1.pm
445 add file2 myfiles/file2.pm
446 add file3 myfiles/file3.pl
447
448 # then later, in perl, use
449 use myfiles::file1;
450 require myfiles::file2;
451 my $res = do "myfiles/file3.pl";
452
453 "--binadd" file | "--add" "file alias"
454 Just like "--add", except that it treats the file as binary and
455 adds it without any postprocessing (perl files might get
456 stripped to reduce their size).
457
458 You should probably add a "/" prefix to avoid clashing with
459 embedded perl files (whose paths do not start with "/"), and/or
460 use a special directory prefix, such as "/res/name".
461
462 You can later get a copy of these files by calling
463 "staticperl::find "alias"".
464
465 An alternative way to embed binary files is to convert them to
466 perl and use "do" to get the contents - this method is a bit
467 cumbersome, but works both inside and outside of a staticperl
468 bundle:
469
470 # a "binary" file, call it "bindata.pl"
471 <<'SOME_MARKER'
472 binary data NOT containing SOME_MARKER
473 SOME_MARKER
474
475 # load the binary
476 chomp (my $data = do "bindata.pl");
477
478 Step 2: filter all files using "--include" and "--exclude" options.
479 After all candidate files and modules are added, they are *filtered*
480 by a combination of "--include" and "--exclude" patterns (there is
481 an implicit "--include *" at the end, so if no filters are
482 specified, all files are included).
483
484 All that this step does is potentially reduce the number of files
485 that are to be included - no new files are added during this step.
486
487 "--include" pattern | "-i" pattern | "--exclude" pattern | "-x"
488 pattern
489 These specify an include or exclude pattern to be applied to the
490 candidate file list. An include makes sure that the given files
491 will be part of the resulting file set, an exclude will exclude
492 remaining files. The patterns are "extended glob patterns" (see
493 below).
494
495 The patterns are applied "in order" - files included via earlier
496 "--include" specifications cannot be removed by any following
497 "--exclude", and likewise, and file excluded by an earlier
498 "--exclude" cannot be added by any following "--include".
499
500 For example, to include everything except "Devel" modules, but
501 still include Devel::PPPort, you could use this:
502
503 --incglob '*' -i '/Devel/PPPort.pm' -x '/Devel/**'
504
505 Step 3: add any extra or "hidden" dependencies.
506 staticperl currently knows about three extra types of depdendencies
507 that are added automatically. Only one (.packlist files) is
508 currently optional and can be influenced, the others are always
509 included:
510
441 --usepacklist 511 "--usepacklists"
442 Read .packlist files for each distribution that happens to match a 512 Read .packlist files for each distribution that happens to match
443 module name you specified. Sounds weird, and it is, so expect 513 a module name you specified. Sounds weird, and it is, so expect
444 semantics to change somehow in the future. 514 semantics to change somehow in the future.
445 515
446 The idea is that most CPAN distributions have a .pm file that 516 The idea is that most CPAN distributions have a .pm file that
447 matches the name of the distribution (which is rather reasonable 517 matches the name of the distribution (which is rather reasonable
448 after all). 518 after all).
449 519
450 If this switch is enabled, then if any of the .pm files that have 520 If this switch is enabled, then if any of the .pm files that
451 been selected match an install distribution, then all .pm, .pl, .al 521 have been selected match an install distribution, then all .pm,
452 and .ix files installed by this distribution are also included. 522 .pl, .al and .ix files installed by this distribution are also
523 included.
453 524
454 For example, using this switch, when the URI module is specified, 525 For example, using this switch, when the URI module is
455 then all URI submodules that have been installed via the CPAN 526 specified, then all URI submodules that have been installed via
456 distribution are included as well, so you don't have to manually 527 the CPAN distribution are included as well, so you don't have to
457 specify them. 528 manually specify them.
458 529
459 --incglob pattern 530 AutoLoader splitfiles
460 This goes through all library directories and tries to match any .pm 531 Some modules use AutoLoader - less commonly (hopefully) used
461 and .pl files against the extended glob pattern (see below). If a 532 functions are split into separate .al files, and an index (.ix)
462 file matches, it is added. This switch will automatically detect 533 file contains the prototypes.
463 AutoLoader files and the required link libraries for XS modules, but
464 it will *not* scan the file for dependencies (at the moment).
465 534
466 This is mainly useful to include "everything": 535 Both .ix and .al files will be detected automatically and added
536 to the bundle.
467 537
468 --incglob '*' 538 link libraries (.a files)
539 Modules using XS (or any other non-perl language extension
540 compiled at installation time) will have a static archive
541 (typically .a). These will automatically be added to the linker
542 options in bundle.ldopts.
469 543
470 Or to include perl libraries, or trees of those, such as the unicode 544 Should staticperl find a dynamic link library (typically .so) it
471 database files needed by many other modules: 545 will warn about it - obviously this shouldn't happen unless you
546 use staticperl on the wrong perl, or one (probably wrongly)
547 configured to use dynamic loading.
472 548
473 --incglob '/unicore/**.pl' 549 extra libraries (extralibs.ld)
550 Some modules need linking against external libraries - these are
551 found in extralibs.ld and added to bundle.ldopts.
474 552
475 --add file | --add "file alias" 553 Step 4: write bundle files and optionally link a program
476 Adds the given (perl) file into the bundle (and optionally call it 554 At this point, the select files will be read, processed (stripped)
477 "alias"). This is useful to include any custom files into the 555 and finally the bundle files get written to disk, and staticperl
478 bundle. 556 mkbundle is normally finished. Optionally, it can go a step further
557 and either link a new perl binary with all selected modules and
558 files inside, or build a standalone application.
479 559
480 Example: embed the file httpd as httpd.pm when creating the bundle. 560 Both the contents of the bundle files and any extra linking is
561 controlled by these options:
481 562
482 staticperl mkperl --add "httpd httpd.pm" 563 "--strip" "none"|"pod"|"ppi"
564 Specify the stripping method applied to reduce the file of the
565 perl sources included.
483 566
484 It is also a great way to add any custom modules: 567 The default is "pod", which uses the Pod::Strip module to remove
568 all pod documentation, which is very fast and reduces file size
569 a lot.
485 570
486 # specification file 571 The "ppi" method uses PPI to parse and condense the perl
487 add file1 myfiles/file1 572 sources. This saves a lot more than just Pod::Strip, and is
488 add file2 myfiles/file2 573 generally safer, but is also a lot slower (some files take
489 add file3 myfiles/file3 574 almost a minute to strip - staticperl maintains a cache of
575 stripped files to speed up subsequent runs for this reason).
576 Note that this method doesn't optimise for raw file size, but
577 for best compression (that means that the uncompressed file size
578 is a bit larger, but the files compress better, e.g. with upx).
490 579
491 --binadd file | --add "file alias" 580 Last not least, if you need accurate line numbers in error
492 Just like "--add", except that it treats the file as binary and adds 581 messages, or in the unlikely case where "pod" is too slow, or
493 it without any processing. 582 some module gets mistreated, you can specify "none" to not
583 mangle included perl sources in any way.
494 584
495 You should probably add a "/" prefix to avoid clashing with embedded 585 "--perl"
496 perl files (whose paths do not start with "/"), and/or use a special 586 After writing out the bundle files, try to link a new perl
497 directory, such as "/res/name". 587 interpreter. It will be called perl and will be left in the
588 current working directory. The bundle files will be removed.
498 589
499 You can later get a copy of these files by calling "staticperl::find 590 This switch is automatically used when staticperl is invoked
500 "alias"". 591 with the "mkperl" command instead of "mkbundle".
501 592
502 --include pattern | -i pattern | --exclude pattern | -x pattern 593 Example: build a new ./perl binary with only common::sense
503 These two options define an include/exclude filter that is used 594 inside - it will be even smaller than the standard perl
504 after all files selected by the other options have been found. Each 595 interpreter as none of the modules of the base distribution
505 include/exclude is applied to all files found so far - an include 596 (such as Fcntl) will be included.
506 makes sure that the given files will be part of the resulting file
507 set, an exclude will exclude files. The patterns are "extended glob
508 patterns" (see below).
509 597
510 For example, to include everything, except "Devel" modules, but 598 staticperl mkperl -Mcommon::sense
511 still include Devel::PPPort, you could use this:
512 599
513 --incglob '*' -i '/Devel/PPPort.pm' -x '/Devel/**' 600 "--app" name
601 After writing out the bundle files, try to link a new standalone
602 program. It will be called "name", and the bundle files get
603 removed after linking it.
514 604
605 This switch is automatically used when staticperl is invoked
606 with the "mkapp" command instead of "mkbundle".
607
608 The difference to the (mutually exclusive) "--perl" option is
609 that the binary created by this option will not try to act as a
610 perl interpreter - instead it will simply initialise the perl
611 interpreter, clean it up and exit.
612
613 This means that, by default, it will do nothing but burna few
614 CPU cycles - for it to do something useful you *must* add some
615 boot code, e.g. with the "--boot" option.
616
617 Example: create a standalone perl binary called ./myexe that
618 will execute appfile when it is started.
619
620 staticperl mkbundle --app myexe --boot appfile
621
515 --static 622 "--static"
516 When "--perl" is also given, link statically instead of dynamically. 623 Add "-static" to bundle.ldopts, which means a fully static (if
624 supported by the OS) executable will be created. This is not
625 immensely useful when just creating the bundle files, but is
626 most useful when linking a binary with the "--perl" or "--app"
627 options.
628
517 The default is to link the new perl interpreter fully dynamic (that 629 The default is to link the new binary dynamically (that means
518 means all perl modules are linked statically, but all external 630 all perl modules are linked statically, but all external
519 libraries are still referenced dynamically). 631 libraries are still referenced dynamically).
520 632
521 Keep in mind that Solaris doesn't support static linking at all, and 633 Keep in mind that Solaris doesn't support static linking at all,
522 systems based on GNU libc don't really support it in a usable 634 and systems based on GNU libc don't really support it in a very
523 fashion either. Try uClibc if you want to create fully statically 635 usable fashion either. Try uClibc if you want to create fully
524 linked executables, or try the "--staticlibs" option to link only 636 statically linked executables, or try the "--staticlib" option
525 some libraries statically. 637 to link only some libraries statically.
526 638
527 --staticlib libname 639 "--staticlib" libname
528 When not linking fully statically, this option allows you to link 640 When not linking fully statically, this option allows you to
529 specific libraries statically. What it does is simply replace all 641 link specific libraries statically. What it does is simply
530 occurances of "-llibname" with the GCC-specific "-Wl,-Bstatic 642 replace all occurrences of "-llibname" with the GCC-specific
531 -llibname -Wl,-Bdynamic" option. 643 "-Wl,-Bstatic -llibname -Wl,-Bdynamic" option.
532 644
533 This will have no effect unless the library is actually linked 645 This will have no effect unless the library is actually linked
534 against, specifically, "--staticlib" will not link against the named 646 against, specifically, "--staticlib" will not link against the
535 library unless it would be linked against anyway. 647 named library unless it would be linked against anyway.
536 648
537 Example: link libcrypt statically into the binary. 649 Example: link libcrypt statically into the final binary.
538 650
539 staticperl mkperl -MIO::AIO --staticlib crypt 651 staticperl mkperl -MIO::AIO --staticlib crypt
540 652
541 # ldopts might nwo contain: 653 # ldopts might now contain:
542 # -lm -Wl,-Bstatic -lcrypt -Wl,-Bdynamic -lpthread 654 # -lm -Wl,-Bstatic -lcrypt -Wl,-Bdynamic -lpthread
543
544 any other argument
545 Any other argument is interpreted as a bundle specification file,
546 which supports most long options (without extra quoting), one option
547 per line.
548 655
549 EXTENDED GLOB PATTERNS 656 EXTENDED GLOB PATTERNS
550 Some options of staticperl mkbundle expect an *extended glob pattern*. 657 Some options of staticperl mkbundle expect an *extended glob pattern*.
551 This is neither a normal shell glob nor a regex, but something in 658 This is neither a normal shell glob nor a regex, but something in
552 between. The idea has been copied from rsync, and there are the current 659 between. The idea has been copied from rsync, and there are the current
… …
560 667
561 Patterns not starting with / will be anchored at the end of the path. 668 Patterns not starting with / will be anchored at the end of the path.
562 That is, idna.pl will match any file called idna.pl anywhere in the 669 That is, idna.pl will match any file called idna.pl anywhere in the
563 hierarchy, but not any directories of the same name. 670 hierarchy, but not any directories of the same name.
564 671
565 A * matches any single component. 672 A * matches anything within a single path component.
566 That is, /unicore/*.pl would match all .pl files directly inside 673 That is, /unicore/*.pl would match all .pl files directly inside
567 "/unicore", not any deeper level .pl files. Or in other words, * 674 "/unicore", not any deeper level .pl files. Or in other words, *
568 will not match slashes. 675 will not match slashes.
569 676
570 A ** matches anything. 677 A ** matches anything.
… …
800 Returns "undef" if the file isn't embedded. 907 Returns "undef" if the file isn't embedded.
801 908
802 @paths = staticperl::list 909 @paths = staticperl::list
803 Returns the list of all paths embedded in this binary. 910 Returns the list of all paths embedded in this binary.
804 911
805FULLY STATIC BINARIES - BUILDROOT 912FULLY STATIC BINARIES - UCLIBC AND BUILDROOT
806 To make truly static (Linux-) libraries, you might want to have a look 913 To make truly static (Linux-) libraries, you might want to have a look
807 at buildroot (<http://buildroot.uclibc.org/>). 914 at buildroot (<http://buildroot.uclibc.org/>).
808 915
809 Buildroot is primarily meant to set up a cross-compile environment 916 Buildroot is primarily meant to set up a cross-compile environment
810 (which is not so useful as perl doesn't quite like cross compiles), but 917 (which is not so useful as perl doesn't quite like cross compiles), but
… …
891 998
892 If you want to handle IRIs or IDNs (AnyEvent::Util punycode and idn 999 If you want to handle IRIs or IDNs (AnyEvent::Util punycode and idn
893 functions), you also need to include "AnyEvent/Util/idna.pl" and 1000 functions), you also need to include "AnyEvent/Util/idna.pl" and
894 "AnyEvent/Util/uts46data.pl". 1001 "AnyEvent/Util/uts46data.pl".
895 1002
896 Or you can use "--usepacklist" and specify "-MAnyEvent" to include 1003 Or you can use "--usepacklists" and specify "-MAnyEvent" to include
897 everything. 1004 everything.
898 1005
899 Carp 1006 Carp
900 Carp had (in older versions of perl) a dependency on Carp::Heavy. As 1007 Carp had (in older versions of perl) a dependency on Carp::Heavy. As
901 of perl 5.12.2 (maybe earlier), this dependency no longer exists. 1008 of perl 5.12.2 (maybe earlier), this dependency no longer exists.
… …
904 The perl -V switch (as well as many modules) needs Config, which in 1011 The perl -V switch (as well as many modules) needs Config, which in
905 turn might need "Config_heavy.pl". Including the latter gives you 1012 turn might need "Config_heavy.pl". Including the latter gives you
906 both. 1013 both.
907 1014
908 Term::ReadLine::Perl 1015 Term::ReadLine::Perl
909 Also needs Term::ReadLine::readline, or "--usepacklist". 1016 Also needs Term::ReadLine::readline, or "--usepacklists".
910 1017
911 URI URI implements schemes as separate modules - the generic URL scheme 1018 URI URI implements schemes as separate modules - the generic URL scheme
912 is implemented in URI::_generic, HTTP is implemented in URI::http. 1019 is implemented in URI::_generic, HTTP is implemented in URI::http.
913 If you need to use any of these schemes, you should include these 1020 If you need to use any of these schemes, you should include these
914 manually, or use "--usepacklist". 1021 manually, or use "--usepacklists".
915 1022
916 RECIPES 1023 RECIPES
917 Linking everything in 1024 Just link everything in
918 To link just about everything installed in the perl library into a 1025 To link just about everything installed in the perl library into a
919 new perl, try this: 1026 new perl, try this (the first time this runs it will take a long
1027 time, as a lot of files need to be parsed):
920 1028
921 staticperl mkperl --strip ppi --incglob '*' 1029 staticperl mkperl -v --strip ppi --incglob '*'
922 1030
1031 If you don't mind the extra megabytes, this can be a very effective
1032 way of creating bundles without having to worry about forgetting any
1033 modules.
1034
1035 You get even more useful variants of this method by first selecting
1036 everything, and then excluding stuff you are reasonable sure not to
1037 need - bigperl <http://staticperl.schmorp.de/bigperl.html> uses this
1038 approach.
1039
923 Getting rid of netdb function 1040 Getting rid of netdb functions
924 The perl core has lots of netdb functions ("getnetbyname", 1041 The perl core has lots of netdb functions ("getnetbyname",
925 "getgrent" and so on) that few applications use. You can avoid 1042 "getgrent" and so on) that few applications use. You can avoid
926 compiling them in by putting the following fragment into a 1043 compiling them in by putting the following fragment into a
927 "preconfigure" hook: 1044 "preconfigure" hook:
928 1045

Diff Legend

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