cvsroot/Perl-LibExtractor/LibExtractor.pm

=head1 NAME

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

=head1 SYNOPSIS

   use Perl::LibExtractor;

=head1 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 example for this module would be to find out
which files are needed to be build a L<PAR> distribution, to link into
an L<App::Staticperl> binary, or to pack with L<Urlader>, to create
stand-alone distributions tailormade to run your app.

=head1 METHODS

To use this module, first call the C<new>-constructor and then as many
other methods as you want, to generate a set of files.

=over 4

=cut

package Perl::LibExtractor;

our $VERSION = '0.1';

use Config;
use File::Temp ();

use common::sense;

sub I_SRC  () { 0 }
sub I_DEP  () { 1 }
sub I_FLAGS() { 2 }

sub T_PL () { 1 }
sub T_PM () { 2 }
sub T_EXE() { 3 }
sub T_BIN() { 4 }
sub T_DLL() { 5 }

sub F_EVAL () { 0x01 }
sub F_STRIP() { 0x02 }

sub croak($) {
   require Carp;
   Carp::croak "(Perl::LibExtractor) $_[0]";
}

=item $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,.

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

=over 4

=item exedir => "bin"

The prefix to use for the suggested target path for perl
executables. Defaults to F<bin>.

=item libdir => "lib"

The prefix to use for the suggested target path of perl library
files (F<.pm>, F<.pl>, dynamic objects, autoloader index and files
etc.). Defaults to F<lib>.

=item bindir => "bin"

The prefix to use for the suggested target path for (non-perl)
executables. Defaults to F<bin>.

=item dlldir => "bin"

The prefix to use for the suggested target path of any shared
libraries. Defaults to F<bin>.

=item inc => \@INC without "."

An arrayref with paths to perl library directories. The default is
C<\@INC>, with F<.> removed.

To prepend custom dirs just do this:

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

=item use_packlists => 1

Enable (if true) or disable the use of C<.packlists>. If enabled, then
each time a module is included, the complete distribution that contains
it is included as well. See L<ALGORITHMS>, below.

=back

=cut

sub new {
   my ($class, %kv) = @_;

   my $self = bless {
      exedir => "bin",
      libdir => "lib",
      bindir => "bin",
      dlldir => "bin",
      inc    => [grep $_ ne ".", @INC],
      use_packlists => 1,
      %kv,
      set    => {},
   }, $class;

   my %inc_seen;
   my @inc = grep !$inc_seen{$_}++, @{ $self->{inc} };
   $self->{inc} = \@inc;

   $self->_set_inc;

   $self
}

sub _set_inc {
   my ($self) = @_;

   my %lib;

   # find all files in all libdirs, earlier ones overwrite later ones
   for my $dir (reverse @{ $self->{inc} }) {
      my $scan = sub {
         my $pfx = length $_[1] ? "$_[1]/" : "";
         #my (@dirs, @files);

         for (do {
            opendir my $fh, "$dir/$_[1]"
               or croak "$dir/$_[1]: $!";
            grep !/^\.\.?$/, readdir $fh
         }) {
            if (-d "$dir/$_[1]/$_/.") {
               #push @dirs, $_;
               $_[0]($_[0], "$pfx$_");
               $lib{"$pfx$_/"} = "$dir/$pfx$_";
            } else {
               #push @files, $_;
               $lib{"$pfx$_"} = "$dir/$pfx$_";
            }
         }

         #$lib{"$_[1]/"} = [\@dirs, \@files]; # won't work nice with overwrite
      };

      $scan->($scan, "");
   }

   $self->{lib} = \%lib;

   my $matchprefix = join "|", map "\Q$_", @{ $self->{inc }};
   $self->{matchprefix} = qr<^(?:$matchprefix)/>;
}

