NAME

lib/File/ppport.h - Perl/Pollution/Portability version 3.42

SYNOPSIS

  perl lib/File/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 lib/File/ppport.h

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

COMPATIBILITY

This version of lib/File/ppport.h is designed to support operation with Perl installations back to 5.003, and has been tested up to 5.20.

OPTIONS

--help

Display a brief usage summary.

--version

Display the version of lib/File/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 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.

--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 lib/File/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 lib/File/ppport.h if you intend to be backward compatible only down to a certain Perl version.

--cplusplus

Usually, lib/File/ppport.h will detect C++ style comments and replace them with C style comments for portability reasons. Using this option instructs lib/File/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 lib/File/ppport.h. This reduces the size of lib/File/ppport.h dramatically and may be useful if you want to include lib/File/ppport.h in smaller modules without increasing their distribution size too much.

The stripped lib/File/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 lib/File/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 lib/File/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.

  • 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 lib/File/ppport.h --list-provided

    to see which API elements are provided by lib/File/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 lib/File/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 lib/File/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.

        Function / Variable       Static Request               Global Request
        -----------------------------------------------------------------------------------------
        PL_parser                 NEED_PL_parser               NEED_PL_parser_GLOBAL
        PL_signals                NEED_PL_signals              NEED_PL_signals_GLOBAL
        SvRX()                    NEED_SvRX                    NEED_SvRX_GLOBAL
        caller_cx()               NEED_caller_cx               NEED_caller_cx_GLOBAL
        croak_xs_usage()          NEED_croak_xs_usage          NEED_croak_xs_usage_GLOBAL
        die_sv()                  NEED_die_sv                  NEED_die_sv_GLOBAL
        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
        gv_fetchpvn_flags()       NEED_gv_fetchpvn_flags       NEED_gv_fetchpvn_flags_GLOBAL
        load_module()             NEED_load_module             NEED_load_module_GLOBAL
        mess()                    NEED_mess                    NEED_mess_GLOBAL
        mess_nocontext()          NEED_mess_nocontext          NEED_mess_nocontext_GLOBAL
        mess_sv()                 NEED_mess_sv                 NEED_mess_sv_GLOBAL
        mg_findext()              NEED_mg_findext              NEED_mg_findext_GLOBAL
        my_snprintf()             NEED_my_snprintf             NEED_my_snprintf_GLOBAL
        my_sprintf()              NEED_my_sprintf              NEED_my_sprintf_GLOBAL
        my_strlcat()              NEED_my_strlcat              NEED_my_strlcat_GLOBAL
        my_strlcpy()              NEED_my_strlcpy              NEED_my_strlcpy_GLOBAL
        newCONSTSUB()             NEED_newCONSTSUB             NEED_newCONSTSUB_GLOBAL
        newRV_noinc()             NEED_newRV_noinc             NEED_newRV_noinc_GLOBAL
        newSV_type()              NEED_newSV_type              NEED_newSV_type_GLOBAL
        newSVpvn_flags()          NEED_newSVpvn_flags          NEED_newSVpvn_flags_GLOBAL
        newSVpvn_share()          NEED_newSVpvn_share          NEED_newSVpvn_share_GLOBAL
        pv_display()              NEED_pv_display              NEED_pv_display_GLOBAL
        pv_escape()               NEED_pv_escape               NEED_pv_escape_GLOBAL
        pv_pretty()               NEED_pv_pretty               NEED_pv_pretty_GLOBAL
        sv_2pv_flags()            NEED_sv_2pv_flags            NEED_sv_2pv_flags_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_pvn_force_flags()      NEED_sv_pvn_force_flags      NEED_sv_pvn_force_flags_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
        sv_unmagicext()           NEED_sv_unmagicext           NEED_sv_unmagicext_GLOBAL
        vload_module()            NEED_vload_module            NEED_vload_module_GLOBAL
        vmess()                   NEED_vmess                   NEED_vmess_GLOBAL
        vnewSVpvf()               NEED_vnewSVpvf               NEED_vnewSVpvf_GLOBAL
        warner()                  NEED_warner                  NEED_warner_GLOBAL

    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 lib/File/ppport.h:

        #define DPPP_NAMESPACE MyOwnNamespace_
        #include "lib/File/ppport.h"

    The default namespace is DPPP_.

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

EXAMPLES

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

    perl lib/File/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 lib/File/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 lib/File/ppport.h --nochanges

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

    perl lib/File/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 lib/File/ppport.h --copy=.new

To display portability information for the newSVpvn function, use:

    perl lib/File/ppport.h --api-info=newSVpvn

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

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

to display portability information for all _nomg functions or

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

to display information for all known API elements.

BUGS

If this version of lib/File/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 lib/File/ppport.h was generated using the latest version of Devel::PPPort and is causing failure of this module, please send a bug report to perlbug@perl.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-2013, 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.