Document the INCLUDE_COMMAND XS directive

ExtUtils::ParseXS has recognized the INCLUDE_COMMAND directive as a
smarter replacement for "INCLUDE: perl -e ... |" since version 2.21_01.

diff --git a/pod/perlxs.pod b/pod/perlxs.pod
index 5f773bb..afff655 100644 (file)
--- a/pod/perlxs.pod
+++ b/pod/perlxs.pod
@@ -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