sub _add {
   my ($self, $add) = @_;

   my $lib = $self->{lib};
   my $path;

   for (@$add) {
      $path = "$self->{libdir}/$_";

      $self->{set}{$path} ||= do {
         my @info;

         $info[I_SRC] = $lib->{$_}
            or croak "$_: unable to locate file in perl library";

         if (/^(.*)\.pm$/) {
            (my $auto = "auto/$1/") =~ s%::%/%g;
            $auto =~ m%/([^/]+)/$% or die;
            my $base = $1;

            if (exists $lib->{$auto}) {
               # auto dir exists, scan it for cool stuff

               # 1. packlists
               my $pack = "$auto.packlist";
               if (my $src = $lib->{$pack} and $self->{use_packlists}) {
                  open my $fh, "<:perlio", $src
                     or croak "$src: $!";

                  my @files;

                  while (<$fh>) {
                     chomp;
                     s/ .*$//; # newer-style .packlists might contain key=value pairs
                     s%/\./%/%g; # yeah, these too

                     # only include certain files (.al, .ix, .pm, .pl)
                     if (/\.(pm|pl|al|ix|\q$Config{dlext}\E)$/) {
                        s/$self->{matchprefix}//
                           or croak "$_: not found in library directory";

                        my $src = $lib->{$_}
                           or croak "$_: not found in library directory";

                        $self->{set}{"$self->{libdir}/$_"} = [$src];
                     }
                  }

                  goto skip; # packlists are supposed to contain all relevant files, including autoload and .so's
               }

               # 1. shared object, others are of no interest to us
               my $so = "$auto$base.$Config{dlext}";
               if (my $src = $lib->{$so}) {
                  $so = "$self->{libdir}/$so";
                  push @{ $info[I_DEP] }, $so; $self->{set}{$so} = [$src];
               }

               # 2. autoloader/autosplit
               my $ix = "${auto}autosplit.ix";
               if (my $src = $lib->{$ix}) {
                  $ix = "$self->{libdir}/$ix";
                  push @{ $info[I_DEP] }, $ix; $self->{set}{$ix} = [$src];

                  open my $fh, "<:perlio", $src
                     or croak "$src: $!";

                  my $package;

                  while (<$fh>) {
                     if (/^\s*sub\s+ ([^[:space:];]+) \s* (?:\([^)]*\))? \s*;?\s*$/x) {
                        my $al = "auto/$package/$1.al";
                        my $src = $lib->{$al}
                           or croak "$al: autoload file not found, but should be there.";

                        $al = "$self->{libdir}/$al";
                        push @{ $info[I_DEP] }, $al; $self->{set}{$al} = [$src];

                     } elsif (/^\s*package\s+([^[:space:];]+)\s*;?\s*$/) {
                        ($package = $1) =~ s/::/\//g;
                     } elsif (/^\s*(?:#|1?\s*;?\s*$)/) {
                        # nop
                     } else {
                        warn "WARNING: $src: unparsable line, please report: $_";
                     }
                  }
               }

               skip:
            }
         }

         \@info
      };
   }
}

sub _trace {
   my ($self, $file, $eval) = @_;

   $self->{trace_begin} .= "#line \"$file\" 1\n$eval;\n";
}

sub _trace_flush {
   my ($self) = @_;

   return unless exists $self->{trace_begin} or exists $self->{trace_check};

   my $tmpdir = newdir File::Temp;
   my $dir = $tmpdir->dirname;

   open my $fh, ">:perlio", "$dir/eval"
      or croak "$dir/eval: $!";
   syswrite $fh,
      'BEGIN { @INC = (' . (join ", ", map "q\x00$_\x00", @{ $self->{inc} }) . ") }\n"
      . "BEGIN { chdir q\x00$dir\x00 or die q\x00$dir: \$!\x00 }\n"
      . 'BEGIN { ' . (delete $self->{trace_begin}) . "}\n"
      . "CHECK {\n"
         . 'open STDOUT, ">:raw", "out" or die "out: $!";'
         . 'print join "\x00", values %INC;'
         . 'open STDERR, ">stderr";' # suppress "syntax OK" message from perl
      . "}\n"
      . (delete $self->{trace_check});
   close $fh;

   my $secure_perl_path = $Config{perlpath};

   if ($^O ne 'VMS') {
      $secure_perl_path .= $Config{_exe}
         unless $secure_perl_path =~ m/$Config{_exe}$/i;
   }

   system $secure_perl_path, "-c", "$dir/eval"
      and croak "trace failure, check trace process output.";

   my @inc = split /\x00/, do {
      open my $fh, "<:perlio", "$dir/out"
         or croak "$dir/out: $!";
      local $/;
      scalar readline $fh 
   };

   my $matchprefix = $self->{matchprefix};

   # remove the library directory prefix, hope for the best
   s/$matchprefix//
      or croak "$_: file outside any library directory"
      for @inc;

   $self->_add (\@inc);
}

=item $extractor->add_mod ($module[, $module...])

Adds the given module(s) to the file set - the module name must be specified
as in C<use>, i.e. with C<::> as separators and without F<.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.

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

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

=cut

