1 ################################################################################
5 ## $Date: 2005/02/27 21:13:25 +0100 $
7 ################################################################################
9 ## Version 3.x, Copyright (C) 2004-2005, Marcus Holland-Moritz.
10 ## Version 2.x, Copyright (C) 2001, Paul Marquess.
11 ## Version 1.x, Copyright (C) 1999, Kenneth Albanowski.
13 ## This program is free software; you can redistribute it and/or
14 ## modify it under the same terms as Perl itself.
16 ################################################################################
32 ppport.h - Perl/Pollution/Portability version __VERSION__
36 perl ppport.h [options] [source files]
38 Searches current directory for files if no [source files] are given
40 --help show short help
42 --patch=file write one patch file with changes
43 --copy=suffix write changed copies with suffix
44 --diff=program use diff program and options
46 --compat-version=version provide compatibility with Perl version
47 --cplusplus accept C++ comments
49 --quiet don't output anything except fatal errors
50 --nodiag don't show diagnostics
51 --nohints don't show hints
52 --nochanges don't suggest changes
53 --nofilter don't filter input files
55 --list-provided list provided API
56 --list-unsupported list unsupported API
57 --api-info=name show Perl API portability information
61 This version of F<ppport.h> is designed to support operation with Perl
62 installations back to __MIN_PERL__, and has been tested up to __MAX_PERL__.
68 Display a brief usage summary.
70 =head2 --patch=I<file>
72 If this option is given, a single patch file will be created if
73 any changes are suggested. This requires a working diff program
74 to be installed on your system.
76 =head2 --copy=I<suffix>
78 If this option is given, a copy of each file will be saved with
79 the given suffix that contains the suggested changes. This does
80 not require any external programs.
82 If neither C<--patch> or C<--copy> are given, the default is to
83 simply print the diffs for each file. This requires either
84 C<Text::Diff> or a C<diff> program to be installed.
86 =head2 --diff=I<program>
88 Manually set the diff program and options to use. The default
89 is to use C<Text::Diff>, when installed, and output unified
92 =head2 --compat-version=I<version>
94 Tell F<ppport.h> to check for compatibility with the given
95 Perl version. The default is to check for compatibility with Perl
96 version __MIN_PERL__. You can use this option to reduce the output
97 of F<ppport.h> if you intend to be backward compatible only
98 up to a certain Perl version.
102 Usually, F<ppport.h> will detect C++ style comments and
103 replace them with C style comments for portability reasons.
104 Using this option instructs F<ppport.h> to leave C++
109 Be quiet. Don't print anything except fatal errors.
113 Don't output any diagnostic messages. Only portability
114 alerts will be printed.
118 Don't output any hints. Hints often contain useful portability
123 Don't suggest any changes. Only give diagnostic output and hints
124 unless these are also deactivated.
128 Don't filter the list of input files. By default, files not looking
129 like source code (i.e. not *.xs, *.c, *.cc, *.cpp or *.h) are skipped.
131 =head2 --list-provided
133 Lists the API elements for which compatibility is provided by
134 F<ppport.h>. Also lists if it must be explicitly requested,
135 if it has dependencies, and if there are hints for it.
137 =head2 --list-unsupported
139 Lists the API elements that are known not to be supported by
140 F<ppport.h> and below which version of Perl they probably
141 won't be available or work.
143 =head2 --api-info=I<name>
145 Show portability information for API elements matching I<name>.
146 If I<name> is surrounded by slashes, it is interpreted as a regular
151 In order for a Perl extension (XS) module to be as portable as possible
152 across differing versions of Perl itself, certain steps need to be taken.
158 Including this header is the first major one. This alone will give you
159 access to a large part of the Perl API that hasn't been available in
160 earlier Perl releases. Use
162 perl ppport.h --list-provided
164 to see which API elements are provided by ppport.h.
168 You should avoid using deprecated parts of the API. For example, using
169 global Perl variables without the C<PL_> prefix is deprecated. Also,
170 some API functions used to have a C<perl_> prefix. Using this form is
171 also deprecated. You can safely use the supported API, as F<ppport.h>
172 will provide wrappers for older Perl versions.
176 If you use one of a few functions that were not present in earlier
177 versions of Perl, and that can't be provided using a macro, you have
178 to explicitly request support for these functions by adding one or
179 more C<#define>s in your source code before the inclusion of F<ppport.h>.
181 These functions will be marked C<explicit> in the list shown by
184 Depending on whether you module has a single or multiple files that
185 use such functions, you want either C<static> or global variants.
187 For a C<static> function, use:
189 #define NEED_function
191 For a global function, use:
193 #define NEED_function_GLOBAL
195 Note that you mustn't have more than one global request for one
196 function in your project.
200 To avoid namespace conflicts, you can change the namespace of the
201 explicitly exported functions using the C<DPPP_NAMESPACE> macro.
202 Just C<#define> the macro before including C<ppport.h>:
204 #define DPPP_NAMESPACE MyOwnNamespace_
207 The default namespace is C<DPPP_>.
211 The good thing is that most of the above can be checked by running
212 F<ppport.h> on your source code. See the next section for
217 To verify whether F<ppport.h> is needed for your module, whether you
218 should make any changes to your code, and whether any special defines
219 should be used, F<ppport.h> can be run as a Perl script to check your
220 source code. Simply say:
224 The result will usually be a list of patches suggesting changes
225 that should at least be acceptable, if not necessarily the most
226 efficient solution, or a fix for all possible problems.
228 If you know that your XS module uses features only available in
229 newer Perl releases, if you're aware that it uses C++ comments,
230 and if you want all suggestions as a single patch file, you could
231 use something like this:
233 perl ppport.h --compat-version=5.6.0 --cplusplus --patch=test.diff
235 If you only want your code to be scanned without any suggestions
238 perl ppport.h --nochanges
240 You can specify a different C<diff> program or options, using
241 the C<--diff> option:
243 perl ppport.h --diff='diff -C 10'
245 This would output context diffs with 10 lines of context.
247 To display portability information for the C<newSVpvn> function,
250 perl ppport.h --api-info=newSVpvn
252 Since the argument to C<--api-info> can be a regular expression,
255 perl ppport.h --api-info=/_nomg$/
257 to display portability information for all C<_nomg> functions or
259 perl ppport.h --api-info=/./
261 to display information for all known API elements.
265 If this version of F<ppport.h> is causing failure during
266 the compilation of this module, please check if newer versions
267 of either this module or C<Devel::PPPort> are available on CPAN
268 before sending a bug report.
270 If F<ppport.h> was generated using the latest version of
271 C<Devel::PPPort> and is causing failure of this module, please
272 file a bug report using the CPAN Request Tracker at L<http://rt.cpan.org/>.
274 Please include the following information:
280 The complete output from running "perl -V"
288 The name and version of the module you were trying to build.
292 A full log of the build that failed.
296 Any other information that you think could be relevant.
300 For the latest version of this code, please get the C<Devel::PPPort>
305 Version 3.x, Copyright (c) 2004-2005, Marcus Holland-Moritz.
307 Version 2.x, Copyright (C) 2001, Paul Marquess.
309 Version 1.x, Copyright (C) 1999, Kenneth Albanowski.
311 This program is free software; you can redistribute it and/or
312 modify it under the same terms as Perl itself.
316 See L<Devel::PPPort>.