Document the INCLUDE_COMMAND XS directive
authorSteffen Mueller <smueller@cpan.org>
Sun, 18 Apr 2010 14:39:29 +0000 (16:39 +0200)
committerSteffen Mueller <smueller@cpan.org>
Tue, 20 Apr 2010 20:45:46 +0000 (22:45 +0200)
ExtUtils::ParseXS has recognized the INCLUDE_COMMAND directive as a
smarter replacement for "INCLUDE: perl -e ... |" since version 2.21_01.

pod/perlxs.pod

index 5f773bb..afff655 100644 (file)
@@ -1434,10 +1434,26 @@ The XS module can use INCLUDE: to pull that file into it.
     INCLUDE: Rpcb1.xsh
 
 If the parameters to the INCLUDE: keyword are followed by a pipe (C<|>) then
-the compiler will interpret the parameters as a command.
+the compiler will interpret the parameters as a command. This feature is
+mildly deprecated in favour of the C<INCLUDE_COMMAND:> directive, as documented
+below.
 
     INCLUDE: cat Rpcb1.xsh |
 
+Do not use this to run perl: C<INCLUDE: perl |> will run the perl that
+happens to be the first in your path and not necessarily the same perl that is
+used to run C<xsubpp>. See L<"The INCLUDE_COMMAND: Keyword">.
+
+=head2 The INCLUDE_COMMAND: Keyword
+
+Runs the supplied command and includes its output into the current XS
+document. C<INCLUDE_COMMAND> assigns special meaning to the C<$^X> token
+in that it runs the same perl interpreter that is running C<xsubpp>:
+
+    INCLUDE_COMMAND: cat Rpcb1.xsh
+
+    INCLUDE_COMMAND: $^X -e ...
+
 =head2 The CASE: Keyword
 
 The CASE: keyword allows an XSUB to have multiple distinct parts with each