If this option is given, a copy of each file will be saved with the given suffix that contains the suggested changes. This does not require any external programs. Note that this does not automagically add a dot between the original filename and the suffix. If you want the dot, you have to include it in the option argument.

If neither --patch or --copy are given, the default is to simply print the diffs for each file. This requires either Text::Diff or a diff program to be installed.

Tell ppport.h to check for compatibility with the given Perl version. The default is to check for compatibility with Perl version __MIN_PERL__. You can use this option to reduce the output of ppport.h if you intend to be backward compatible only down to a certain Perl version.

Strip all script and documentation functionality from ppport.h. This reduces the size of ppport.h dramatically and may be useful if you want to include ppport.h in smaller modules without increasing their distribution size too much.

The stripped ppport.h will have a --unstrip option that allows you to undo the stripping, but only if an appropriate Devel::PPPort module is installed.

In order for a Perl extension (XS) module to be as portable as possible across differing versions of Perl itself, certain steps need to be taken.

Including this header is the first major one. This alone will give you access to a large part of the Perl API that hasn't been available in earlier Perl releases. Use

perl ppport.h --list-provided

to see which API elements are provided by ppport.h.

You should avoid using deprecated parts of the API. For example, using global Perl variables without the PL_ prefix is deprecated. Also, some API functions used to have a perl_ prefix. Using this form is also deprecated. You can safely use the supported API, as ppport.h will provide wrappers for older Perl versions.

If you use one of a few functions or variables that were not present in earlier versions of Perl, and that can't be provided using a macro, you have to explicitly request support for these functions by adding one or more #defines in your source code before the inclusion of ppport.h.

These functions or variables will be marked explicit in the list shown by --list-provided.

Depending on whether you module has a single or multiple files that use such functions or variables, you want either static or global variants.

For a static function or variable (used only in a single source file), use:

#define NEED_function
#define NEED_variable

For a global function or variable (used in multiple source files), use:

#define NEED_function_GLOBAL
#define NEED_variable_GLOBAL

Note that you mustn't have more than one global request for the same function or variable in your project.

__EXPLICIT_API__

To avoid namespace conflicts, you can change the namespace of the explicitly exported functions / variables using the DPPP_NAMESPACE macro. Just #define the macro before including ppport.h:

#define DPPP_NAMESPACE MyOwnNamespace_
#include "ppport.h"

The default namespace is DPPP_.

The good thing is that most of the above can be checked by running ppport.h on your source code. See the next section for details.

To verify whether ppport.h is needed for your module, whether you should make any changes to your code, and whether any special defines should be used, ppport.h can be run as a Perl script to check your source code. Simply say:

perl ppport.h

The result will usually be a list of patches suggesting changes that should at least be acceptable, if not necessarily the most efficient solution, or a fix for all possible problems.

If you know that your XS module uses features only available in newer Perl releases, if you're aware that it uses C++ comments, and if you want all suggestions as a single patch file, you could use something like this:

perl ppport.h --compat-version=5.6.0 --cplusplus --patch=test.diff

If you only want your code to be scanned without any suggestions for changes, use:

perl ppport.h --nochanges

You can specify a different diff program or options, using the --diff option:

perl ppport.h --diff='diff -C 10'

This would output context diffs with 10 lines of context.

If you want to create patched copies of your files instead, use:

perl ppport.h --copy=.new

To display portability information for the newSVpvn function, use:

perl ppport.h --api-info=newSVpvn

Since the argument to --api-info can be a regular expression, you can use

If this version of ppport.h is causing failure during the compilation of this module, please check if newer versions of either this module or Devel::PPPort are available on CPAN before sending a bug report.