sub add_mod {
   my $self = shift;

   my $pkg = "libextractor" . ++$self->{count};

   $self->_trace ("use $_", "{ package $pkg; use $_ }")
      for @_;
}

=item $extractor->add_exe ($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
L<perl-libextract> program that is part of the C<Perl::LibExtractor>
distribution).

Example: add the deliantra client installed by the L<Deliantra::Client>
module.

   $extractor->add_exe ("deliantra");

=cut

sub add_exe {
   my $self = shift;

   exe:
   for my $exe (@_) {
      for my $dir ($Config{sitebinexp}, $Config{vendorbinexp}, $Config{binexp}) {
         if (open my $fh, "<:perlio", "$dir/$exe") {

            my $file = do { local $/; readline $fh };

            $self->_trace_flush if exists $self->{trace_check};
            $self->{trace_check} = $file;

            $self->{set}{"$self->{exedir}/$exe"} = ["$dir/$exe"];
            next exe;
         }
      }

      croak "add_exe ($exe): executable not found";
   }
}

=item $extractor->add_eval ($string)

Evaluates the string and adds all modules that are loaded by it. For
example, this would add L<AnyEvent> and the default backend implementation
module and event loop module:

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

=cut

sub add_eval {
   my ($self, $eval) = @_;

   $eval =~ s/\x00/\x00."\\x00".q\x00/g;
   $self->_trace ($eval, "eval q\x00$eval\x00 or die;\n");
}

=item $extractor->add_perl

Adds the perl binary itself to the file set, including the libperl dll, if
needed.

=item $extractor->add_unicore_minimal

=item $extractor->add_unicore_all

=item $extractor->add_glob ($modglob[, $modglob...])

#TODO#

=item $extractor->filter ($pattern[, $pattern...])

Applies a series of include/exclude filters. Each filter must start
with either C<+> or C<->, to designate the pattern as I<include> or
I<exclude> pattern. The rest of the pattern is an extended glob pattern
(see L<EXTENDED GLOB PATTERNS>).

Each pattern is instantly applied, and all matching files will be
permanently included or excluded, 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 matches by later include patterns.

