=provides

=implementation

=pod

=head1 NAME

ppport.h - Perl/Pollution/Portability version __VERSION__

=head1 SYNOPSIS

  perl ppport.h [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

=head1 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__.

=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 --changed=I<suffix>

If this option is given, for each file a copy with the given
suffix will be saved that contains the suggested changes. This
does not require any external programs.

If neither C<--patch> or C<--changed> 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 to use.

=head2 --quiet

Be quiet.

=head2 --nodiag

Don't output any diagnostic messages.

=head2 --nohints

Don't output any hints. Hints often contain useful portability
notes.

=head1 DESCRIPTION

In order for a Perl extension 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, then using dTHX is all
the appropriate places and using a PL_ prefix to refer to global Perl
variables is the second.

If you use one of a few functions that were not present in earlier
versions of Perl, please add a define before the inclusion of ppport.h
for a static include, or use the GLOBAL request in a single module to
produce a global definition that can be referenced from the other
modules.

  Function:            Static define:           Extern define:
  newCONSTSUB()        NEED_newCONSTSUB         NEED_newCONSTSUB_GLOBAL

=head1 EXAMPLES

To verify whether ppport.h is needed for your module, and whether any
special defines should be used, ppport.h can be run through Perl to check
your source code. Simply say:

  perl -x ppport.h *.c *.h *.xs foo/bar*.c [etc]

The result will 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. It won't catch where dTHR is needed, and
doesn't attempt to account for global macro or function definitions,
nested includes, typemaps, etc.

In order to test for the need of dTHR, please try your module under a
recent version of Perl that has threading compiled-in.

=head1 BUGS

If this version of ppport.h is failing during the compilation of this
module, please check if a newer version of Devel::PPPort is available
on CPAN before sending a bug report.

If you are using the latest version of Devel::PPPort and it is failing
during compilation 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 3

=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 retrieve the 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>.

