NAME

perl-libextractor - determine perl library subsets for building distributions

SYNOPSIS

   perl-libextractor ...

General Options:

   -v                verbose
   --version         display version
   -I path           prepend path to @INC
   --no-packlists    do not use packlists

Selection:

   -Mmodule          load and trace module
   --script progname add executable script
   --eval | -e str   trace execution of perl string
   --perl            add perl interpreter itself
   --core-support    add core support
   --unicore         add unicore database
   --core            add perl core library
   --glob glob       add library files select by glob
   --filter pat,...  apply include/exclude patterns
   --runtime-only    remove files not needed for execution

Modes:

   --list            list source and destination paths

   --dstlist         list destination paths

   --srclist         list source paths

   --copy path       copy files to a target path
      --bindir path     perl executable target ("exe")
      --dlldir path     shared library target ("dll")
      --scriptdir path  executable script target ("bin")
      --libdir path     perl library target ("lib")
      --strip           strip .pl and .pm files
      --cache-dir path  cache directory to use
      --binstrip "..."  strip binaries and dlls

DESCRIPTION

This program can be used to extract a subset of your perl installation, with the intention of building software distributions. Or in other words, this module finds all files necessary to run a perl program (library files, perl executable, scripts).

The resulting set can then be displayed or copied to another directory, while optionally stripping the perl sources to make them smaller.

OPTIONS

This manpage gives only rudimentary documentation for options that have an equivalent in Perl::LibExtractor, so look there for details.

Options are not processed in order specified on the commandline, but in multiple phases (e.g., -I gets executed before any -M option).

GENERAL OPTIONS

These options configure basic settings.

--verbose

-v

Increases verbosity - highly recommended for interactive use.

--version

Display the version of Perl::LibExtractor.

-I path

Prepends the given path to @INC when searching perl library directories (the last -I option is prepended first).

--no-packlists

Packlists allow to package all of a distribution, including resource files not found through the normal tracing mechanism. This option disaables use of packlists (normally highly recommended).

Some especially broken perls (Debian GNU/Linux...) have missing files, so this option doesn't work with them, at least not for any packages distributed by debian (packages installed through CPAN or any other non-dpkg-mechanism work fine).

SELECTION

These options specify and modify module selections. They are executed in the order stated on the commandline, and when in doubt, you should use them in the order documented here.

-Mmodule

Load the named module and trace direct dependencies (e.g. -MCarp). Same as add_mod in Perl::LibExtractor.

--script progname

Compile the (installed) script progname and trace dependencies (e.g. corelist). Same as add_bin in Perl::LibExtractor.

--eval string

-e str string

Compile and execute the givne perl code, and trace dependencies (e.g. -e "use AnyEvent; AnyEvent::detect"). Same as add_eval in Perl::LibExtractor.

--perl

Adds the perl interpreter itself, including libperl if required to run perl. Same as add_perl in Perl::LibExtractor.

--core-support

Add all support files needed to support built-in features of perl (such as ucfirst), which is usually the minimum you should add from the core library. Same as add_core_support in Perl::LibExtractor.

--unicore

Add the whole unicore database, which is big, contains many, many files and is usually not needed to run a program. Same as add_unicore in Perl::LibExtractor.

--core

Add the complete perl core library, which includes everything added by --core-support and --unicore. Same as add_core in Perl::LibExtractor.

Some especially broken perls (Debian GNU/Linux...) have missing files, so this option doesn't work with them.

--glob glob

Add all files from the perl library directories thta match the given extended glob pattern. Same as add_glob in Perl::LibExtractor, also see there for the syntax of glob patterns.

Example: add AnyEvent.pm and all AnyEvent::xxx modules installed.

   --glob Coro --glob "Coro::*"

--filter pat,...

Apply a comma-separated series of extended glob patterns, prefixed by + (include) or - (for exclude patterns). Same as filter in Perl::LibExtractor, also see there for exact semantics and syntax.

Example: remove all *.al files in auto/POSIX, except memset.al.

   --filter "+/lib/auto/POSIX/memset.al,-/lib/auto/POSIX/*.al"

--runtime-only

Remove all files not needed to run any scripts, such as debug info files, link libraries, pod files and so on. Same as runtime_only in Perl::LibExtractor.

MODES

These options select a specific work mode. Work modes might have specific options to control them further.

--list

Lists all selected files in two columns, first column is destination path, second column is source path and first line is a header line.

--dstlist

Same as --list, but only list destination paths and has no header - intended for scripts.

--srclist

Same as --list, but only list source paths and has no header - intended for scripts.

--copy path

Copy all selected files to the respective position under the directory path - previous contents of the directory will be list.

This mode has the following suboptions:

--exedir path

Specifies the subdirectory for binary executables (the perl interpreter itself), instead of the default exe/.

--dlldir path

Specifies the subdirectory for shared libraries, instead of the default dll/.

--bindir path

Specifies the subdirectry for perl scripts, instead of the default bin/.

--libdir path

Specifies the subdirectory for perl library files, instead of the default lib/.

--strip

Strip all .pm, .pl, .al files and perl executables, which mostly means removal of unecessary whitespace and documentation - see Perl::Strip which is used.

--cache-dir path

Specify the cache dir to use - the default is ~/.cache/perlstrip for cached stripped perl files (compatible to the perlstrip program).

--binstrip "..."

Use the specified program and arguments to strip executables, shared libraries and shared objects.

This is only necessary when your programs were compiled with debugging info, but can be used to specify extra treatment for all binary files.

EXAMPLE

This is how the Deliantra client (http://www.deliantra.,net) is being packages:

   perl-libextractor \
      --perl --core-support --script deliantra \
      --runtime-only \
      --copy distdir --strip --exedir . --dlldir . --bindir pm/bin --libdir pm \

The first line of arguments adds perl, support for core functions (the Deliantra client does need the full unicode database or perl core) and tells perl-libextractor to parse the installed deliantra script and trace all it's dependencies. The script is installed by installed the Deliantra::Client module from CPAN.

This finds all required perl dependencies.

The second line of arguments (--runtime-only) then removes all files not required for execution, slimming down the distribution.

The last line tells perl-libextractor to copy the resulting files to the directory distdir. The argument --strip tells it to stirp all perl sources (make them smaller by removing whitespace, comments and documentation, which saves about a megabyte).

The remaining arguments override the default subdirectories for the files, as Urlader, which is used for the binary distribution, works best if dll's and executables are in the top dir.

After this, the script that builds the distribution does a lot more, for example finding shared libraries (such as pango, SDL and so on), renaming them on OS X to avoid the severe DLL Hell on that platform, and provides a wrapper script that initialises perl so it loads its files from the distribution dir and doesn't try to search anything anywhere else.

On GNU/Linux, the binaries and libraries are also patched to remove any rpath that Debian might have compiled in and that would keep perl from ignoring LD_LIBRARY_PATH.

The wrapper script is called run, and looks a bit like this:

   @INC = ("pm", "."); # "." required by newer AutoLoader grrrr.
   $ENV{PANGO_RC_FILE} = "pango.rc";
   require "bin/deliantra";
   exit 0;

The most important line is the first one, which tells perl where to look for library files.

SEE ALSO

App::Staticperl, Urlader, Perl::Strip.

AUTHOR

 Marc Lehmann <schmorp@schmorp.de>
 http://software.schmorp.de/pkg/staticperl.html

cpanm Perl::LibExtractor

perl -MCPAN -e shell
install Perl::LibExtractor