4 # And Gandalf said: 'Many folk like to know beforehand what is to
5 # be set on the table; but those who have laboured to prepare the
6 # feast like to keep their secret; for wonder makes the words of
10 # Quote from Tolkien sugested by Anno Siegel.
12 # Read ext/DynaLoader/README and DynaLoader.doc for
13 # detailed information.
15 # Tim.Bunce@ig.co.uk, August 1994
24 # enable messages from DynaLoader perl code
25 $dl_debug = 0 unless $dl_debug;
26 $dl_debug = $ENV{'PERL_DL_DEBUG'} if $ENV{'PERL_DL_DEBUG'};
28 $dl_so = $dl_dlext = ""; # avoid typo warnings
29 $dl_so = $Config{'so'}; # suffix for shared libraries
30 $dl_dlext = $Config{'dlext'}; # suffix for dynamic modules
32 # Some systems need special handling to expand file specifications
33 # (VMS support by Charles Bailey <bailey@HMIVAX.HUMGEN.UPENN.EDU>)
34 # See dl_expandspec() for more details. Should be harmless but
35 # inefficient to define on systems that don't need it.
36 $do_expand = ($Config{'osname'} eq 'VMS');
38 @dl_require_symbols = (); # names of symbols we need
39 @dl_resolve_using = (); # names of files to link with
40 @dl_library_path = (); # path to look for files
42 # This is a fix to support DLD's unfortunate desire to relink -lc
43 @dl_resolve_using = dl_findfile('-lc') if $Config{'dlsrc'} eq "dl_dld.xs";
45 # Initialise @dl_library_path with the 'standard' library path
46 # for this platform as determined by Configure
47 push(@dl_library_path, split(' ',$Config{'libpth'}));
49 # Add to @dl_library_path any extra directories we can gather from
50 # environment variables. So far LD_LIBRARY_PATH is the only known
51 # variable used for this purpose. Others may be added later.
52 push(@dl_library_path, split(/:/, $ENV{'LD_LIBRARY_PATH'}))
53 if $ENV{'LD_LIBRARY_PATH'};
56 # No prizes for guessing why we don't say 'bootstrap DynaLoader;' here.
57 &boot_DynaLoader if defined &boot_DynaLoader;
59 print STDERR "DynaLoader.pm loaded (@dl_library_path)\n"
62 # Temporary interface checks for recent changes (Aug 1994)
63 if (defined(&dl_load_file)){
64 die "dl_error not defined" unless defined (&dl_error);
65 die "dl_undef_symbols not defined" unless defined (&dl_undef_symbols);
71 # The bootstrap function cannot be autoloaded (without complications)
72 # so we define it here:
75 # use local vars to enable $module.bs script to edit values
77 local($module) = $args[0];
80 croak "Usage: DynaLoader::bootstrap(module)"
83 croak "Can't load module $module, dynamic loading not available in this perl"
84 unless defined(&dl_load_file);
86 print STDERR "DynaLoader::bootstrap($module)\n" if $dl_debug;
88 my(@modparts) = split(/::/,$module);
89 my($modfname) = $modparts[-1];
90 my($modpname) = join('/',@modparts);
92 my $dir = "$_/auto/$modpname";
93 next unless -d $dir; # skip over uninteresting directories
95 # check for common cases to avoid autoload of dl_findfile
96 last if ($file=_check_file("$dir/$modfname.$dl_dlext"));
98 # no luck here, save dir for possible later dl_findfile search
99 push(@dirs, "-L$dir");
101 # last resort, let dl_findfile have a go in all known locations
102 $file = dl_findfile(@dirs, map("-L$_",@INC), $modfname) unless $file;
104 croak "Can't find loadable object for module $module in \@INC"
107 my($bootname) = "boot_$module";
108 $bootname =~ s/\W/_/g;
109 @dl_require_symbols = ($bootname);
111 # Execute optional '.bootstrap' perl script for this module.
112 # The .bs file can be used to configure @dl_resolve_using etc to
113 # match the needs of the individual module on this architecture.
115 $bs =~ s/(\.\w+)?$/\.bs/; # look for .bs 'beside' the library
116 if (-s $bs) { # only read file if it's not empty
117 local($osname, $dlsrc) = @Config{'osname','dlsrc'};
118 print STDERR "BS: $bs ($osname, $dlsrc)\n" if $dl_debug;
120 warn "$bs: $@\n" if $@;
123 my $libref = DynaLoader::dl_load_file($file) or
124 croak "Can't load '$file' for module $module: ".&dl_error."\n";
126 my(@unresolved) = dl_undef_symbols();
127 carp "Undefined symbols present after loading $file: @unresolved\n"
130 my $boot_symbol_ref = dl_find_symbol($libref, $bootname) or
131 croak "Can't find '$bootname' symbol in $file\n";
133 dl_install_xsub("${module}::bootstrap", $boot_symbol_ref, $file);
134 &{"${module}::bootstrap"}(@args);
138 sub _check_file{ # private utility to handle dl_expandspec vs -f tests
140 return $file if (!$do_expand && -f $file); # the common case
141 return $file if ( $do_expand && ($file=dl_expandspec($file)));
146 # Let autosplit and the autoloader deal with these functions:
151 # Read ext/DynaLoader/DynaLoader.doc for detailed information.
152 # This function does not automatically consider the architecture
153 # or the perl library auto directories.
155 my (@dirs, $dir); # which directories to search
156 my (@found); # full paths to real files we have found
157 my ($vms) = ($Config{'osname'} eq 'VMS');
159 print STDERR "dl_findfile(@args)\n" if $dl_debug;
161 # accumulate directories but process files as they appear
162 arg: foreach(@args) {
163 # Special fast case: full filepath requires no search
164 if (m:/: && -f $_ && !$do_expand){
166 last arg unless wantarray;
170 # Deal with directories first:
171 # Using a -L prefix is the preferred option (faster and more robust)
172 if (m:^-L:){ s/^-L//; push(@dirs, $_); next; }
173 # Otherwise we try to try to spot directories by a heuristic
174 # (this is a more complicated issue than it first appears)
175 if (m:/: && -d $_){ push(@dirs, $_); next; }
176 # VMS: we may be using native VMS directry syntax instead of
177 # Unix emulation, so check this as well
178 if ($vms && /[:>\]]/ && -d $_){ push(@dirs, $_); next; }
180 # Only files should get this far...
181 my(@names, $name); # what filenames to look for
182 if (m:-l: ){ # convert -lname to appropriate library name
184 push(@names,"lib$_.$dl_so");
185 push(@names,"lib$_.a");
186 }else{ # Umm, a bare name. Try various alternatives:
187 # these should be ordered with the most likely first
188 push(@names,"$_.$dl_so") unless m/\.$dl_so$/o;
189 push(@names,"lib$_.$dl_so") unless m:/:;
190 push(@names,"$_.o") unless m/\.(o|$dl_so)$/o;
191 push(@names,"$_.a") unless m/\.a$/;
194 foreach $dir (@dirs, @dl_library_path) {
196 foreach $name (@names) {
197 my($file) = "$dir/$name";
198 print STDERR " checking in $dir for $name\n" if $dl_debug;
199 $file = _check_file($file);
202 next arg; # no need to look any further
209 print STDERR " dl_findfile ignored non-existent directory: $_\n" unless -d $_;
211 print STDERR "dl_findfile found: @found\n";
213 return $found[0] unless wantarray;
220 # Optional function invoked if DynaLoader.pm sets $do_expand.
221 # Most systems do not require or use this function.
222 # Some systems may implement it in the dl_*.xs file in which case
223 # this autoload version will not be called but is harmless.
225 # This function is designed to deal with systems which treat some
226 # 'filenames' in a special way. For example VMS 'Logical Names'
227 # (something like unix environment variables - but different).
228 # This function should recognise such names and expand them into
230 # Must return undef if $spec is invalid or file does not exist.
232 my($file) = $spec; # default output to input
233 my($osname) = $Config{'osname'};
235 if ($osname eq 'VMS'){ # dl_expandspec should be defined in dl_vms.xs
236 croak "dl_expandspec: should be defined in XS file!\n";
238 return undef unless -f $file;
240 print STDERR "dl_expandspec($spec) => $file\n" if $dl_debug;