[ViewVC] Contents of: cvs/Perl-LibExtractor/README

NAME
    Perl::LibExtractor - determine perl library subsets for building
    distributions

SYNOPSIS
       use Perl::LibExtractor;

DESCRIPTION
    The purpose of this module is to determine subsets of your perl library,
    that is, a set of files needed to satisfy certain dependencies (e.g. of
    a program).

    The goal is to extract a part of your perl installation including
    dependencies. A typical use case for this module would be to find out
    which files are needed to be build a PAR distribution, to link into an
    App::Staticperl binary, or to pack with Urlader, to create stand-alone
    distributions tailormade to run your app.

METHODS
    To use this module, first call the "new"-constructor and then as many
    other methods as you want, to generate a set of files. Then query the
    set of files and do whatever you want with them.

    The command-line utility perl-libextract can be a convenient alternative
    to using this module directly, and offers a few extra options, such as
    to copy out the files into a new directory, strip them and/or manipulate
    them in other ways.

  CREATION
    $extractor = new Perl::LibExtractor [key => value...]
        Creates a new extractor object. Each extractor object stores some
        configuration options and a subset of files that can be queried at
        any time,.

        Binary executables (such as the perl interpreter) are stored inside
        bin/, perl scripts are stored under script/, perl library files are
        stored under lib/ and shared libraries are stored under dll/.

        The following key-value pairs exist, with default values as
        specified.

        inc => \@INC without "."
            An arrayref with paths to perl library directories. The default
            is "\@INC", with . removed.

            To prepend custom dirs just do this:

               inc => ["mydir", @INC],

        use_packlist => 1
            Enable (if true) or disable the use of ".packlist" files. If
            enabled, then each time a file is traced, the complete
            distribution that contains it is included (but not traced).

            If disabled, only shared objects and autoload files will be
            added.

            Debian GNU/Linux doesn't completely package perl or any perl
            modules, so this option will fail. Other perls should be fine.

        extra_deps => { file => [files...] }
            Some (mainly runtime dependencies in the perl core library)
            cannot be detected automatically by this module, especially if
            you don't use packlists and "add_core".

            This module comes with a set of default dependencies (such as
            Carp requiring Carp::Heavy), which you cna override with this
            parameter.

            To see the default set of dependencies that come with this
            module, use this:

               perl -MPerl::LibExtractor -MData::Dumper -e 'print Dumper $Perl::LibExtractor::EXTRA_DEPS'

  TRACE/PACKLIST BASED ADDING
    The following methods add various things to the set of files.

    Each time a perl file is added, it is scanned by tracing either loading,
    execution or compiling it, and seeing which other perl modules and
    libraries have been loaded.

    For each library file found this way, additional dependencies are added:
    if packlists are enabled, then all files of the distribution that
    contains the file will be added. If packlists are disabled, then only
    shared objects and autoload files for modules will be added.

    Only files from perl library directories will be added automatically.
    Any other files (such as manpages or scripts installed in the bin
    directory) are skipped.

    If there is an error, such as a module not being found, then this module
    croaks (as opposed to silently skipping). If you want to add something
    of which you are not sure it exists, then you can wrap the call into
    "eval {}". In some cases, you can avoid this by executing the code you
    want to work later using "add_eval" - see "add_core_support" for an
    actual example of this technique.

    Note that packlists are meant to add files not covered by other
    mechanisms, such as resource files and other data files loaded directly
    by a module - they are not meant to add dependencies that are missed
    because they only happen at runtime.

    For example, with packlists, when using AnyEvent, then all event loop
    backends are automatically added as well, but *not* any event loops
    (i.e. AnyEvent::Impl::POE is added, but POE itself is not). Without
    packlists, only the backend that is being used is added (i.e. normally
    none, as loading AnyEvent does not instantly load any backend).

    To catch the extra event loop dependencies, you can either initialise
    AnyEvent so it picks a suitable backend:

       $extractor->add_eval ("use AnyEvent; AnyEvent::detect");

    Or you can directly load the backend modules you plan to use:

       $extractor->add_mod ("AnyEvent::Impl::EV", "AnyEvent::Impl::Perl");

    An example of a program (or module) that has extra resource files is
    Deliantra::Client - the normal tracing (without packlist usage) will
    correctly add all submodules, but miss the fonts and textures. By using
    the packlist, those files are added correctly.

    $extractor->add_mod ($module[, $module...])
        Adds the given module(s) to the file set - the module name must be
        specified as in "use", i.e. with "::" as separators and without .pm.

        The program will be loaded with the default import list, any
        dependent files, such as the shared object implementing xs
        functions, or autoload files, will also be added.

        If you want to use a different import list (for those rare modules
        wghere import lists trigger different backend modules to be loaded
        for example), you can use "add_eval" instead:

          $extractor->add_eval ("use Module qw(a b c)");

        Example: add Coro.pm and AnyEvent/AIO.pm, and all relevant files
        from the distribution they are part of.

          $extractor->add_mod ("Coro", "AnyEvent::AIO");

    $extractor->add_require ($name[, $name...])
        Works like "add_mod", but uses "require $name" to load the module,
        i.e. the name must be a filename.

        Example: load Coro and AnyEvent::AIO, but using "add_require"
        instead of "add_mod".

           $extractor->add_require ("Coro.pm", "AnyEvent/AIO.pm");

    $extractor->add_bin ($name[, $name...])
        Adds the given (perl) program(s) to the file set, that is, a program
        installed by some perl module, written in perl (an example would be
        the perl-libextract program that is part of the "Perl::LibExtractor"
        distribution).

        Example: add the deliantra client program installed by the
        Deliantra::Client module and put it under bin/deliantra.

           $extractor->add_bin ("deliantra");

    $extractor->add_eval ($string)
        Evaluates the string as perl code and adds all modules that are
        loaded by it. For example, this would add AnyEvent and the default
        backend implementation module and event loop module:

           $extractor->add_eval ("use AnyEvent; AnyEvent::detect");

        Each code snippet will be executed in its own package and under "use
        strict".

  OTHER METHODS FOR ADDING FILES
    The following methods add commonly used files that are either not
    covered by other methods or add commonly-used dependencies.

    $extractor->add_perl
        Adds the perl binary itself to the file set, including the libperl
        dll, if needed.

        For example, on UNIX systems, this usually adds a exe/perl and
        possibly some dll/libperl.so.XXX.

    $extractor->add_core_support
        Try to add modules and files needed to support commonly-used builtin
        language features. For example to open a scalar for I/O you need the
        PerlIO::scalar module:

           open $fh, "<", \$scalar

        A number of regex and string features (e.g. "ucfirst") need some
        unicore files, e.g.:

           'my $x = chr 1234; "\u$x\U$x\l$x\L$x"; $x =~ /\d|\w|\s|\b|$x/i';

        This call adds these files (simply by executing code similar to the
        above code fragments).

        Notable things that are missing are other PerlIO layers, such as
        PerlIO::encoding, and named character and character class matches.

    $extractor->add_unicore
        Adds (hopefully) all files from the unicore database that will ever
        be needed.

        If you are not sure which unicode character classes and similar
        unicore databases you need, and you do not care about an extra one
        thousand(!) files comprising 4MB of data, then you can just call
        this method, which adds basically all files from perl's unicode
        database.

        Note that "add_core_support" also adds some unicore files, but it's
        not a subset of "add_unicore" - the former adds all files neccessary
        to support core builtins (which includes some unicore files and
        other things), while the latter adds all unicore files (but nothing
        else).

        When in doubt, use both.

    $extractor->add_core
        This adds all files from the perl core distribution, that is, all
        library files that come with perl.

        This is a superset of "add_core_support" and "add_unicore".

        This is quite a lot, but on the plus side, you can be sure nothing
        is missing.

        This requires a full perl installation - Debian GNU/Linux doesn't
        package the full perl library, so this function will not work there.

  GLOB-BASED ADDING AND FILTERING
    These methods add or manipulate files by using glob-based patterns.

    These glob patterns work similarly to glob patterns in the shell:

    /   A / at the start of the pattern interprets the pattern as a file
        path inside the file set, almost the same as in the shell. For
        example, /bin/perl* would match all files whose names starting with
        perl inside the bin directory in the set.

        If the / is missing, then the pattern is interpreted as a module
        name (a .pm file). For example, Coro matches the file lib/Coro.pm ,
        while Coro::* would match lib/Coro/*.pm.

    *   A single star matches anything inside a single directory component.
        For example, /lib/Coro/*.pm would match all .pm files inside the
        lib/Coro/ directory, but not any files deeper in the hierarchy.

        Another way to look at it is that a single star matches anything but
        a slash (/).

    **  A double star matches any number of characters in the path,
        including /.

        For example, AnyEvent::** would match all modules whose names start
        with "AnyEvent::", no matter how deep in the hierarchy they are.

    $extractor->add_glob ($modglob[, $modglob...])
        Adds all files from the perl library that match the given glob
        pattern.

        For example, you could implement "add_unicore" yourself like this:

           $extractor->add_glob ("/unicore/**.pl");

    $extractor->filter ($pattern[, $pattern...])
        Applies a series of include/exclude filters. Each filter must start
        with either "+" or "-", to designate the pattern as *include* or
        *exclude* pattern. The rest of the pattern is a normal glob pattern.

        An exclude pattern ("-") instantly removes all matching files from
        the set. An include pattern ("+") protects matching files from later
        removals.

        That is, if you have an include pattern then all files that were
        matched by it will be included in the set, regardless of any further
        exclude patterns matching the same files.

        Likewise, any file excluded by a pattern will not be included in the
        set, even if matched by later include patterns.

        Any files not matched by any expression will simply stay in the set.

        For example, to remove most of the useless autoload functions by the
        POSIX module (they either do the same thing as a builtin or always
        raise an error), you would use this:

           $extractor->filter ("-/lib/auto/POSIX/*.al");

        This does not remove all autoload files, only the ones not defined
        by a subclass (e.g. it leaves "POSIX::SigRt::xxx" alone).

    $extractor->runtime_only
        This removes all files that are not needed at runtime, such as
        static archives, header and other files needed only for compilation
        of modules, and pod and html files (which are unlikely to be needed
        at runtime).

        This is quite useful when you want to have only files actually
        needed to execute a program.

  RESULT SET
    $set = $extractor->set
        Returns a hash reference that represents the result set. The hash is
        the actual internal storage hash and can only be modified as
        described below.

        Each key in the hash is the path inside the set, without a leading
        slash, e.g.:

           bin/perl
           lib/unicore/lib/Blk/Superscr.pl
           lib/AnyEvent/Impl/EV.pm

        The value is an array reference with mostly unspecified contents,
        except the first element, which is the file system path where the
        actual file can be found.

        This code snippet lists all files inside the set:

           print "$_\n"
              for sort keys %{ $extractor->set });

        This code fragment prints "filesystem_path => set_path" pairs for
        all files in the set:

           my $set = $extractor->set;
           while (my ($set,$fspath) = each %$set) {
              print "$fspath => $set\n";
           }

        You can implement your own filtering by asking for the result set
        with "$extractor->set", and then deleting keys from the referenced
        hash - since you can ask for the result set at any time you can add
        things, filter them out this way, and add additional things.

EXAMPLE
    To package he deliantra client (Deliantra::Client), finding all (perl)
    files needed to run it is a first step. This can be done by using
    something like the following code snippet:

       my $ex = new Perl::LibExtractor;

       $ex->add_perl;
       $ex->add_core_support;
       $ex->add_bin ("deliantra");
       $ex->add_mod ("AnyEvent::Impl::EV");
       $ex->add_mod ("AnyEvent::Impl::Perl");
       $ex->add_mod ("Urlader");
       $ex->filter ("-/*/auto/POSIX/**.al");
       $ex->runtime_only;

    First it sets the perl library directory to pm and . (the latter to work
    around some AutoLoader bugs), so perl uses only the perl library files
    that came with the binary package.

    Then it sets some environment variable to override the system default
    (which might be incompatible).

    Then it runs the client itself, using "require". Since "require" only
    looks in the perl library directory this is the reaosn why the scripts
    were put there (of course, since . is also included it doesn't matter,
    but I refuse to yield to bugs).

    Finally it exits with a clean status to signal "ok" to Urlader.

    Back to the original "Perl::LibExtractor" script: after initialising a
    new set, the script simply adds the perl interpreter and core support
    files (just in case, not all are needed, but some are, and I am too lazy
    to find out which ones exactly).

    Then it adds the deliantra executable itself, which in turn adds most of
    the required modules. After that, the AnyEvent implementation modules
    are added because these dependencies are not picked up automatically.

    The Urlader module is added because the client itself does not depend on
    it at all, but the wrapper does.

    At this point, all required files are present, and it's time to slim
    down: most of the ueseless POSIX autoloaded functions are removed, not
    because they are so big, but because creating files is a costly
    operation in itself, so even small fiels have considerable overhead when
    unpacking. Then files not required for running the client are removed.

    And that concludes it, the set is now ready.

SEE ALSO
    The utility program that comes with this module: perl-libextract.

    App::Staticperl, Urlader, Perl::Squish.

LICENSE
    This software package is licensed under the GPL version 3 or any later
    version, see COPYING for details.

    This license does not, of course, apply to any output generated by this
    software.

AUTHOR
       Marc Lehmann <schmorp@schmorp.de>
       http://home.schmorp.de/

Revision:	1.2
Committed:	Fri Jan 27 20:39:07 2012 UTC (13 years, 9 months ago) by root
Branch:	MAIN
CVS Tags:	rel-1_1, rel-1_0, HEAD
Changes since 1.1:	+402 -0 lines
Log Message:	1.0
#	Content
1	NAME
2	Perl::LibExtractor - determine perl library subsets for building
3	distributions
4
5	SYNOPSIS
6	use Perl::LibExtractor;
7
8	DESCRIPTION
9	The purpose of this module is to determine subsets of your perl library,
10	that is, a set of files needed to satisfy certain dependencies (e.g. of
11	a program).
12
13	The goal is to extract a part of your perl installation including
14	dependencies. A typical use case for this module would be to find out
15	which files are needed to be build a PAR distribution, to link into an
16	App::Staticperl binary, or to pack with Urlader, to create stand-alone
17	distributions tailormade to run your app.
18
19	METHODS
20	To use this module, first call the "new"-constructor and then as many
21	other methods as you want, to generate a set of files. Then query the
22	set of files and do whatever you want with them.
23
24	The command-line utility perl-libextract can be a convenient alternative
25	to using this module directly, and offers a few extra options, such as
26	to copy out the files into a new directory, strip them and/or manipulate
27	them in other ways.
28
29	CREATION
30	$extractor = new Perl::LibExtractor [key => value...]
31	Creates a new extractor object. Each extractor object stores some
32	configuration options and a subset of files that can be queried at
33	any time,.
34
35	Binary executables (such as the perl interpreter) are stored inside
36	bin/, perl scripts are stored under script/, perl library files are
37	stored under lib/ and shared libraries are stored under dll/.
38
39	The following key-value pairs exist, with default values as
40	specified.
41
42	inc => \@INC without "."
43	An arrayref with paths to perl library directories. The default
44	is "\@INC", with . removed.
45
46	To prepend custom dirs just do this:
47
48	inc => ["mydir", @INC],
49
50	use_packlist => 1
51	Enable (if true) or disable the use of ".packlist" files. If
52	enabled, then each time a file is traced, the complete
53	distribution that contains it is included (but not traced).
54
55	If disabled, only shared objects and autoload files will be
56	added.
57
58	Debian GNU/Linux doesn't completely package perl or any perl
59	modules, so this option will fail. Other perls should be fine.
60
61	extra_deps => { file => [files...] }
62	Some (mainly runtime dependencies in the perl core library)
63	cannot be detected automatically by this module, especially if
64	you don't use packlists and "add_core".
65
66	This module comes with a set of default dependencies (such as
67	Carp requiring Carp::Heavy), which you cna override with this
68	parameter.
69
70	To see the default set of dependencies that come with this
71	module, use this:
72
73	perl -MPerl::LibExtractor -MData::Dumper -e 'print Dumper $Perl::LibExtractor::EXTRA_DEPS'
74
75	TRACE/PACKLIST BASED ADDING
76	The following methods add various things to the set of files.
77
78	Each time a perl file is added, it is scanned by tracing either loading,
79	execution or compiling it, and seeing which other perl modules and
80	libraries have been loaded.
81
82	For each library file found this way, additional dependencies are added:
83	if packlists are enabled, then all files of the distribution that
84	contains the file will be added. If packlists are disabled, then only
85	shared objects and autoload files for modules will be added.
86
87	Only files from perl library directories will be added automatically.
88	Any other files (such as manpages or scripts installed in the bin
89	directory) are skipped.
90
91	If there is an error, such as a module not being found, then this module
92	croaks (as opposed to silently skipping). If you want to add something
93	of which you are not sure it exists, then you can wrap the call into
94	"eval {}". In some cases, you can avoid this by executing the code you
95	want to work later using "add_eval" - see "add_core_support" for an
96	actual example of this technique.
97
98	Note that packlists are meant to add files not covered by other
99	mechanisms, such as resource files and other data files loaded directly
100	by a module - they are not meant to add dependencies that are missed
101	because they only happen at runtime.
102
103	For example, with packlists, when using AnyEvent, then all event loop
104	backends are automatically added as well, but not any event loops
105	(i.e. AnyEvent::Impl::POE is added, but POE itself is not). Without
106	packlists, only the backend that is being used is added (i.e. normally
107	none, as loading AnyEvent does not instantly load any backend).
108
109	To catch the extra event loop dependencies, you can either initialise
110	AnyEvent so it picks a suitable backend:
111
112	$extractor->add_eval ("use AnyEvent; AnyEvent::detect");
113
114	Or you can directly load the backend modules you plan to use:
115
116	$extractor->add_mod ("AnyEvent::Impl::EV", "AnyEvent::Impl::Perl");
117
118	An example of a program (or module) that has extra resource files is
119	Deliantra::Client - the normal tracing (without packlist usage) will
120	correctly add all submodules, but miss the fonts and textures. By using
121	the packlist, those files are added correctly.
122
123	$extractor->add_mod ($module[, $module...])
124	Adds the given module(s) to the file set - the module name must be
125	specified as in "use", i.e. with "::" as separators and without .pm.
126
127	The program will be loaded with the default import list, any
128	dependent files, such as the shared object implementing xs
129	functions, or autoload files, will also be added.
130
131	If you want to use a different import list (for those rare modules
132	wghere import lists trigger different backend modules to be loaded
133	for example), you can use "add_eval" instead:
134
135	$extractor->add_eval ("use Module qw(a b c)");
136
137	Example: add Coro.pm and AnyEvent/AIO.pm, and all relevant files
138	from the distribution they are part of.
139
140	$extractor->add_mod ("Coro", "AnyEvent::AIO");
141
142	$extractor->add_require ($name[, $name...])
143	Works like "add_mod", but uses "require $name" to load the module,
144	i.e. the name must be a filename.
145
146	Example: load Coro and AnyEvent::AIO, but using "add_require"
147	instead of "add_mod".
148
149	$extractor->add_require ("Coro.pm", "AnyEvent/AIO.pm");
150
151	$extractor->add_bin ($name[, $name...])
152	Adds the given (perl) program(s) to the file set, that is, a program
153	installed by some perl module, written in perl (an example would be
154	the perl-libextract program that is part of the "Perl::LibExtractor"
155	distribution).
156
157	Example: add the deliantra client program installed by the
158	Deliantra::Client module and put it under bin/deliantra.
159
160	$extractor->add_bin ("deliantra");
161
162	$extractor->add_eval ($string)
163	Evaluates the string as perl code and adds all modules that are
164	loaded by it. For example, this would add AnyEvent and the default
165	backend implementation module and event loop module:
166
167	$extractor->add_eval ("use AnyEvent; AnyEvent::detect");
168
169	Each code snippet will be executed in its own package and under "use
170	strict".
171
172	OTHER METHODS FOR ADDING FILES
173	The following methods add commonly used files that are either not
174	covered by other methods or add commonly-used dependencies.
175
176	$extractor->add_perl
177	Adds the perl binary itself to the file set, including the libperl
178	dll, if needed.
179
180	For example, on UNIX systems, this usually adds a exe/perl and
181	possibly some dll/libperl.so.XXX.
182
183	$extractor->add_core_support
184	Try to add modules and files needed to support commonly-used builtin
185	language features. For example to open a scalar for I/O you need the
186	PerlIO::scalar module:
187
188	open $fh, "<", \$scalar
189
190	A number of regex and string features (e.g. "ucfirst") need some
191	unicore files, e.g.:
192
193	'my $x = chr 1234; "\u$x\U$x\l$x\L$x"; $x =~ /\d\|\w\|\s\|\b\|$x/i';
194
195	This call adds these files (simply by executing code similar to the
196	above code fragments).
197
198	Notable things that are missing are other PerlIO layers, such as
199	PerlIO::encoding, and named character and character class matches.
200
201	$extractor->add_unicore
202	Adds (hopefully) all files from the unicore database that will ever
203	be needed.
204
205	If you are not sure which unicode character classes and similar
206	unicore databases you need, and you do not care about an extra one
207	thousand(!) files comprising 4MB of data, then you can just call
208	this method, which adds basically all files from perl's unicode
209	database.
210
211	Note that "add_core_support" also adds some unicore files, but it's
212	not a subset of "add_unicore" - the former adds all files neccessary
213	to support core builtins (which includes some unicore files and
214	other things), while the latter adds all unicore files (but nothing
215	else).
216
217	When in doubt, use both.
218
219	$extractor->add_core
220	This adds all files from the perl core distribution, that is, all
221	library files that come with perl.
222
223	This is a superset of "add_core_support" and "add_unicore".
224
225	This is quite a lot, but on the plus side, you can be sure nothing
226	is missing.
227
228	This requires a full perl installation - Debian GNU/Linux doesn't
229	package the full perl library, so this function will not work there.
230
231	GLOB-BASED ADDING AND FILTERING
232	These methods add or manipulate files by using glob-based patterns.
233
234	These glob patterns work similarly to glob patterns in the shell:
235
236	/ A / at the start of the pattern interprets the pattern as a file
237	path inside the file set, almost the same as in the shell. For
238	example, /bin/perl* would match all files whose names starting with
239	perl inside the bin directory in the set.
240
241	If the / is missing, then the pattern is interpreted as a module
242	name (a .pm file). For example, Coro matches the file lib/Coro.pm ,
243	while Coro::* would match lib/Coro/*.pm.
244
245	* A single star matches anything inside a single directory component.
246	For example, /lib/Coro/*.pm would match all .pm files inside the
247	lib/Coro/ directory, but not any files deeper in the hierarchy.
248
249	Another way to look at it is that a single star matches anything but
250	a slash (/).
251
252	** A double star matches any number of characters in the path,
253	including /.
254
255	For example, AnyEvent::** would match all modules whose names start
256	with "AnyEvent::", no matter how deep in the hierarchy they are.
257
258	$extractor->add_glob ($modglob[, $modglob...])
259	Adds all files from the perl library that match the given glob
260	pattern.
261
262	For example, you could implement "add_unicore" yourself like this:
263
264	$extractor->add_glob ("/unicore/**.pl");
265
266	$extractor->filter ($pattern[, $pattern...])
267	Applies a series of include/exclude filters. Each filter must start
268	with either "+" or "-", to designate the pattern as include or
269	exclude pattern. The rest of the pattern is a normal glob pattern.
270
271	An exclude pattern ("-") instantly removes all matching files from
272	the set. An include pattern ("+") protects matching files from later
273	removals.
274
275	That is, if you have an include pattern then all files that were
276	matched by it will be included in the set, regardless of any further
277	exclude patterns matching the same files.
278
279	Likewise, any file excluded by a pattern will not be included in the
280	set, even if matched by later include patterns.
281
282	Any files not matched by any expression will simply stay in the set.
283
284	For example, to remove most of the useless autoload functions by the
285	POSIX module (they either do the same thing as a builtin or always
286	raise an error), you would use this:
287
288	$extractor->filter ("-/lib/auto/POSIX/*.al");
289
290	This does not remove all autoload files, only the ones not defined
291	by a subclass (e.g. it leaves "POSIX::SigRt::xxx" alone).
292
293	$extractor->runtime_only
294	This removes all files that are not needed at runtime, such as
295	static archives, header and other files needed only for compilation
296	of modules, and pod and html files (which are unlikely to be needed
297	at runtime).
298
299	This is quite useful when you want to have only files actually
300	needed to execute a program.
301
302	RESULT SET
303	$set = $extractor->set
304	Returns a hash reference that represents the result set. The hash is
305	the actual internal storage hash and can only be modified as
306	described below.
307
308	Each key in the hash is the path inside the set, without a leading
309	slash, e.g.:
310
311	bin/perl
312	lib/unicore/lib/Blk/Superscr.pl
313	lib/AnyEvent/Impl/EV.pm
314
315	The value is an array reference with mostly unspecified contents,
316	except the first element, which is the file system path where the
317	actual file can be found.
318
319	This code snippet lists all files inside the set:
320
321	print "$_\n"
322	for sort keys %{ $extractor->set });
323
324	This code fragment prints "filesystem_path => set_path" pairs for
325	all files in the set:
326
327	my $set = $extractor->set;
328	while (my ($set,$fspath) = each %$set) {
329	print "$fspath => $set\n";
330	}
331
332	You can implement your own filtering by asking for the result set
333	with "$extractor->set", and then deleting keys from the referenced
334	hash - since you can ask for the result set at any time you can add
335	things, filter them out this way, and add additional things.
336
337	EXAMPLE
338	To package he deliantra client (Deliantra::Client), finding all (perl)
339	files needed to run it is a first step. This can be done by using
340	something like the following code snippet:
341
342	my $ex = new Perl::LibExtractor;
343
344	$ex->add_perl;
345	$ex->add_core_support;
346	$ex->add_bin ("deliantra");
347	$ex->add_mod ("AnyEvent::Impl::EV");
348	$ex->add_mod ("AnyEvent::Impl::Perl");
349	$ex->add_mod ("Urlader");
350	$ex->filter ("-//auto/POSIX/*.al");
351	$ex->runtime_only;
352
353	First it sets the perl library directory to pm and . (the latter to work
354	around some AutoLoader bugs), so perl uses only the perl library files
355	that came with the binary package.
356
357	Then it sets some environment variable to override the system default
358	(which might be incompatible).
359
360	Then it runs the client itself, using "require". Since "require" only
361	looks in the perl library directory this is the reaosn why the scripts
362	were put there (of course, since . is also included it doesn't matter,
363	but I refuse to yield to bugs).
364
365	Finally it exits with a clean status to signal "ok" to Urlader.
366
367	Back to the original "Perl::LibExtractor" script: after initialising a
368	new set, the script simply adds the perl interpreter and core support
369	files (just in case, not all are needed, but some are, and I am too lazy
370	to find out which ones exactly).
371
372	Then it adds the deliantra executable itself, which in turn adds most of
373	the required modules. After that, the AnyEvent implementation modules
374	are added because these dependencies are not picked up automatically.
375
376	The Urlader module is added because the client itself does not depend on
377	it at all, but the wrapper does.
378
379	At this point, all required files are present, and it's time to slim
380	down: most of the ueseless POSIX autoloaded functions are removed, not
381	because they are so big, but because creating files is a costly
382	operation in itself, so even small fiels have considerable overhead when
383	unpacking. Then files not required for running the client are removed.
384
385	And that concludes it, the set is now ready.
386
387	SEE ALSO
388	The utility program that comes with this module: perl-libextract.
389
390	App::Staticperl, Urlader, Perl::Squish.
391
392	LICENSE
393	This software package is licensed under the GPL version 3 or any later
394	version, see COPYING for details.
395
396	This license does not, of course, apply to any output generated by this
397	software.
398
399	AUTHOR
400	Marc Lehmann <schmorp@schmorp.de>
401	http://home.schmorp.de/
402