Integrate change #9501 from maintperl into mainline.

fix the perlembed notes on multiple interpreters

fix ExtUtils::Embed to work passably on Windows

p4raw-link: @9501 on //depot/maint-5.6/perl: fa102aa9a975aaa2a384e09b6377476f565fdcc2

p4raw-id: //depot/perl@9502
p4raw-integrated: from //depot/maint-5.6/perl@9500 'copy in'
	pod/perlembed.pod (@8627..) 'merge in' lib/ExtUtils/Embed.pm
	(@8153..)

2 files changed, 54 insertions, 37 deletions

diff --git a/lib/ExtUtils/Embed.pm b/lib/ExtUtils/Embed.pm
index b5a1bae5f6..cbdd2bba04 100644
--- a/lib/ExtUtils/Embed.pm
+++ b/lib/ExtUtils/Embed.pm
@@ -6,6 +6,7 @@ require Exporter;
 require FileHandle;
 use Config;
 use Getopt::Std;
+use File::Spec;
 
 #Only when we need them
 #require ExtUtils::MakeMaker;
@@ -86,33 +87,8 @@ sub xsinit {
 
 sub xsi_header {
     return <<EOF;
-#if defined(__cplusplus) && !defined(PERL_OBJECT)
-#define is_cplusplus
-#endif
-
-#ifdef is_cplusplus
-extern "C" {
-#endif
-
 #include <EXTERN.h>
 #include <perl.h>
-#ifdef PERL_OBJECT
-#define NO_XSLOCKS
-#include <XSUB.h>
-#include "win32iop.h"
-#include <fcntl.h>
-#include <perlhost.h>
-#endif
-#ifdef is_cplusplus
-}
-#  ifndef EXTERN_C
-#    define EXTERN_C extern "C"
-#  endif
-#else
-#  ifndef EXTERN_C
-#    define EXTERN_C extern
-#  endif
-#endif
 
 EOF
 }    
@@ -190,10 +166,14 @@ sub ldopts {
        }
     }
     $std = 1 unless scalar @link_args;
-    @path = $path ? split(/:/, $path) : @INC;
+    my $sep = $Config{path_sep} || ':';
+    @path = $path ? split(/\Q$sep/, $path) : @INC;
 
     push(@potential_libs, @link_args)    if scalar @link_args;
-    push(@potential_libs, $Config{perllibs}) if defined $std;
+    # makemaker includes std libs on windows by default
+    if ($^O ne 'MSWin32' and defined($std)) {
+	push(@potential_libs, $Config{perllibs});
+    }
 
     push(@mods, static_ext()) if $std;
 
@@ -223,12 +203,18 @@ sub ldopts {
     }
     #print STDERR "\@potential_libs = @potential_libs\n";
 
-    my $libperl = (grep(/^-l\w*perl\w*$/, @link_args))[0] || "-lperl";
+    my $libperl;
+    if ($^O eq 'MSWin32') {
+	$libperl = $Config{libperl};
+    }
+    else {
+	$libperl = (grep(/^-l\w*perl\w*$/, @link_args))[0] || "-lperl";
+    }
 
+    my $lpath = File::Spec->catdir($Config{archlibexp}, 'CORE');
+    $lpath = qq["$lpath"] if $^O eq 'MSWin32';
     my($extralibs, $bsloadlibs, $ldloadlibs, $ld_run_path) =
-	$MM->ext(join ' ', 
-		 $MM->catdir("-L$Config{archlibexp}", "CORE"), " $libperl", 
-		 @potential_libs);
+	$MM->ext(join ' ', "-L$lpath", $libperl, @potential_libs);
 
     my $ld_or_bs = $bsloadlibs || $ldloadlibs;
     print STDERR "bs: $bsloadlibs ** ld: $ldloadlibs" if $Verbose;