Any files not matched by any expression will be included, that is, the
filter list has an implicit C<+/**> pattern at the end.

#TODO#

=item $extractor->add_auto

#todo, not like this

=back

=head1 ALGORITHMS
#TODO

=head2 Module/trace-based additions
#TODO

For example, when using L<Coro::AnyEvent> or
L<AnyEvent::DNS> are added, then also all (relevant) files from the
L<Coro> and L<AnyEvent> distributions will be included.

The only exception is perl itself

=head2 Glob/path-based modifications
#TODO

=head1 EXTENDED GLOB PATTERNS

=head1 SEE ALSO

The utility program that comes with this module: L<perl-libextract>.

L<App::Staticperl>, L<Urlader>, L<Perl::Squish>.

=head1 AUTHOR

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

=cut

1;

Revision:	1.1
Committed:	Fri Jan 13 20:36:40 2012 UTC (14 years, 8 months ago) by root
Branch:	MAIN
Log Message:	* empty log message *
#	User	Rev	Content
1	root	1.1	=head1 NAME
2
3			Perl::LibExtractor - determine perl library subsets for building distributions
4
5			=head1 SYNOPSIS
6
7			use Perl::LibExtractor;
8
9			=head1 DESCRIPTION
10
11			The purpose of this module is to determine subsets of your perl library,
12			that is, a set of files needed to satisfy certain dependencies (e.g. of a
13			program).
14
15			The goal is to extract a part of your perl installation including
16			dependencies. A typical example for this module would be to find out
17			which files are needed to be build a L<PAR> distribution, to link into
18			an L<App::Staticperl> binary, or to pack with L<Urlader>, to create
19			stand-alone distributions tailormade to run your app.
20
21			=head1 METHODS
22
23			To use this module, first call the C<new>-constructor and then as many
24			other methods as you want, to generate a set of files.
25
26			=over 4
27
28			=cut
29
30			package Perl::LibExtractor;
31
32			our $VERSION = '0.1';
33
34			use Config;
35			use File::Temp ();
36
37			use common::sense;
38
39			sub I_SRC () { 0 }
40			sub I_DEP () { 1 }
41			sub I_FLAGS() { 2 }
42
43			sub T_PL () { 1 }
44			sub T_PM () { 2 }
45			sub T_EXE() { 3 }
46			sub T_BIN() { 4 }
47			sub T_DLL() { 5 }
48
49			sub F_EVAL () { 0x01 }
50			sub F_STRIP() { 0x02 }
51
52			sub croak($) {
53			require Carp;
54			Carp::croak "(Perl::LibExtractor) $_[0]";
55			}
56
57			=item $extractor = new Perl::LibExtractor [key => value...]
58
59			Creates a new extractor object. Each extractor object stores some
60			configuration options and a subset of files that can be queried at any
61			time,.
62
63			The following key-value pairs exist, with default values as specified.
64
65			=over 4
66
67			=item exedir => "bin"
68
69			The prefix to use for the suggested target path for perl
70			executables. Defaults to F<bin>.
71
72			=item libdir => "lib"
73
74			The prefix to use for the suggested target path of perl library
75			files (F<.pm>, F<.pl>, dynamic objects, autoloader index and files
76			etc.). Defaults to F<lib>.
77
78			=item bindir => "bin"
79
80			The prefix to use for the suggested target path for (non-perl)
81			executables. Defaults to F<bin>.
82
83			=item dlldir => "bin"
84
85			The prefix to use for the suggested target path of any shared
86			libraries. Defaults to F<bin>.
87
88			=item inc => \@INC without "."
89
90			An arrayref with paths to perl library directories. The default is
91			C<\@INC>, with F<.> removed.
92
93			To prepend custom dirs just do this:
94
95			inc => ["mydir", @INC],
96
97			=item use_packlists => 1
98
99			Enable (if true) or disable the use of C<.packlists>. If enabled, then
100			each time a module is included, the complete distribution that contains
101			it is included as well. See L<ALGORITHMS>, below.
102
103			=back
104
105			=cut
106
107			sub new {
108			my ($class, %kv) = @_;
109
110			my $self = bless {
111			exedir => "bin",
112			libdir => "lib",
113			bindir => "bin",
114			dlldir => "bin",
115			inc => [grep $_ ne ".", @INC],
116			use_packlists => 1,
117			%kv,
118			set => {},
119			}, $class;
120
121			my %inc_seen;
122			my @inc = grep !$inc_seen{$_}++, @{ $self->{inc} };
123			$self->{inc} = \@inc;
124
125			$self->_set_inc;
126
127			$self
128			}
129
130			sub _set_inc {
131			my ($self) = @_;
132
133			my %lib;
134
135			# find all files in all libdirs, earlier ones overwrite later ones
136			for my $dir (reverse @{ $self->{inc} }) {
137			my $scan = sub {
138			my $pfx = length $_[1] ? "$_[1]/" : "";
139			#my (@dirs, @files);
140
141			for (do {
142			opendir my $fh, "$dir/$_[1]"
143			or croak "$dir/$_[1]: $!";
144			grep !/^\.\.?$/, readdir $fh
145			}) {
146			if (-d "$dir/$_[1]/$_/.") {
147			#push @dirs, $_;
148			$_[0]($_[0], "$pfx$_");
149			$lib{"$pfx$_/"} = "$dir/$pfx$_";
150			} else {
151			#push @files, $_;
152			$lib{"$pfx$_"} = "$dir/$pfx$_";
153			}
154			}
155
156			#$lib{"$_[1]/"} = [\@dirs, \@files]; # won't work nice with overwrite
157			};
158
159			$scan->($scan, "");
160			}
161
162			$self->{lib} = \%lib;
163
164			my $matchprefix = join "\|", map "\Q$_", @{ $self->{inc }};
165			$self->{matchprefix} = qr<^(?:$matchprefix)/>;
166			}
167
168			sub _add {
169			my ($self, $add) = @_;
170
171			my $lib = $self->{lib};
172			my $path;
173
174			for (@$add) {
175			$path = "$self->{libdir}/$_";
176
177			$self->{set}{$path} \|\|= do {
178			my @info;
179
180			$info[I_SRC] = $lib->{$_}
181			or croak "$_: unable to locate file in perl library";
182
183			if (/^(.*)\.pm$/) {
184			(my $auto = "auto/$1/") =~ s%::%/%g;
185			$auto =~ m%/([^/]+)/$% or die;
186			my $base = $1;
187
188			if (exists $lib->{$auto}) {
189			# auto dir exists, scan it for cool stuff
190
191			# 1. packlists
192			my $pack = "$auto.packlist";
193			if (my $src = $lib->{$pack} and $self->{use_packlists}) {
194			open my $fh, "<:perlio", $src
195			or croak "$src: $!";
196
197			my @files;
198
199			while (<$fh>) {
200			chomp;
201			s/ .*$//; # newer-style .packlists might contain key=value pairs
202			s%/\./%/%g; # yeah, these too
203
204			# only include certain files (.al, .ix, .pm, .pl)
205			if (/\.(pm\|pl\|al\|ix\|\q$Config{dlext}\E)$/) {
206			s/$self->{matchprefix}//
207			or croak "$_: not found in library directory";
208
209			my $src = $lib->{$_}
210			or croak "$_: not found in library directory";
211
212			$self->{set}{"$self->{libdir}/$_"} = [$src];
213			}
214			}
215
216			goto skip; # packlists are supposed to contain all relevant files, including autoload and .so's
217			}
218
219			# 1. shared object, others are of no interest to us
220			my $so = "$auto$base.$Config{dlext}";
221			if (my $src = $lib->{$so}) {
222			$so = "$self->{libdir}/$so";
223			push @{ $info[I_DEP] }, $so; $self->{set}{$so} = [$src];
224			}
225
226			# 2. autoloader/autosplit
227			my $ix = "${auto}autosplit.ix";
228			if (my $src = $lib->{$ix}) {
229			$ix = "$self->{libdir}/$ix";
230			push @{ $info[I_DEP] }, $ix; $self->{set}{$ix} = [$src];
231
232			open my $fh, "<:perlio", $src
233			or croak "$src: $!";
234
235			my $package;
236
237			while (<$fh>) {
238			if (/^\ssub\s+ ([^[:space:];]+) \s (?:\([^)]\))? \s;?\s*$/x) {
239			my $al = "auto/$package/$1.al";
240			my $src = $lib->{$al}
241			or croak "$al: autoload file not found, but should be there.";
242
243			$al = "$self->{libdir}/$al";
244			push @{ $info[I_DEP] }, $al; $self->{set}{$al} = [$src];
245
246			} elsif (/^\spackage\s+([^[:space:];]+)\s;?\s*$/) {
247			($package = $1) =~ s/::/\//g;
248			} elsif (/^\s(?:#\|1?\s;?\s*$)/) {
249			# nop
250			} else {
251			warn "WARNING: $src: unparsable line, please report: $_";
252			}
253			}
254			}
255
256			skip:
257			}
258			}
259
260			\@info
261			};
262			}
263			}
264
265			sub _trace {
266			my ($self, $file, $eval) = @_;
267
268			$self->{trace_begin} .= "#line \"$file\" 1\n$eval;\n";
269			}
270
271			sub _trace_flush {
272			my ($self) = @_;
273
274			return unless exists $self->{trace_begin} or exists $self->{trace_check};
275
276			my $tmpdir = newdir File::Temp;
277			my $dir = $tmpdir->dirname;
278
279			open my $fh, ">:perlio", "$dir/eval"
280			or croak "$dir/eval: $!";
281			syswrite $fh,
282			'BEGIN { @INC = (' . (join ", ", map "q\x00$_\x00", @{ $self->{inc} }) . ") }\n"
283			. "BEGIN { chdir q\x00$dir\x00 or die q\x00$dir: \$!\x00 }\n"
284			. 'BEGIN { ' . (delete $self->{trace_begin}) . "}\n"
285			. "CHECK {\n"
286			. 'open STDOUT, ">:raw", "out" or die "out: $!";'
287			. 'print join "\x00", values %INC;'
288			. 'open STDERR, ">stderr";' # suppress "syntax OK" message from perl
289			. "}\n"
290			. (delete $self->{trace_check});
291			close $fh;
292
293			my $secure_perl_path = $Config{perlpath};
294
295			if ($^O ne 'VMS') {
296			$secure_perl_path .= $Config{_exe}
297			unless $secure_perl_path =~ m/$Config{_exe}$/i;
298			}
299
300			system $secure_perl_path, "-c", "$dir/eval"
301			and croak "trace failure, check trace process output.";
302
303			my @inc = split /\x00/, do {
304			open my $fh, "<:perlio", "$dir/out"
305			or croak "$dir/out: $!";
306			local $/;
307			scalar readline $fh
308			};
309
310			my $matchprefix = $self->{matchprefix};
311
312			# remove the library directory prefix, hope for the best
313			s/$matchprefix//
314			or croak "$_: file outside any library directory"
315			for @inc;
316
317			$self->_add (\@inc);
318			}
319
320			=item $extractor->add_mod ($module[, $module...])
321
322			Adds the given module(s) to the file set - the module name must be specified
323			as in C<use>, i.e. with C<::> as separators and without F<.pm>.
324
325			The program will be loaded with the default import list, any dependent
326			files, such as the shared object implementing xs functions, or autoload
327			files, will also be added.
328
329			Example: add F<Coro.pm> and F<AnyEvent/AIO.pm>, and all relevant files
330			from the distribution they are part of.
331
332			$extractor->add_mod ("Coro", "AnyEvent::AIO");
333
334			=cut
335
336			sub add_mod {
337			my $self = shift;
338
339			my $pkg = "libextractor" . ++$self->{count};
340
341			$self->_trace ("use $_", "{ package $pkg; use $_ }")
342			for @_;
343			}
344
345			=item $extractor->add_exe ($name[, $name...])
346
347			Adds the given (perl) program(s) to the file set, that is, a program
348			installed by some perl module, written in perl (an example would be the
349			L<perl-libextract> program that is part of the C<Perl::LibExtractor>
350			distribution).
351
352			Example: add the deliantra client installed by the L<Deliantra::Client>
353			module.
354
355			$extractor->add_exe ("deliantra");
356
357			=cut
358
359			sub add_exe {
360			my $self = shift;
361
362			exe:
363			for my $exe (@_) {
364			for my $dir ($Config{sitebinexp}, $Config{vendorbinexp}, $Config{binexp}) {
365			if (open my $fh, "<:perlio", "$dir/$exe") {
366
367			my $file = do { local $/; readline $fh };
368
369			$self->_trace_flush if exists $self->{trace_check};
370			$self->{trace_check} = $file;
371
372			$self->{set}{"$self->{exedir}/$exe"} = ["$dir/$exe"];
373			next exe;
374			}
375			}
376
377			croak "add_exe ($exe): executable not found";
378			}
379			}
380
381			=item $extractor->add_eval ($string)
382
383			Evaluates the string and adds all modules that are loaded by it. For
384			example, this would add L<AnyEvent> and the default backend implementation
385			module and event loop module:
386
387			$extractor->add_eval ("use AnyEvent; AnyEvent::detect");
388
389			=cut
390
391			sub add_eval {
392			my ($self, $eval) = @_;
393
394			$eval =~ s/\x00/\x00."\\x00".q\x00/g;
395			$self->_trace ($eval, "eval q\x00$eval\x00 or die;\n");
396			}
397
398			=item $extractor->add_perl
399
400			Adds the perl binary itself to the file set, including the libperl dll, if
401			needed.
402
403			=item $extractor->add_unicore_minimal
404
405			=item $extractor->add_unicore_all
406
407			=item $extractor->add_glob ($modglob[, $modglob...])
408
409			#TODO#
410
411			=item $extractor->filter ($pattern[, $pattern...])
412
413			Applies a series of include/exclude filters. Each filter must start
414			with either C<+> or C<->, to designate the pattern as I<include> or
415			I<exclude> pattern. The rest of the pattern is an extended glob pattern
416			(see L<EXTENDED GLOB PATTERNS>).
417
418			Each pattern is instantly applied, and all matching files will be
419			permanently included or excluded, that is, if you have an include pattern
420			then all files that were matched by it will be included in the set,
421			regardless of any further exclude patterns matching the same files.
422
423			Likewise, any file excluded by a pattern will not be included in the set,
424			even if matches by later include patterns.
425
426			Any files not matched by any expression will be included, that is, the
427			filter list has an implicit C<+/**> pattern at the end.
428
429			#TODO#
430
431			=item $extractor->add_auto
432
433			#todo, not like this
434
435			=back
436
437			=head1 ALGORITHMS
438			#TODO
439
440			=head2 Module/trace-based additions
441			#TODO
442
443			For example, when using L<Coro::AnyEvent> or
444			L<AnyEvent::DNS> are added, then also all (relevant) files from the
445			L<Coro> and L<AnyEvent> distributions will be included.
446
447			The only exception is perl itself
448
449			=head2 Glob/path-based modifications
450			#TODO
451
452			=head1 EXTENDED GLOB PATTERNS
453
454			=head1 SEE ALSO
455
456			The utility program that comes with this module: L<perl-libextract>.
457
458			L<App::Staticperl>, L<Urlader>, L<Perl::Squish>.
459
460			=head1 AUTHOR
461
462			Marc Lehmann <schmorp@schmorp.de>
463			http://home.schmorp.de/
464
465			=cut
466
467			1;
468