ppport.h - Perl/Pollution/Portability version 3.03
perl ppport.h [options] [files] --help show short help --patch=file write one patch file with changes --copy=suffix write changed copies with suffix --diff=program use diff program and options --compat-version=version provide compatibility with Perl version --cplusplus accept C++ comments --quiet don't output anything except fatal errors --nodiag don't show diagnostics --nohints don't show hints --nochanges don't suggest changes --list-provided list provided API --list-unsupported list unsupported API
This version of ppport.h is designed to support operation with Perl installations back to 5.003, and has been tested up to 5.9.2.
Display a brief usage summary.
If this option is given, a single patch file will be created if any changes are suggested. This requires a working diff program to be installed on your system.
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.
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.
--patch
--copy
Text::Diff
diff
Manually set the diff program and options to use. The default is to use Text::Diff, when installed, and output unified context diffs.
Tell ppport.h to check for compatibility with the given Perl version. The default is to check for compatibility with Perl version 5.003. You can use this option to reduce the output of ppport.h if you intend to be backward compatible only up to a certain Perl version.
Usually, ppport.h will detect C++ style comments and replace them with C style comments for portability reasons. Using this option instructs ppport.h to leave C++ comments untouched.
Be quiet. Don't print anything except fatal errors.
Don't output any diagnostic messages. Only portability alerts will be printed.
Don't output any hints. Hints often contain useful portability notes.
Don't suggest any changes. Only give diagnostic output and hints unless these are also deactivated.
Lists the API elements for which compatibility is provided by ppport.h. Also lists if it must be explicitly requested, if it has dependencies, and if there are hints for it.
Lists the API elements that are known not to be supported by ppport.h and below which version of Perl they probably won't be available or work.
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.
PL_
perl_
If you use one of a few functions 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.
#define
These functions will be marked explicit in the list shown by --list-provided.
explicit
--list-provided
Depending on whether you module has a single or multiple files that use such functions, you want either static or global variants.
static
For a static function, use:
#define NEED_function
For a global function, use:
#define NEED_function_GLOBAL
Note that you mustn't have more than one global request for one function in your project.
Function Static Request Global Request ----------------------------------------------------------------------------------------- eval_pv() NEED_eval_pv NEED_eval_pv_GLOBAL grok_bin() NEED_grok_bin NEED_grok_bin_GLOBAL grok_hex() NEED_grok_hex NEED_grok_hex_GLOBAL grok_number() NEED_grok_number NEED_grok_number_GLOBAL grok_numeric_radix() NEED_grok_numeric_radix NEED_grok_numeric_radix_GLOBAL grok_oct() NEED_grok_oct NEED_grok_oct_GLOBAL newCONSTSUB() NEED_newCONSTSUB NEED_newCONSTSUB_GLOBAL newRV_noinc() NEED_newRV_noinc NEED_newRV_noinc_GLOBAL sv_2pv_nolen() NEED_sv_2pv_nolen NEED_sv_2pv_nolen_GLOBAL sv_2pvbyte() NEED_sv_2pvbyte NEED_sv_2pvbyte_GLOBAL sv_catpvf_mg() NEED_sv_catpvf_mg NEED_sv_catpvf_mg_GLOBAL sv_catpvf_mg_nocontext() NEED_sv_catpvf_mg_nocontext NEED_sv_catpvf_mg_nocontext_GLOBAL sv_setpvf_mg() NEED_sv_setpvf_mg NEED_sv_setpvf_mg_GLOBAL sv_setpvf_mg_nocontext() NEED_sv_setpvf_mg_nocontext NEED_sv_setpvf_mg_nocontext_GLOBAL vnewSVpvf() NEED_vnewSVpvf NEED_vnewSVpvf_GLOBAL
To avoid namespace conflicts, you can change the namespace of the explicitly exported functions using the DPPP_NAMESPACE macro. Just #define the macro before including ppport.h:
DPPP_NAMESPACE
ppport.h
#define DPPP_NAMESPACE MyOwnNamespace_ #include "ppport.h"
The default namespace is DPPP_.
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:
--diff
perl ppport.h --diff='diff -C 10'
This would output context diffs with 10 lines of context.
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.
Devel::PPPort
If ppport.h was generated using the latest version of Devel::PPPort and is causing failure of this module, please file a bug report using the CPAN Request Tracker at http://rt.cpan.org/.
Please include the following information:
The complete output from running "perl -V"
This file.
The name and version of the module you were trying to build.
A full log of the build that failed.
Any other information that you think could be relevant.
For the latest version of this code, please get the Devel::PPPort module from CPAN.
Version 3.x, Copyright (c) 2004, Marcus Holland-Moritz.
Version 2.x, Copyright (C) 2001, Paul Marquess.
Version 1.x, Copyright (C) 1999, Kenneth Albanowski.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
See Devel::PPPort.
To install CMS::MediaWiki, copy and paste the appropriate command in to your terminal.
cpanm
cpanm CMS::MediaWiki
CPAN shell
perl -MCPAN -e shell install CMS::MediaWiki
For more information on module installation, please visit the detailed CPAN module installation guide.