@@ -248,7 +234,9 @@ sub ccdlflags {
 }
 
 sub perl_inc {
-    my_return(" -I$Config{archlibexp}/CORE ");
+    my $dir = File::Spec->catdir($Config{archlibexp}, 'CORE');
+    $dir = qq["$dir"] if $^O eq 'MSWin32';
+    my_return(" -I$dir ");
 }
 
 sub ccopts {
@@ -277,6 +265,7 @@ ExtUtils::Embed - Utilities for embedding Perl in C/C++ applications
 
 
  perl -MExtUtils::Embed -e xsinit 
+ perl -MExtUtils::Embed -e ccopts 
  perl -MExtUtils::Embed -e ldopts 
 
 =head1 DESCRIPTION
diff --git a/pod/perlembed.pod b/pod/perlembed.pod
index 57d1bdbc0e..ecbe1f6706 100644
--- a/pod/perlembed.pod
+++ b/pod/perlembed.pod
@@ -815,9 +815,11 @@ during a session.  Such an application might sporadically decide to
 release any resources associated with the interpreter.
 
 The program must take care to ensure that this takes place I<before>
-the next interpreter is constructed.  By default, the global variable
+the next interpreter is constructed.  By default, when perl is not
+built with any special options, the global variable
 C<PL_perl_destruct_level> is set to C<0>, since extra cleaning isn't
-needed when a program has only one interpreter.
+usually needed when a program only ever creates a single interpreter
+in its entire lifetime.
 
 Setting C<PL_perl_destruct_level> to C<1> makes everything squeaky clean:
 
@@ -839,9 +841,16 @@ When I<perl_destruct()> is called, the interpreter's syntax parse tree
 and symbol tables are cleaned up, and global variables are reset.
 
 Now suppose we have more than one interpreter instance running at the
-same time.  This is feasible, but only if you used the
-C<-DMULTIPLICITY> flag when building Perl.  By default, that sets
-C<PL_perl_destruct_level> to C<1>.
+same time.  This is feasible, but only if you used the Configure option
+C<-Dusemultiplicity> or the options C<-Dusethreads -Duseithreads> when
+building Perl.  By default, enabling one of these Configure options
+sets the per-interpreter global variable C<PL_perl_destruct_level> to
+C<1>, so that thorough cleaning is automatic.
+
+Using C<-Dusethreads -Duseithreads> rather than C<-Dusemultiplicity>
+is more appropriate if you intend to run multiple interpreters
+concurrently in different threads, because it enables support for
+linking in the thread libraries of your system with the interpreter.
 
 Let's give it a try:
 
@@ -862,22 +871,41 @@ Let's give it a try:
      char *one_args[] = { "one_perl", SAY_HELLO };
      char *two_args[] = { "two_perl", SAY_HELLO };
 
+     PERL_SET_CONTEXT(one_perl);
      perl_construct(one_perl);
+     PERL_SET_CONTEXT(two_perl);
      perl_construct(two_perl);
 
+     PERL_SET_CONTEXT(one_perl);
      perl_parse(one_perl, NULL, 3, one_args, (char **)NULL);
+     PERL_SET_CONTEXT(two_perl);
      perl_parse(two_perl, NULL, 3, two_args, (char **)NULL);
 
+     PERL_SET_CONTEXT(one_perl);
      perl_run(one_perl);
+     PERL_SET_CONTEXT(two_perl);
      perl_run(two_perl);
 
+     PERL_SET_CONTEXT(one_perl);
      perl_destruct(one_perl);
+     PERL_SET_CONTEXT(two_perl);
      perl_destruct(two_perl);
 
+     PERL_SET_CONTEXT(one_perl);
      perl_free(one_perl);
+     PERL_SET_CONTEXT(two_perl);
      perl_free(two_perl);
  }
 
+Note the calls to PERL_SET_CONTEXT().  These are necessary to initialize
+the global state that tracks which interpreter is the "current" one on
+the particular process or thread that may be running it.  It should
+always be used if you have more than one interpreter and are making
+perl API calls on both interpreters in an interleaved fashion.
+
+PERL_SET_CONTEXT(interp) should also be called whenever C<interp> is
+used by a thread that did not create it (using either perl_alloc(), or
+the more esoteric perl_clone()).
 
 Compile as usual: