Marcus Holland-Moritz > Devel-PPPort-3.20 > ppport.h

Download:
Devel-PPPort-3.20.tar.gz

Annotate this POD

CPAN RT

New  1
Open  1
Stalled  5
View/Report Bugs
Source   Latest Release: Devel-PPPort-3.25

NEED_function NEED_function_GLOBAL NEED_variable NEED_variable_GLOBAL DPPP_NAMESPACE

NAME ^

ppport.h - Perl/Pollution/Portability version __VERSION__

SYNOPSIS ^

  perl ppport.h [options] [source files]

  Searches current directory for files if no [source files] are given

  --help                      show short help

  --version                   show version

  --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
  --nofilter                  don't filter input files

  --strip                     strip all script and doc functionality from
                              ppport.h

  --list-provided             list provided API
  --list-unsupported          list unsupported API
  --api-info=name             show Perl API portability information

COMPATIBILITY ^

This version of ppport.h is designed to support operation with Perl installations back to __MIN_PERL__, and has been tested up to __MAX_PERL__.

OPTIONS ^

--help

Display a brief usage summary.

--version

Display the version of ppport.h.

--patch=file

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.

--copy=suffix

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 automagially 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.

--diff=program

Manually set the diff program and options to use. The default is to use Text::Diff, when installed, and output unified context diffs.

--compat-version=version

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.

--cplusplus

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.

--quiet

Be quiet. Don't print anything except fatal errors.

--nodiag

Don't output any diagnostic messages. Only portability alerts will be printed.

--nohints

Don't output any hints. Hints often contain useful portability notes. Warnings will still be displayed.

--nochanges

Don't suggest any changes. Only give diagnostic output and hints unless these are also deactivated.

--nofilter

Don't filter the list of input files. By default, files not looking like source code (i.e. not *.xs, *.c, *.cc, *.cpp or *.h) are skipped.

--strip

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.

--list-provided

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 or warnings for it.

--list-unsupported

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.

--api-info=name

Show portability information for API elements matching name. If name is surrounded by slashes, it is interpreted as a regular expression.

DESCRIPTION ^

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.

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.

EXAMPLES ^

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

    perl ppport.h --api-info=/_nomg$/

to display portability information for all _nomg functions or

    perl ppport.h --api-info=/./

to display information for all known API elements.

BUGS ^

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.

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:

  1. The complete output from running "perl -V"
  2. This file.
  3. The name and version of the module you were trying to build.
  4. A full log of the build that failed.
  5. Any other information that you think could be relevant.

For the latest version of this code, please get the Devel::PPPort module from CPAN.

COPYRIGHT ^

Version 3.x, Copyright (c) 2004-2010, 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 ALSO ^

See Devel::PPPort.

syntax highlighting: