← Index
NYTProf Performance Profile   « line view »
For flows_to_es.pl
  Run on Mon May 9 23:27:59 2016
Reported on Mon May 9 23:28:08 2016

Filename/usr/share/perl5/local/lib.pm
StatementsExecuted 160 statements in 3.93ms
Subroutines
Calls P F Exclusive
Time		 Inclusive
Time		 Subroutine
1113.03ms9.59mslocal::lib::::BEGIN@10local::lib::BEGIN@10
1111.99ms2.96mslocal::lib::::BEGIN@9local::lib::BEGIN@9
111717µs837µslocal::lib::::BEGIN@11local::lib::BEGIN@11
311168µs190µslocal::lib::::_env_list_valuelocal::lib::_env_list_value
11161µs610µslocal::lib::::importlocal::lib::import
11142µs430µslocal::lib::::setup_local_lib_forlocal::lib::setup_local_lib_for
22126µs171µslocal::lib::::__ANON__[:89]local::lib::__ANON__[:89]
11123µs265µslocal::lib::::build_activate_environment_vars_forlocal::lib::build_activate_environment_vars_for
11117µs288µslocal::lib::::setup_env_hash_forlocal::lib::setup_env_hash_for
11115µs15µslocal::lib::::BEGIN@6local::lib::BEGIN@6
32113µs13µslocal::lib::::pipelinelocal::lib::pipeline
153111µs11µslocal::lib::::CORE:matchlocal::lib::CORE:match (opcode)
11111µs27µsmain::::BEGIN@1 main::BEGIN@1
11111µs11µslocal::lib::::_uniqlocal::lib::_uniq
22111µs11µslocal::lib::::CORE:regcomplocal::lib::CORE:regcomp (opcode)
11110µs10µslocal::lib::::CORE:ftdirlocal::lib::CORE:ftdir (opcode)
11110µs55µslocal::lib::::ensure_dir_structure_forlocal::lib::ensure_dir_structure_for
9119µs9µslocal::lib::::__ANON__[:387]local::lib::__ANON__[:387]
1118µs50µslocal::lib::::resolve_relative_pathlocal::lib::resolve_relative_path
1118µs30µslocal::lib::::install_base_perl_pathlocal::lib::install_base_perl_path
1118µs108µslocal::lib::::resolve_pathlocal::lib::resolve_path
1118µs12µsmain::::BEGIN@2 main::BEGIN@2
1116µs271µslocal::lib::::build_environment_vars_forlocal::lib::build_environment_vars_for
1115µs56µslocal::lib::::__ANON__[:93]local::lib::__ANON__[:93]
1115µs22µslocal::lib::::install_base_bin_pathlocal::lib::install_base_bin_path
1114µs4µslocal::lib::::resolve_home_pathlocal::lib::resolve_home_path
1112µs2µslocal::lib::::active_pathslocal::lib::active_paths
1112µs2µslocal::lib::::resolve_empty_pathlocal::lib::resolve_empty_path
0000s0slocal::lib::::__ANON__[:484]local::lib::__ANON__[:484]
0000s0slocal::lib::::__ANON__[:491]local::lib::__ANON__[:491]
0000s0slocal::lib::::__ANON__[:530]local::lib::__ANON__[:530]
0000s0slocal::lib::::__ANON__[:539]local::lib::__ANON__[:539]
0000s0slocal::lib::::build_bourne_env_declarationlocal::lib::build_bourne_env_declaration
0000s0slocal::lib::::build_csh_env_declarationlocal::lib::build_csh_env_declaration
0000s0slocal::lib::::build_deact_all_environment_vars_forlocal::lib::build_deact_all_environment_vars_for
0000s0slocal::lib::::build_deactivate_environment_vars_forlocal::lib::build_deactivate_environment_vars_for
0000s0slocal::lib::::build_win32_env_declarationlocal::lib::build_win32_env_declaration
0000s0slocal::lib::::environment_vars_string_forlocal::lib::environment_vars_string_for
0000s0slocal::lib::::guess_shelltypelocal::lib::guess_shelltype
0000s0slocal::lib::::install_base_arch_pathlocal::lib::install_base_arch_path
0000s0slocal::lib::::print_environment_vars_forlocal::lib::print_environment_vars_for
Call graph for these subroutines as a Graphviz dot language file.
Line State
ments		 Time
on line		 Calls Time
in subs		 Code
1227µs242µs
# spent 27µs (11+15) within main::BEGIN@1 which was called: # once (11µs+15µs) by main::BEGIN@5 at line 1
use strict;
# spent 27µs making 1 call to main::BEGIN@1 # spent 15µs making 1 call to strict::import
2234µs216µs
# spent 12µs (8+4) within main::BEGIN@2 which was called: # once (8µs+4µs) by main::BEGIN@5 at line 2
use warnings;
# spent 12µs making 1 call to main::BEGIN@2 # spent 4µs making 1 call to warnings::import
3
4package local::lib;
5
6251µs115µs
# spent 15µs within local::lib::BEGIN@6 which was called: # once (15µs+0s) by main::BEGIN@5 at line 6
use 5.008001; # probably works with earlier versions but I'm not supporting them
# spent 15µs making 1 call to local::lib::BEGIN@6
7 # (patches would, of course, be welcome)
8
92107µs12.96ms
# spent 2.96ms (1.99+966µs) within local::lib::BEGIN@9 which was called: # once (1.99ms+966µs) by main::BEGIN@5 at line 9
use File::Spec ();
# spent 2.96ms making 1 call to local::lib::BEGIN@9
102112µs19.59ms
# spent 9.59ms (3.03+6.56) within local::lib::BEGIN@10 which was called: # once (3.03ms+6.56ms) by main::BEGIN@5 at line 10
use File::Path ();
# spent 9.59ms making 1 call to local::lib::BEGIN@10
1123.13ms2847µs
# spent 837µs (717+120) within local::lib::BEGIN@11 which was called: # once (717µs+120µs) by main::BEGIN@5 at line 11
use Config;
# spent 837µs making 1 call to local::lib::BEGIN@11 # spent 10µs making 1 call to Config::import
12
131700nsour $VERSION = '1.008023'; # 1.8.23
14116µs$VERSION = eval $VERSION;
# spent 2µs executing statements in string eval
15
1611µsour @KNOWN_FLAGS = qw(--self-contained --deactivate --deactivate-all);
17
18sub DEACTIVATE_ONE () { 1 }
19sub DEACTIVATE_ALL () { 2 }
20
21sub INTERPOLATE_ENV () { 1 }
22sub LITERAL_ENV () { 0 }
23
24
# spent 610µs (61+549) within local::lib::import which was called: # once (61µs+549µs) by main::BEGIN@5 at line 5 of flows_to_es.pl
sub import {
251800ns my ($class, @args) = @_;
26
27 # Remember what PERL5LIB was when we started
2811µs my $perl5lib = $ENV{PERL5LIB} || '';
29
301100ns my %arg_store;
3111µs for my $arg (@args) {
32 # check for lethal dash first to stop processing before causing problems
33 # the fancy dash is U+2212 or \xE2\x88\x92
34114µs32µs if ($arg =~ /\xE2\x88\x92/ or $arg =~ /−/) {
# spent 2µs making 3 calls to local::lib::CORE:match, avg 633ns/call
35 die <<'DEATH';
36WHOA THERE! It looks like you've got some fancy dashes in your commandline!
37These are *not* the traditional -- dashes that software recognizes. You
38probably got these by copy-pasting from the perldoc for this module as
39rendered by a UTF8-capable formatter. This most typically happens on an OS X
40terminal, but can happen elsewhere too. Please try again after replacing the
41dashes with normal minus signs.
42DEATH
43 }
44 elsif(grep { $arg eq $_ } @KNOWN_FLAGS) {
45 (my $flag = $arg) =~ s/--//;
46 $arg_store{$flag} = 1;
47 }
48 elsif($arg =~ /^--/) {
49 die "Unknown import argument: $arg";
50 }
51 else {
52 # assume that what's left is a path
5311µs $arg_store{path} = $arg;
54 }
55 }
56
571300ns if($arg_store{'self-contained'}) {
58 die "FATAL: The local::lib --self-contained flag has never worked reliably and the original author, Mark Stosberg, was unable or unwilling to maintain it. As such, this flag has been removed from the local::lib codebase in order to prevent misunderstandings and potentially broken builds. The local::lib authors recommend that you look at the lib::core::only module shipped with this distribution in order to create a more robust environment that is equivalent to what --self-contained provided (although quite possibly not what you originally thought it provided due to the poor quality of the documentation, for which we apologise).\n";
59 }
60
611300ns my $deactivating = 0;
621200ns if ($arg_store{deactivate}) {
63 $deactivating = DEACTIVATE_ONE;
64 }
651100ns if ($arg_store{'deactivate-all'}) {
66 $deactivating = DEACTIVATE_ALL;
67 }
68
6918µs1108µs $arg_store{path} = $class->resolve_path($arg_store{path});
# spent 108µs making 1 call to local::lib::resolve_path
7013µs1430µs $class->setup_local_lib_for($arg_store{path}, $deactivating);
# spent 430µs making 1 call to local::lib::setup_local_lib_for
71
7214µs for (@INC) { # Untaint @INC
73111µs next if ref; # Skip entry if it is an ARRAY, CODE, blessed, etc.
741135µs119µs m/(.*)/ and $_ = $1;
# spent 9µs making 11 calls to local::lib::CORE:match, avg 827ns/call
75 }
76}
77
78sub pipeline;
79
80
# spent 13µs within local::lib::pipeline which was called 3 times, avg 4µs/call: # 2 times (7µs+0s) by local::lib::__ANON__[/usr/share/perl5/local/lib.pm:89] at line 86, avg 4µs/call # once (6µs+0s) by local::lib::resolve_path at line 118
sub pipeline {
8132µs my @methods = @_;
8231µs my $last = pop(@methods);
8339µs if (@methods) {
84
# spent 171µs (26+145) within local::lib::__ANON__[/usr/share/perl5/local/lib.pm:89] which was called 2 times, avg 85µs/call: # once (12µs+82µs) by local::lib::resolve_path at line 118 # once (14µs+63µs) by local::lib::__ANON__[/usr/share/perl5/local/lib.pm:89] at line 86
\sub {
8521µs my ($obj, @args) = @_;
86212µs6145µs $obj->${pipeline @methods}(
# spent 77µs making 1 call to local::lib::__ANON__[local/lib.pm:89] # spent 56µs making 1 call to local::lib::__ANON__[local/lib.pm:93] # spent 7µs making 2 calls to local::lib::pipeline, avg 4µs/call # spent 4µs making 1 call to local::lib::resolve_home_path # spent 2µs making 1 call to local::lib::resolve_empty_path
87 $obj->$last(@args)
88 );
8924µs };
90 } else {
91
# spent 56µs (5+50) within local::lib::__ANON__[/usr/share/perl5/local/lib.pm:93] which was called: # once (5µs+50µs) by local::lib::__ANON__[/usr/share/perl5/local/lib.pm:89] at line 86
\sub {
9218µs150µs shift->$last(@_);
# spent 50µs making 1 call to local::lib::resolve_relative_path
9311µs };
94 }
95}
96
97=begin testing
98
99#:: test pipeline
100
101package local::lib;
102
103{ package Foo; sub foo { -$_[1] } sub bar { $_[1]+2 } sub baz { $_[1]+3 } }
104my $foo = bless({}, 'Foo');
105Test::More::ok($foo->${pipeline qw(foo bar baz)}(10) == -15);
106
107=end testing
108
109=cut
110
111
# spent 11µs within local::lib::_uniq which was called: # once (11µs+0s) by local::lib::setup_local_lib_for at line 243
sub _uniq {
1121200ns my %seen;
113113µs grep { ! $seen{$_}++ } @_;
114}
115
116
# spent 108µs (8+100) within local::lib::resolve_path which was called: # once (8µs+100µs) by local::lib::import at line 69
sub resolve_path {
1171600ns my ($class, $path) = @_;
11814µs2100µs $class->${pipeline qw(
# spent 94µs making 1 call to local::lib::__ANON__[local/lib.pm:89] # spent 6µs making 1 call to local::lib::pipeline
119 resolve_relative_path
120 resolve_home_path
121 resolve_empty_path
122 )}($path);
123}
124
125
# spent 2µs within local::lib::resolve_empty_path which was called: # once (2µs+0s) by local::lib::__ANON__[/usr/share/perl5/local/lib.pm:89] at line 86
sub resolve_empty_path {
1261400ns my ($class, $path) = @_;
12714µs if (defined $path) {
128 $path;
129 } else {
130 '~/perl5';
131 }
132}
133
134=begin testing
135
136#:: test classmethod setup
137
138my $c = 'local::lib';
139
140=end testing
141
142=begin testing
143
144#:: test classmethod
145
146is($c->resolve_empty_path, '~/perl5');
147is($c->resolve_empty_path('foo'), 'foo');
148
149=end testing
150
151=cut
152
153
# spent 4µs (4+300ns) within local::lib::resolve_home_path which was called: # once (4µs+300ns) by local::lib::__ANON__[/usr/share/perl5/local/lib.pm:89] at line 86
sub resolve_home_path {
1541400ns my ($class, $path) = @_;
15516µs1300ns return $path unless ($path =~ /^~/);
# spent 300ns making 1 call to local::lib::CORE:match
156 my ($user) = ($path =~ /^~([^\/]+)/); # can assume ^~ so undef for 'us'
157 my $tried_file_homedir;
158 my $homedir = do {
159 if (eval { require File::HomeDir } && $File::HomeDir::VERSION >= 0.65) {
160 $tried_file_homedir = 1;
161 if (defined $user) {
162 File::HomeDir->users_home($user);
163 } else {
164 File::HomeDir->my_home;
165 }
166 } else {
167 if (defined $user) {
168 (getpwnam $user)[7];
169 } else {
170 if (defined $ENV{HOME}) {
171 $ENV{HOME};
172 } else {
173 (getpwuid $<)[7];
174 }
175 }
176 }
177 };
178 unless (defined $homedir) {
179 require Carp;
180 Carp::croak(
181 "Couldn't resolve homedir for "
182 .(defined $user ? $user : 'current user')
183 .($tried_file_homedir ? '' : ' - consider installing File::HomeDir')
184 );
185 }
186 $path =~ s/^~[^\/]*/$homedir/;
187 $path;
188}
189
190
# spent 50µs (8+42) within local::lib::resolve_relative_path which was called: # once (8µs+42µs) by local::lib::__ANON__[/usr/share/perl5/local/lib.pm:93] at line 92
sub resolve_relative_path {
1911500ns my ($class, $path) = @_;
19219µs142µs $path = File::Spec->rel2abs($path);
# spent 42µs making 1 call to File::Spec::Unix::rel2abs
193}
194
195=begin testing
196
197#:: test classmethod
198
199local *File::Spec::rel2abs = sub { shift; 'FOO'.shift; };
200is($c->resolve_relative_path('bar'),'FOObar');
201
202=end testing
203
204=cut
205
206
# spent 430µs (42+388) within local::lib::setup_local_lib_for which was called: # once (42µs+388µs) by local::lib::import at line 70
sub setup_local_lib_for {
2071700ns my ($class, $path, $deactivating) = @_;
208
2091200ns my $interpolate = LITERAL_ENV;
21011µs12µs my @active_lls = $class->active_paths;
# spent 2µs making 1 call to local::lib::active_paths
211
21211µs155µs $class->ensure_dir_structure_for($path);
# spent 55µs making 1 call to local::lib::ensure_dir_structure_for
213
214 # On Win32 directories often contain spaces. But some parts of the CPAN
215 # toolchain don't like that. To avoid this, GetShortPathName() gives us
216 # an alternate representation that has none.
217 # This only works if the directory already exists.
2181600ns $path = Win32::GetShortPathName($path) if $^O eq 'MSWin32';
219
2201400ns if (! $deactivating) {
2211700ns if (@active_lls && $active_lls[-1] eq $path) {
222 exit 0 if $0 eq '-';
223 return; # Asked to add what's already at the top of the stack
224 } elsif (grep { $_ eq $path} @active_lls) {
225 # Asked to add a dir that's lower in the stack -- so we remove it from
226 # where it is, and then add it back at the top.
227 $class->setup_env_hash_for($path, DEACTIVATE_ONE);
228 # Which means we can no longer output "PERL5LIB=...:$PERL5LIB" stuff
229 # anymore because we're taking something *out*.
230 $interpolate = INTERPOLATE_ENV;
231 }
232 }
233
23414µs if ($0 eq '-') {
235 $class->print_environment_vars_for($path, $deactivating, $interpolate);
236 exit 0;
237 } else {
23812µs1288µs $class->setup_env_hash_for($path, $deactivating);
# spent 288µs making 1 call to local::lib::setup_env_hash_for
23915µs12µs my $arch_dir = $Config{archname};
# spent 2µs making 1 call to Config::FETCH
24012µs124µs @INC = _uniq(
# spent 24µs making 1 call to File::Spec::Unix::catdir
241 (
242 # Inject $path/$archname for each path in PERL5LIB
243117µs317µs map { ( File::Spec->catdir($_, $arch_dir), $_ ) }
# spent 11µs making 1 call to local::lib::_uniq # spent 5µs making 1 call to local::lib::CORE:regcomp # spent 1µs making 1 call to Config::FETCH
244 split($Config{path_sep}, $ENV{PERL5LIB})
245 ),
246 @INC
247 );
248 }
249}
250
251
# spent 22µs (5+17) within local::lib::install_base_bin_path which was called: # once (5µs+17µs) by local::lib::build_activate_environment_vars_for at line 421
sub install_base_bin_path {
2521600ns my ($class, $path) = @_;
25314µs117µs File::Spec->catdir($path, 'bin');
# spent 17µs making 1 call to File::Spec::Unix::catdir
254}
255
256
# spent 30µs (8+22) within local::lib::install_base_perl_path which was called: # once (8µs+22µs) by local::lib::build_activate_environment_vars_for at line 421
sub install_base_perl_path {
2571600ns my ($class, $path) = @_;
25817µs122µs File::Spec->catdir($path, 'lib', 'perl5');
# spent 22µs making 1 call to File::Spec::Unix::catdir
259}
260
261sub install_base_arch_path {
262 my ($class, $path) = @_;
263 File::Spec->catdir($class->install_base_perl_path($path), $Config{archname});
264}
265
266
# spent 55µs (10+45) within local::lib::ensure_dir_structure_for which was called: # once (10µs+45µs) by local::lib::setup_local_lib_for at line 212
sub ensure_dir_structure_for {
2671400ns my ($class, $path) = @_;
268116µs110µs unless (-d $path) {
# spent 10µs making 1 call to local::lib::CORE:ftdir
269 warn "Attempting to create directory ${path}\n";
270 }
27111µs135µs File::Path::mkpath($path);
# spent 35µs making 1 call to File::Path::mkpath
272 return
27313µs}
274
275sub guess_shelltype {
276 my $shellbin = 'sh';
277 if(defined $ENV{'SHELL'}) {
278 my @shell_bin_path_parts = File::Spec->splitpath($ENV{'SHELL'});
279 $shellbin = $shell_bin_path_parts[-1];
280 }
281 my $shelltype = do {
282 local $_ = $shellbin;
283 if(/csh/) {
284 'csh'
285 } else {
286 'bourne'
287 }
288 };
289
290 # Both Win32 and Cygwin have $ENV{COMSPEC} set.
291 if (defined $ENV{'COMSPEC'} && $^O ne 'cygwin') {
292 my @shell_bin_path_parts = File::Spec->splitpath($ENV{'COMSPEC'});
293 $shellbin = $shell_bin_path_parts[-1];
294 $shelltype = do {
295 local $_ = $shellbin;
296 if(/command\.com/) {
297 'win32'
298 } elsif(/cmd\.exe/) {
299 'win32'
300 } elsif(/4nt\.exe/) {
301 'win32'
302 } else {
303 $shelltype
304 }
305 };
306 }
307 return $shelltype;
308}
309
310sub print_environment_vars_for {
311 my ($class, $path, $deactivating, $interpolate) = @_;
312 print $class->environment_vars_string_for($path, $deactivating, $interpolate);
313}
314
315sub environment_vars_string_for {
316 my ($class, $path, $deactivating, $interpolate) = @_;
317 my @envs = $class->build_environment_vars_for($path, $deactivating, $interpolate);
318 my $out = '';
319
320 # rather basic csh detection, goes on the assumption that something won't
321 # call itself csh unless it really is. also, default to bourne in the
322 # pathological situation where a user doesn't have $ENV{SHELL} defined.
323 # note also that shells with funny names, like zoid, are assumed to be
324 # bourne.
325
326 my $shelltype = $class->guess_shelltype;
327
328 while (@envs) {
329 my ($name, $value) = (shift(@envs), shift(@envs));
330 $value =~ s/(\\")/\\$1/g if defined $value;
331 $out .= $class->${\"build_${shelltype}_env_declaration"}($name, $value);
332 }
333 return $out;
334}
335
336# simple routines that take two arguments: an %ENV key and a value. return
337# strings that are suitable for passing directly to the relevant shell to set
338# said key to said value.
339sub build_bourne_env_declaration {
340 my $class = shift;
341 my($name, $value) = @_;
342 return defined($value) ? qq{export ${name}="${value}";\n} : qq{unset ${name};\n};
343}
344
345sub build_csh_env_declaration {
346 my $class = shift;
347 my($name, $value) = @_;
348 return defined($value) ? qq{setenv ${name} "${value}"\n} : qq{unsetenv ${name}\n};
349}
350
351sub build_win32_env_declaration {
352 my $class = shift;
353 my($name, $value) = @_;
354 return defined($value) ? qq{set ${name}=${value}\n} : qq{set ${name}=\n};
355}
356
357
# spent 288µs (17+271) within local::lib::setup_env_hash_for which was called: # once (17µs+271µs) by local::lib::setup_local_lib_for at line 238
sub setup_env_hash_for {
3581600ns my ($class, $path, $deactivating) = @_;
35915µs1271µs my %envs = $class->build_environment_vars_for($path, $deactivating, INTERPOLATE_ENV);
# spent 271µs making 1 call to local::lib::build_environment_vars_for
360112µs @ENV{keys %envs} = values %envs;
361}
362
363
# spent 271µs (6+265) within local::lib::build_environment_vars_for which was called: # once (6µs+265µs) by local::lib::setup_env_hash_for at line 359
sub build_environment_vars_for {
3641500ns my ($class, $path, $deactivating, $interpolate) = @_;
365
3661500ns if ($deactivating == DEACTIVATE_ONE) {
367 return $class->build_deactivate_environment_vars_for($path, $interpolate);
368 } elsif ($deactivating == DEACTIVATE_ALL) {
369 return $class->build_deact_all_environment_vars_for($path, $interpolate);
370 } else {
37114µs1265µs return $class->build_activate_environment_vars_for($path, $interpolate);
# spent 265µs making 1 call to local::lib::build_activate_environment_vars_for
372 }
373}
374
375# Build an environment value for a variable like PATH from a list of paths.
376# References to existing variables are given as references to the variable name.
377# Duplicates are removed.
378#
379# options:
380# - interpolate: INTERPOLATE_ENV/LITERAL_ENV
381# - exists: paths are included only if they exist (default: interpolate == INTERPOLATE_ENV)
382# - filter: function to apply to each path do decide if it must be included
383# - empty: the value to return in the case of empty value
384my %ENV_LIST_VALUE_DEFAULTS = (
385 interpolate => INTERPOLATE_ENV,
386 exists => undef,
387919µs
# spent 9µs within local::lib::__ANON__[/usr/share/perl5/local/lib.pm:387] which was called 9 times, avg 978ns/call: # 9 times (9µs+0s) by local::lib::_env_list_value at line 401, avg 978ns/call
filter => sub { 1 },
38814µs empty => undef,
389);
390
# spent 190µs (168+23) within local::lib::_env_list_value which was called 3 times, avg 63µs/call: # 3 times (168µs+23µs) by local::lib::build_activate_environment_vars_for at line 421, avg 63µs/call
sub _env_list_value {
3913600ns my $options = shift;
392 die(sprintf "unknown option '$_' at %s line %u\n", (caller)[1..2])
393310µs for grep { !exists $ENV_LIST_VALUE_DEFAULTS{$_} } keys %$options;
39438µs my %options = (%ENV_LIST_VALUE_DEFAULTS, %{ $options });
39531µs $options{exists} = $options{interpolate} == INTERPOLATE_ENV
396 unless defined $options{exists};
397
3983300ns my %seen;
399
400 my $value = join($Config{path_sep}, map {
401968µs99µs ref $_ ? ($^O eq 'MSWin32' ? "%${$_}%" : "\$${$_}") : $_
# spent 9µs making 9 calls to local::lib::__ANON__[local/lib.pm:387], avg 978ns/call
402 } grep {
403 ref $_ || (defined $_
404 && length($_) > 0
405 && !$seen{$_}++
406 && $options{filter}->($_)
407 && (!$options{exists} || -e $_))
408 } map {
409932µs36µs if (ref $_ eq 'SCALAR' && $options{interpolate} == INTERPOLATE_ENV) {
# spent 6µs making 3 calls to Config::FETCH, avg 2µs/call
410316µs27µs defined $ENV{${$_}} ? (split /\Q$Config{path_sep}/, $ENV{${$_}}) : ()
# spent 6µs making 1 call to local::lib::CORE:regcomp # spent 2µs making 1 call to Config::FETCH
411 } else {
41231µs $_
413 }
414 } @_);
415324µs return length($value) ? $value : $options{empty};
416}
417
418
# spent 265µs (23+242) within local::lib::build_activate_environment_vars_for which was called: # once (23µs+242µs) by local::lib::build_environment_vars_for at line 371
sub build_activate_environment_vars_for {
4191400ns my ($class, $path, $interpolate) = @_;
420 return (
421116µs5242µs PERL_LOCAL_LIB_ROOT =>
# spent 190µs making 3 calls to local::lib::_env_list_value, avg 63µs/call # spent 30µs making 1 call to local::lib::install_base_perl_path # spent 22µs making 1 call to local::lib::install_base_bin_path
422 _env_list_value(
423 { interpolate => $interpolate, exists => 0, empty => '' },
424 \'PERL_LOCAL_LIB_ROOT',
425 $path,
426 ),
427 PERL_MB_OPT => "--install_base ${path}",
428 PERL_MM_OPT => "INSTALL_BASE=${path}",
429 PERL5LIB =>
430 _env_list_value(
431 { interpolate => $interpolate, exists => 0, empty => '' },
432 $class->install_base_perl_path($path),
433 \'PERL5LIB',
434 ),
435 PATH => _env_list_value(
436 { interpolate => $interpolate, exists => 0, empty => '' },
437 $class->install_base_bin_path($path),
438 \'PATH',
439 ),
440 )
441}
442
443
# spent 2µs within local::lib::active_paths which was called: # once (2µs+0s) by local::lib::setup_local_lib_for at line 210
sub active_paths {
4441300ns my ($class) = @_;
445
44614µs return () unless defined $ENV{PERL_LOCAL_LIB_ROOT};
447
448 return grep {
449 # screen out entries that aren't actually reflected in @INC
450 my $active_ll = $class->install_base_perl_path($_);
451 grep { $_ eq $active_ll } @INC
452 }
453 grep { $_ ne '' }
454 split /\Q$Config{path_sep}\E/, $ENV{PERL_LOCAL_LIB_ROOT};
455}
456
457sub build_deactivate_environment_vars_for {
458 my ($class, $path, $interpolate) = @_;
459
460 my @active_lls = $class->active_paths;
461
462 if (!grep { $_ eq $path } @active_lls) {
463 warn "Tried to deactivate inactive local::lib '$path'\n";
464 return ();
465 }
466
467 my $perl_path = $class->install_base_perl_path($path);
468 my $arch_path = $class->install_base_arch_path($path);
469 my $bin_path = $class->install_base_bin_path($path);
470
471
472 my %env = (
473 PERL_LOCAL_LIB_ROOT => _env_list_value(
474 {
475 exists => 0,
476 },
477 grep { $_ ne $path } @active_lls
478 ),
479 PERL5LIB => _env_list_value(
480 {
481 exists => 0,
482 filter => sub {
483 $_ ne $perl_path && $_ ne $arch_path
484 },
485 },
486 \'PERL5LIB',
487 ),
488 PATH => _env_list_value(
489 {
490 exists => 0,
491 filter => sub { $_ ne $bin_path },
492 },
493 \'PATH',
494 ),
495 );
496
497 # If removing ourselves from the "top of the stack", set install paths to
498 # correspond with the new top of stack.
499 if ($active_lls[-1] eq $path) {
500 my $new_top = $active_lls[-2];
501 $env{PERL_MB_OPT} = defined($new_top) ? "--install_base ${new_top}" : undef;
502 $env{PERL_MM_OPT} = defined($new_top) ? "INSTALL_BASE=${new_top}" : undef;
503 }
504
505 return %env;
506}
507
508sub build_deact_all_environment_vars_for {
509 my ($class, $path, $interpolate) = @_;
510
511 my @active_lls = $class->active_paths;
512
513 my %perl_paths = map { (
514 $class->install_base_perl_path($_) => 1,
515 $class->install_base_arch_path($_) => 1
516 ) } @active_lls;
517 my %bin_paths = map { (
518 $class->install_base_bin_path($_) => 1,
519 ) } @active_lls;
520
521 my %env = (
522 PERL_LOCAL_LIB_ROOT => undef,
523 PERL_MM_OPT => undef,
524 PERL_MB_OPT => undef,
525 PERL5LIB => _env_list_value(
526 {
527 exists => 0,
528 filter => sub {
529 ! scalar grep { exists $perl_paths{$_} } $_[0]
530 },
531 },
532 \'PERL5LIB'
533 ),
534 PATH => _env_list_value(
535 {
536 exists => 0,
537 filter => sub {
538 ! scalar grep { exists $bin_paths{$_} } $_[0]
539 },
540 },
541 \'PATH'
542 ),
543 );
544
545 return %env;
546}
547
548=begin testing
549
550#:: test classmethod
551
552File::Path::rmtree('t/var/splat');
553
554$c->ensure_dir_structure_for('t/var/splat');
555
556ok(-d 't/var/splat');
557
558=end testing
559
560=encoding utf8
561
562=head1 NAME
563
564local::lib - create and use a local lib/ for perl modules with PERL5LIB
565
566=head1 SYNOPSIS
567
568In code -
569
570 use local::lib; # sets up a local lib at ~/perl5
571
572 use local::lib '~/foo'; # same, but ~/foo
573
574 # Or...
575 use FindBin;
576 use local::lib "$FindBin::Bin/../support"; # app-local support library
577
578From the shell -
579
580 # Install LWP and its missing dependencies to the '~/perl5' directory
581 perl -MCPAN -Mlocal::lib -e 'CPAN::install(LWP)'
582
583 # Just print out useful shell commands
584 $ perl -Mlocal::lib
585 export PERL_MB_OPT='--install_base /home/username/perl5'
586 export PERL_MM_OPT='INSTALL_BASE=/home/username/perl5'
587 export PERL5LIB='/home/username/perl5/lib/perl5/i386-linux:/home/username/perl5/lib/perl5'
588 export PATH="/home/username/perl5/bin:$PATH"
589
590=head2 The bootstrapping technique
591
592A typical way to install local::lib is using what is known as the
593"bootstrapping" technique. You would do this if your system administrator
594hasn't already installed local::lib. In this case, you'll need to install
595local::lib in your home directory.
596
597Even if you do have administrative privileges, you will still want to set up your
598environment variables, as discussed in step 4. Without this, you would still
599install the modules into the system CPAN installation and also your Perl scripts
600will not use the lib/ path you bootstrapped with local::lib.
601
602By default local::lib installs itself and the CPAN modules into ~/perl5.
603
604Windows users must also see L</Differences when using this module under Win32>.
605
6061. Download and unpack the local::lib tarball from CPAN (search for "Download"
607on the CPAN page about local::lib). Do this as an ordinary user, not as root
608or administrator. Unpack the file in your home directory or in any other
609convenient location.
610
6112. Run this:
612
613 perl Makefile.PL --bootstrap
614
615If the system asks you whether it should automatically configure as much
616as possible, you would typically answer yes.
617
618In order to install local::lib into a directory other than the default, you need
619to specify the name of the directory when you call bootstrap, as follows:
620
621 perl Makefile.PL --bootstrap=~/foo
622
6233. Run this: (local::lib assumes you have make installed on your system)
624
625 make test && make install
626
6274. Now we need to setup the appropriate environment variables, so that Perl
628starts using our newly generated lib/ directory. If you are using bash or
629any other Bourne shells, you can add this to your shell startup script this
630way:
631
632 echo 'eval $(perl -I$HOME/perl5/lib/perl5 -Mlocal::lib)' >>~/.bashrc
633
634If you are using C shell, you can do this as follows:
635
636 /bin/csh
637 echo $SHELL
638 /bin/csh
639 perl -I$HOME/perl5/lib/perl5 -Mlocal::lib >> ~/.cshrc
640
641If you passed to bootstrap a directory other than default, you also need to give that as
642import parameter to the call of the local::lib module like this way:
643
644 echo 'eval $(perl -I$HOME/foo/lib/perl5 -Mlocal::lib=$HOME/foo)' >>~/.bashrc
645
646After writing your shell configuration file, be sure to re-read it to get the
647changed settings into your current shell's environment. Bourne shells use
648C<. ~/.bashrc> for this, whereas C shells use C<source ~/.cshrc>.
649
650If you're on a slower machine, or are operating under draconian disk space
651limitations, you can disable the automatic generation of manpages from POD when
652installing modules by using the C<--no-manpages> argument when bootstrapping:
653
654 perl Makefile.PL --bootstrap --no-manpages
655
656To avoid doing several bootstrap for several Perl module environments on the
657same account, for example if you use it for several different deployed
658applications independently, you can use one bootstrapped local::lib
659installation to install modules in different directories directly this way:
660
661 cd ~/mydir1
662 perl -Mlocal::lib=./
663 eval $(perl -Mlocal::lib=./) ### To set the environment for this shell alone
664 printenv ### You will see that ~/mydir1 is in the PERL5LIB
665 perl -MCPAN -e install ... ### whatever modules you want
666 cd ../mydir2
667 ... REPEAT ...
668
669If you are working with several C<local::lib> environments, you may want to
670remove some of them from the current environment without disturbing the others.
671You can deactivate one environment like this (using bourne sh):
672
673 eval $(perl -Mlocal::lib=--deactivate,~/path)
674
675which will generate and run the commands needed to remove C<~/path> from your
676various search paths. Whichever environment was B<activated most recently> will
677remain the target for module installations. That is, if you activate
678C<~/path_A> and then you activate C<~/path_B>, new modules you install will go
679in C<~/path_B>. If you deactivate C<~/path_B> then modules will be installed
680into C<~/pathA> -- but if you deactivate C<~/path_A> then they will still be
681installed in C<~/pathB> because pathB was activated later.
682
683You can also ask C<local::lib> to clean itself completely out of the current
684shell's environment with the C<--deactivate-all> option.
685For multiple environments for multiple apps you may need to include a modified
686version of the C<< use FindBin >> instructions in the "In code" sample above.
687If you did something like the above, you have a set of Perl modules at C<<
688~/mydir1/lib >>. If you have a script at C<< ~/mydir1/scripts/myscript.pl >>,
689you need to tell it where to find the modules you installed for it at C<<
690~/mydir1/lib >>.
691
692In C<< ~/mydir1/scripts/myscript.pl >>:
693
694 use strict;
695 use warnings;
696 use local::lib "$FindBin::Bin/.."; ### points to ~/mydir1 and local::lib finds lib
697 use lib "$FindBin::Bin/../lib"; ### points to ~/mydir1/lib
698
699Put this before any BEGIN { ... } blocks that require the modules you installed.
700
701=head2 Differences when using this module under Win32
702
703To set up the proper environment variables for your current session of
704C<CMD.exe>, you can use this:
705
706 C:\>perl -Mlocal::lib
707 set PERL_MB_OPT=--install_base C:\DOCUME~1\ADMINI~1\perl5
708 set PERL_MM_OPT=INSTALL_BASE=C:\DOCUME~1\ADMINI~1\perl5
709 set PERL5LIB=C:\DOCUME~1\ADMINI~1\perl5\lib\perl5;C:\DOCUME~1\ADMINI~1\perl5\lib\perl5\MSWin32-x86-multi-thread
710 set PATH=C:\DOCUME~1\ADMINI~1\perl5\bin;%PATH%
711
712 ### To set the environment for this shell alone
713 C:\>perl -Mlocal::lib > %TEMP%\tmp.bat && %TEMP%\tmp.bat && del %TEMP%\tmp.bat
714 ### instead of $(perl -Mlocal::lib=./)
715
716If you want the environment entries to persist, you'll need to add then to the
717Control Panel's System applet yourself or use L<App::local::lib::Win32Helper>.
718
719The "~" is translated to the user's profile directory (the directory named for
720the user under "Documents and Settings" (Windows XP or earlier) or "Users"
721(Windows Vista or later)) unless $ENV{HOME} exists. After that, the home
722directory is translated to a short name (which means the directory must exist)
723and the subdirectories are created.
724
725=head1 RATIONALE
726
727The version of a Perl package on your machine is not always the version you
728need. Obviously, the best thing to do would be to update to the version you
729need. However, you might be in a situation where you're prevented from doing
730this. Perhaps you don't have system administrator privileges; or perhaps you
731are using a package management system such as Debian, and nobody has yet gotten
732around to packaging up the version you need.
733
734local::lib solves this problem by allowing you to create your own directory of
735Perl packages downloaded from CPAN (in a multi-user system, this would typically
736be within your own home directory). The existing system Perl installation is
737not affected; you simply invoke Perl with special options so that Perl uses the
738packages in your own local package directory rather than the system packages.
739local::lib arranges things so that your locally installed version of the Perl
740packages takes precedence over the system installation.
741
742If you are using a package management system (such as Debian), you don't need to
743worry about Debian and CPAN stepping on each other's toes. Your local version
744of the packages will be written to an entirely separate directory from those
745installed by Debian.
746
747=head1 DESCRIPTION
748
749This module provides a quick, convenient way of bootstrapping a user-local Perl
750module library located within the user's home directory. It also constructs and
751prints out for the user the list of environment variables using the syntax
752appropriate for the user's current shell (as specified by the C<SHELL>
753environment variable), suitable for directly adding to one's shell
754configuration file.
755
756More generally, local::lib allows for the bootstrapping and usage of a
757directory containing Perl modules outside of Perl's C<@INC>. This makes it
758easier to ship an application with an app-specific copy of a Perl module, or
759collection of modules. Useful in cases like when an upstream maintainer hasn't
760applied a patch to a module of theirs that you need for your application.
761
762On import, local::lib sets the following environment variables to appropriate
763values:
764
765=over 4
766
767=item PERL_MB_OPT
768
769=item PERL_MM_OPT
770
771=item PERL5LIB
772
773=item PATH
774
775PATH is appended to, rather than clobbered.
776
777=back
778
779These values are then available for reference by any code after import.
780
781=head1 CREATING A SELF-CONTAINED SET OF MODULES
782
783See L<lib::core::only> for one way to do this - but note that
784there are a number of caveats, and the best approach is always to perform a
785build against a clean perl (i.e. site and vendor as close to empty as possible).
786
787=head1 OPTIONS
788
789Options are values that can be passed to the C<local::lib> import besides the
790directory to use. They are specified as C<use local::lib '--option'[, path];>
791or C<perl -Mlocal::lib=--option[,path]>.
792
793=head2 --deactivate
794
795Remove the chosen path (or the default path) from the module search paths if it
796was added by C<local::lib>, instead of adding it.
797
798=head2 --deactivate-all
799
800Remove all directories that were added to search paths by C<local::lib> from the
801search paths.
802
803=head1 METHODS
804
805=head2 ensure_dir_structure_for
806
807=over 4
808
809=item Arguments: $path
810
811=item Return value: None
812
813=back
814
815Attempts to create the given path, and all required parent directories. Throws
816an exception on failure.
817
818=head2 print_environment_vars_for
819
820=over 4
821
822=item Arguments: $path
823
824=item Return value: None
825
826=back
827
828Prints to standard output the variables listed above, properly set to use the
829given path as the base directory.
830
831=head2 build_environment_vars_for
832
833=over 4
834
835=item Arguments: $path, $interpolate
836
837=item Return value: \%environment_vars
838
839=back
840
841Returns a hash with the variables listed above, properly set to use the
842given path as the base directory.
843
844=head2 setup_env_hash_for
845
846=over 4
847
848=item Arguments: $path
849
850=item Return value: None
851
852=back
853
854Constructs the C<%ENV> keys for the given path, by calling
855L</build_environment_vars_for>.
856
857=head2 active_paths
858
859=over 4
860
861=item Arguments: None
862
863=item Return value: @paths
864
865=back
866
867Returns a list of active C<local::lib> paths, according to the
868C<PERL_LOCAL_LIB_ROOT> environment variable and verified against
869what is really in C<@INC>.
870
871=head2 install_base_perl_path
872
873=over 4
874
875=item Arguments: $path
876
877=item Return value: $install_base_perl_path
878
879=back
880
881Returns a path describing where to install the Perl modules for this local
882library installation. Appends the directories C<lib> and C<perl5> to the given
883path.
884
885=head2 install_base_arch_path
886
887=over 4
888
889=item Arguments: $path
890
891=item Return value: $install_base_arch_path
892
893=back
894
895Returns a path describing where to install the architecture-specific Perl
896modules for this local library installation. Based on the
897L</install_base_perl_path> method's return value, and appends the value of
898C<$Config{archname}>.
899
900=head2 install_base_bin_path
901
902=over 4
903
904=item Arguments: $path
905
906=item Return value: $install_base_bin_path
907
908=back
909
910Returns a path describing where to install the executable programs for this
911local library installation. Based on the L</install_base_perl_path> method's
912return value, and appends the directory C<bin>.
913
914=head2 resolve_empty_path
915
916=over 4
917
918=item Arguments: $path
919
920=item Return value: $base_path
921
922=back
923
924Builds and returns the base path into which to set up the local module
925installation. Defaults to C<~/perl5>.
926
927=head2 resolve_home_path
928
929=over 4
930
931=item Arguments: $path
932
933=item Return value: $home_path
934
935=back
936
937Attempts to find the user's home directory. If installed, uses C<File::HomeDir>
938for this purpose. If no definite answer is available, throws an exception.
939
940=head2 resolve_relative_path
941
942=over 4
943
944=item Arguments: $path
945
946=item Return value: $absolute_path
947
948=back
949
950Translates the given path into an absolute path.
951
952=head2 resolve_path
953
954=over 4
955
956=item Arguments: $path
957
958=item Return value: $absolute_path
959
960=back
961
962Calls the following in a pipeline, passing the result from the previous to the
963next, in an attempt to find where to configure the environment for a local
964library installation: L</resolve_empty_path>, L</resolve_home_path>,
965L</resolve_relative_path>. Passes the given path argument to
966L</resolve_empty_path> which then returns a result that is passed to
967L</resolve_home_path>, which then has its result passed to
968L</resolve_relative_path>. The result of this final call is returned from
969L</resolve_path>.
970
971=head1 A WARNING ABOUT UNINST=1
972
973Be careful about using local::lib in combination with "make install UNINST=1".
974The idea of this feature is that will uninstall an old version of a module
975before installing a new one. However it lacks a safety check that the old
976version and the new version will go in the same directory. Used in combination
977with local::lib, you can potentially delete a globally accessible version of a
978module while installing the new version in a local place. Only combine "make
979install UNINST=1" and local::lib if you understand these possible consequences.
980
981=head1 LIMITATIONS
982
983=over 4
984
985=item * The perl toolchain is unable to handle directory names with spaces in it,
986so you can't put your local::lib bootstrap into a directory with spaces. What
987you can do is moving your local::lib to a directory with spaces B<after> you
988installed all modules inside your local::lib bootstrap. But be aware that you
989can't update or install CPAN modules after the move.
990
991=item * Rather basic shell detection. Right now anything with csh in its name is
992assumed to be a C shell or something compatible, and everything else is assumed
993to be Bourne, except on Win32 systems. If the C<SHELL> environment variable is
994not set, a Bourne-compatible shell is assumed.
995
996=item * Bootstrap is a hack and will use CPAN.pm for ExtUtils::MakeMaker even if you
997have CPANPLUS installed.
998
999=item * Kills any existing PERL5LIB, PERL_MM_OPT or PERL_MB_OPT.
1000
1001=item * Should probably auto-fixup CPAN config if not already done.
1002
1003=back
1004
1005Patches very much welcome for any of the above.
1006
1007=over 4
1008
1009=item * On Win32 systems, does not have a way to write the created environment variables
1010to the registry, so that they can persist through a reboot.
1011
1012=back
1013
1014=head1 TROUBLESHOOTING
1015
1016If you've configured local::lib to install CPAN modules somewhere in to your
1017home directory, and at some point later you try to install a module with C<cpan
1018-i Foo::Bar>, but it fails with an error like: C<Warning: You do not have
1019permissions to install into /usr/lib64/perl5/site_perl/5.8.8/x86_64-linux at
1020/usr/lib64/perl5/5.8.8/Foo/Bar.pm> and buried within the install log is an
1021error saying C<'INSTALL_BASE' is not a known MakeMaker parameter name>, then
1022you've somehow lost your updated ExtUtils::MakeMaker module.
1023
1024To remedy this situation, rerun the bootstrapping procedure documented above.
1025
1026Then, run C<rm -r ~/.cpan/build/Foo-Bar*>
1027
1028Finally, re-run C<cpan -i Foo::Bar> and it should install without problems.
1029
1030=head1 ENVIRONMENT
1031
1032=over 4
1033
1034=item SHELL
1035
1036=item COMSPEC
1037
1038local::lib looks at the user's C<SHELL> environment variable when printing out
1039commands to add to the shell configuration file.
1040
1041On Win32 systems, C<COMSPEC> is also examined.
1042
1043=back
1044
1045=head1 SEE ALSO
1046
1047=over 4
1048
1049=item * L<Perl Advent article, 2011|http://perladvent.org/2011/2011-12-01.html>
1050
1051=back
1052
1053=head1 SUPPORT
1054
1055IRC:
1056
1057 Join #local-lib on irc.perl.org.
1058
1059=head1 AUTHOR
1060
1061Matt S Trout <mst@shadowcat.co.uk> http://www.shadowcat.co.uk/
1062
1063auto_install fixes kindly sponsored by http://www.takkle.com/
1064
1065=head1 CONTRIBUTORS
1066
1067Patches to correctly output commands for csh style shells, as well as some
1068documentation additions, contributed by Christopher Nehren <apeiron@cpan.org>.
1069
1070Doc patches for a custom local::lib directory, more cleanups in the english
1071documentation and a L<german documentation|POD2::DE::local::lib> contributed by Torsten Raudssus
1072<torsten@raudssus.de>.
1073
1074Hans Dieter Pearcey <hdp@cpan.org> sent in some additional tests for ensuring
1075things will install properly, submitted a fix for the bug causing problems with
1076writing Makefiles during bootstrapping, contributed an example program, and
1077submitted yet another fix to ensure that local::lib can install and bootstrap
1078properly. Many, many thanks!
1079
1080pattern of Freenode IRC contributed the beginnings of the Troubleshooting
1081section. Many thanks!
1082
1083Patch to add Win32 support contributed by Curtis Jewell <csjewell@cpan.org>.
1084
1085Warnings for missing PATH/PERL5LIB (as when not running interactively) silenced
1086by a patch from Marco Emilio Poleggi.
1087
1088Mark Stosberg <mark@summersault.com> provided the code for the now deleted
1089'--self-contained' option.
1090
1091Documentation patches to make win32 usage clearer by
1092David Mertens <dcmertens.perl@gmail.com> (run4flat).
1093
1094Brazilian L<portuguese translation|POD2::PT_BR::local::lib> and minor doc patches contributed by Breno
1095G. de Oliveira <garu@cpan.org>.
1096
1097Improvements to stacking multiple local::lib dirs and removing them from the
1098environment later on contributed by Andrew Rodland <arodland@cpan.org>.
1099
1100Patch for Carp version mismatch contributed by Hakim Cassimally <osfameron@cpan.org>.
1101
1102=head1 COPYRIGHT
1103
1104Copyright (c) 2007 - 2010 the local::lib L</AUTHOR> and L</CONTRIBUTORS> as
1105listed above.
1106
1107=head1 LICENSE
1108
1109This is free software; you can redistribute it and/or modify it under
1110the same terms as the Perl 5 programming language system itself.
1111
1112=cut
1113
111415µs1;
 
# spent 10µs within local::lib::CORE:ftdir which was called: # once (10µs+0s) by local::lib::ensure_dir_structure_for at line 268
sub local::lib::CORE:ftdir; # opcode
# spent 11µs within local::lib::CORE:match which was called 15 times, avg 753ns/call: # 11 times (9µs+0s) by local::lib::import at line 74, avg 827ns/call # 3 times (2µs+0s) by local::lib::import at line 34, avg 633ns/call # once (300ns+0s) by local::lib::resolve_home_path at line 155
sub local::lib::CORE:match; # opcode
# spent 11µs within local::lib::CORE:regcomp which was called 2 times, avg 5µs/call: # once (6µs+0s) by local::lib::_env_list_value at line 410 # once (5µs+0s) by local::lib::setup_local_lib_for at line 243
sub local::lib::CORE:regcomp; # opcode
Report produced by the NYTProf 5.06 Perl profiler, developed by Tim Bunce and Adam Kaplan.