=provides
=dontwarn
NEED_function
NEED_function_GLOBAL
=implementation
=pod
=head1 NAME
__PPPORT_NAME__ - Perl/Pollution/Portability version __VERSION__
=head1 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
--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
=head1 COMPATIBILITY
This version of F<__PPPORT_NAME__> is designed to support operation with Perl
installations back to __MIN_PERL__, and has been tested up to __MAX_PERL__.
=head1 OPTIONS
=head2 --help
Display a brief usage summary.
=head2 --patch=I<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.
=head2 --copy=I<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 C<--patch> or C<--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.
=head2 --diff=I<program>
Manually set the diff program and options to use.
=head2 --cplusplus
Usually, F<__PPPORT_NAME__> will detect C++ style comments and
replace them with C style comments for portability reasons.
Using this option instructs F<__PPPORT_NAME__> to leave C++
comments untouched.
=head2 --quiet
Be quiet. Don't print anything except fatal errors.
=head2 --nodiag
Don't output any diagnostic messages. Only portability
alerts will be printed.
=head2 --nohints
Don't output any hints. Hints often contain useful portability
notes.
=head2 --nochanges
Don't suggest any changes. Only give diagnostic output and hints
unless these are also deactivated.
=head2 --list-provided
Lists the API elements for which compatibility is provided by
F<__PPPORT_NAME__>. Also lists if it must be explicitly requested,
if it has dependencies, and if there are hints for it.
=head2 --list-unsupported
Lists the API elements that are known not to be supported by
F<__PPPORT_NAME__> and below which version of Perl they probably
won't be available or work.
=head1 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.
=over 4
=item *
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__.
=item *
You should avoid using deprecated parts of the API. For example, using
global Perl variables without the C<PL_> prefix is deprecated. Also,
some API functions used to have a C<perl_> prefix. Using this form is
also deprecated. You can safely use the supported API, as F<__PPPORT_NAME__>
will provide wrappers for older Perl versions.
=item *
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 C<#define>s in your source code before the inclusion of F<__PPPORT_NAME__>.
These functions will be marked C<explicit> in the list shown by
C<--list-provided>.
Depending on whether you module has a single or multiple files that
use such functions, you want either C<static> or global variants.
For a C<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__
To avoid namespace conflicts, you can change the namespace of the
explicitly exported functions using the C<DPPP_NAMESPACE> macro.
Just C<#define> the macro before including C<__PPPORT_NAME__>:
#define DPPP_NAMESPACE MyOwnNamespace_
#include "__PPPORT_NAME__"
The default namespace is C<DPPP_>.
=back
The good thing is that most of the above can be checked by running
F<__PPPORT_NAME__> on your source code. See the next section for
details.
=head1 EXAMPLES
To verify whether F<__PPPORT_NAME__> is needed for your module,
whether you should make any changes to your code, and whether any
special defines should be used, F<__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.
=head1 BUGS
If this version of F<__PPPORT_NAME__> is causing failure during
the compilation of this module, please check if newer versions
of either this module or C<Devel::PPPort> are available on CPAN
before sending a bug report.
If F<__PPPORT_NAME__> was generated using the latest version of
C<Devel::PPPort> and is causing failure of this module, please
file a bug report using the CPAN Request Tracker at L<http://rt.cpan.org/>.
Please include the following information:
=over 4
=item 1.
The complete output from running "perl -V"
=item 2.
This file.
=item 3.
The name and version of the module you were trying to build.
=item 4.
A full log of the build that failed.
=item 5.
Any other information that you think could be relevant.
=back
For the latest version of this code, please get the C<Devel::PPPort>
module from CPAN.
=head1 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.
=head1 SEE ALSO
See L<Devel::PPPort>.