07 May 2021 10:32:28 UTC
- Distribution: Win32-ErrorMode
- Source (raw)
- Browse (raw)
- How to Contribute
- Issues (0)
- Testers (1 / 0 / 0)
- KwaliteeBus factor: 1
- % Coverage
- License: perl_5
- Perl: v5.8.0
- Activity24 month
- Download (129.67KB)
- MetaCPAN Explorer
- Subscribe to distribution
- This version
- Latest version
- SEE ALSO
include/ppport.h - Perl/Pollution/Portability version 3.62
perl include/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 include/ppport.h --list-provided list provided API --list-unsupported list API that isn't supported all the way back --api-info=name show Perl API portability information
This version of include/ppport.h is designed to support operation with Perl installations back to 5.003_07, and has been tested up to 5.33.1.
Display a brief usage summary.
Display the version of include/ppport.h.
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. 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.
--copyare given, the default is to simply print the diffs for each file. This requires either
diffprogram to be installed.
Manually set the diff program and options to use. The default is to use
Text::Diff, when installed, and output unified context diffs.
Tell include/ppport.h to check for compatibility with the given Perl version. The default is to check for compatibility with Perl version 5.003_07. You can use this option to reduce the output of include/ppport.h if you intend to be backward compatible only down to a certain Perl version.
Usually, include/ppport.h will detect C++ style comments and replace them with C style comments for portability reasons. Using this option instructs include/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. Warnings will still be displayed.
Don't suggest any changes. Only give diagnostic output and hints unless these are also deactivated.
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 all script and documentation functionality from include/ppport.h. This reduces the size of include/ppport.h dramatically and may be useful if you want to include include/ppport.h in smaller modules without increasing their distribution size too much.
The stripped include/ppport.h will have a
--unstripoption that allows you to undo the stripping, but only if an appropriate
Devel::PPPortmodule is installed.
Lists the API elements for which compatibility is provided by include/ppport.h. Also lists if it must be explicitly requested, if it has dependencies, and if there are hints or warnings for it.
Lists the API elements that are known not to be FULLY supported by include/ppport.h, and below which version of Perl they probably won't be available or work. By FULLY, we mean that support isn't provided all the way back to the first version of Perl that include/ppport.h supports at all.
Show portability information for elements matching name. If name is surrounded by slashes, it is interpreted as a regular expression.
Normally, only API elements are shown, but if there are no matching API elements but there are some other matching elements, those are shown. This allows you to conveniently find when functions internal to the core implementation were added; only people working on the core are likely to find this last part useful.
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 include/ppport.h --list-provided
to see which API elements are provided by include/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 include/ppport.h will provide wrappers for older Perl versions.
Although the purpose of include/ppport.h is to keep you from having to concern yourself with what version you are running under, there may arise instances where you have to do so. These macros, the same ones as in base Perl, are available to you in all versions, and are what you should use:
PERL_VERSION_xx(major, minor, patch)
Returns whether or not the perl currently being compiled has the specified relationship xx to the perl given by the parameters. xx is one of
#if PERL_VERSION_GT(5,24,2) code that will only be compiled on perls after v5.24.2 #else fallback code #endif
Note that this is usable in making compile-time decisions
You may use the special value '*' for the final number to mean ALL possible values for it. Thus,
means all perls in the 5.31 series. And
means all perls EXCEPT 5.24 ones. And
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 include/ppport.h.
These functions or variables will be marked
explicitin the list shown by
Depending on whether you module has a single or multiple files that use such functions or variables, you want either
staticor global variants.
staticfunction 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 ----------------------------------------------------------------------------------------- caller_cx() NEED_caller_cx NEED_caller_cx_GLOBAL ck_warner() NEED_ck_warner NEED_ck_warner_GLOBAL ck_warner_d() NEED_ck_warner_d NEED_ck_warner_d_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 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 my_strnlen() NEED_my_strnlen NEED_my_strnlen_GLOBAL newCONSTSUB() NEED_newCONSTSUB NEED_newCONSTSUB_GLOBAL newSVpvn_share() NEED_newSVpvn_share NEED_newSVpvn_share_GLOBAL PL_parser NEED_PL_parser NEED_PL_parser_GLOBAL PL_signals NEED_PL_signals NEED_PL_signals_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_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 sv_unmagicext() NEED_sv_unmagicext NEED_sv_unmagicext_GLOBAL utf8_to_uvchr_buf() NEED_utf8_to_uvchr_buf NEED_utf8_to_uvchr_buf_GLOBAL vload_module() NEED_vload_module NEED_vload_module_GLOBAL vmess() NEED_vmess NEED_vmess_GLOBAL warner() NEED_warner NEED_warner_GLOBAL
To avoid namespace conflicts, you can change the namespace of the explicitly exported functions / variables using the
#definethe macro before including
#define DPPP_NAMESPACE MyOwnNamespace_ #include "include/ppport.h"
The default namespace is
The good thing is that most of the above can be checked by running include/ppport.h on your source code. See the next section for details.
To verify whether include/ppport.h is needed for your module, whether you should make any changes to your code, and whether any special defines should be used, include/ppport.h can be run as a Perl script to check your source code. Simply say:
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 include/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 include/ppport.h --nochanges
You can specify a different
diffprogram or options, using the
perl include/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 include/ppport.h --copy=.new
To display portability information for the
perl include/ppport.h --api-info=newSVpvn
Since the argument to
--api-infocan be a regular expression, you can use
perl include/ppport.h --api-info=/_nomg$/
to display portability information for all
perl include/ppport.h --api-info=/./
to display information for all known API elements.
Some of the suggested edits and/or generated patches may not compile as-is without tweaking manually. This is generally due to the need for an extra parameter to be added to the call to prevent buffer overflow.
If this version of include/ppport.h is causing failure during the compilation of this module, please check if newer versions of either this module or
Devel::PPPortare available on CPAN before sending a bug report.
If include/ppport.h was generated using the latest version of
Devel::PPPortand is causing failure of this module, please file a bug report at https://github.com/Dual-Life/Devel-PPPort/issues
Please include the following information:
The complete output from running "perl -V"
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::PPPortmodule from CPAN.
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.
Module Install Instructions
To install Win32::ErrorMode, copy and paste the appropriate command in to your terminal.
perl -MCPAN -e shell install Win32::ErrorMode
For more information on module installation, please visit the detailed CPAN module installation guide.