The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Devel-PPPort-2.99_02
River stage four • 73 direct dependents • 1301 total dependents
/ __PPPORT_NAME__

NEED_function NEED_function_GLOBAL

NAME

__PPPORT_NAME__ - Perl/Pollution/Portability version __VERSION__

SYNOPSIS

  perl __PPPORT_NAME__ [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

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

COMPATIBILITY

This version of __PPPORT_NAME__ 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.

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

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 to use.

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

--nochanges

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

--list-provided

Lists the API elements for which compatibility is provided by __PPPORT_NAME__. Also lists if it must be explicitly requested, if it has dependencies, and if there are hints for it.

--list-unsupported

Lists the API elements that are known not to be supported by __PPPORT_NAME__ and below which version of Perl they probably won't be available or work.

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.

  • 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_NAME__ --list-provided

    to see which API elements are provided by __PPPORT_NAME__.

  • 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_NAME__ will provide wrappers for older Perl versions.

  • 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_NAME__.

    These functions 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, you want either static or global variants.

    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.

        __EXPLICIT_API__

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

EXAMPLES

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

    perl __PPPORT_NAME__

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.

BUGS

If this version of __PPPORT_NAME__ 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_NAME__ 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, 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.

3 POD Errors

The following errors were encountered while parsing the POD:

Around line 1:

Unknown directive: =provides

Around line 3:

Unknown directive: =dontwarn

Around line 8:

Unknown directive: =implementation