1 ################################################################################
5 ## $Date: 2008/01/04 10:47:42 +0100 $
7 ################################################################################
9 ## Version 3.x, Copyright (C) 2004-2008, 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 ################################################################################
34 ppport.h - Perl/Pollution/Portability version __VERSION__
38 perl ppport.h [options] [source files]
40 Searches current directory for files if no [source files] are given
42 --help show short help
44 --version show version
46 --patch=file write one patch file with changes
47 --copy=suffix write changed copies with suffix
48 --diff=program use diff program and options
50 --compat-version=version provide compatibility with Perl version
51 --cplusplus accept C++ comments
53 --quiet don't output anything except fatal errors
54 --nodiag don't show diagnostics
55 --nohints don't show hints
56 --nochanges don't suggest changes
57 --nofilter don't filter input files
59 --strip strip all script and doc functionality from
62 --list-provided list provided API
63 --list-unsupported list unsupported API
64 --api-info=name show Perl API portability information
68 This version of F<ppport.h> is designed to support operation with Perl
69 installations back to __MIN_PERL__, and has been tested up to __MAX_PERL__.
75 Display a brief usage summary.
79 Display the version of F<ppport.h>.
81 =head2 --patch=I<file>
83 If this option is given, a single patch file will be created if
84 any changes are suggested. This requires a working diff program
85 to be installed on your system.
87 =head2 --copy=I<suffix>
89 If this option is given, a copy of each file will be saved with
90 the given suffix that contains the suggested changes. This does
91 not require any external programs. Note that this does not
92 automagially add a dot between the original filename and the
93 suffix. If you want the dot, you have to include it in the option
96 If neither C<--patch> or C<--copy> are given, the default is to
97 simply print the diffs for each file. This requires either
98 C<Text::Diff> or a C<diff> program to be installed.
100 =head2 --diff=I<program>
102 Manually set the diff program and options to use. The default
103 is to use C<Text::Diff>, when installed, and output unified
106 =head2 --compat-version=I<version>
108 Tell F<ppport.h> to check for compatibility with the given
109 Perl version. The default is to check for compatibility with Perl
110 version __MIN_PERL__. You can use this option to reduce the output
111 of F<ppport.h> if you intend to be backward compatible only
112 down to a certain Perl version.
116 Usually, F<ppport.h> will detect C++ style comments and
117 replace them with C style comments for portability reasons.
118 Using this option instructs F<ppport.h> to leave C++
123 Be quiet. Don't print anything except fatal errors.
127 Don't output any diagnostic messages. Only portability
128 alerts will be printed.
132 Don't output any hints. Hints often contain useful portability
133 notes. Warnings will still be displayed.
137 Don't suggest any changes. Only give diagnostic output and hints
138 unless these are also deactivated.
142 Don't filter the list of input files. By default, files not looking
143 like source code (i.e. not *.xs, *.c, *.cc, *.cpp or *.h) are skipped.
147 Strip all script and documentation functionality from F<ppport.h>.
148 This reduces the size of F<ppport.h> dramatically and may be useful
149 if you want to include F<ppport.h> in smaller modules without
150 increasing their distribution size too much.
152 The stripped F<ppport.h> will have a C<--unstrip> option that allows
153 you to undo the stripping, but only if an appropriate C<Devel::PPPort>
156 =head2 --list-provided
158 Lists the API elements for which compatibility is provided by
159 F<ppport.h>. Also lists if it must be explicitly requested,
160 if it has dependencies, and if there are hints or warnings for it.
162 =head2 --list-unsupported
164 Lists the API elements that are known not to be supported by
165 F<ppport.h> and below which version of Perl they probably
166 won't be available or work.
168 =head2 --api-info=I<name>
170 Show portability information for API elements matching I<name>.
171 If I<name> is surrounded by slashes, it is interpreted as a regular
176 In order for a Perl extension (XS) module to be as portable as possible
177 across differing versions of Perl itself, certain steps need to be taken.
183 Including this header is the first major one. This alone will give you
184 access to a large part of the Perl API that hasn't been available in
185 earlier Perl releases. Use
187 perl ppport.h --list-provided
189 to see which API elements are provided by ppport.h.
193 You should avoid using deprecated parts of the API. For example, using
194 global Perl variables without the C<PL_> prefix is deprecated. Also,
195 some API functions used to have a C<perl_> prefix. Using this form is
196 also deprecated. You can safely use the supported API, as F<ppport.h>
197 will provide wrappers for older Perl versions.
201 If you use one of a few functions or variables that were not present in
202 earlier versions of Perl, and that can't be provided using a macro, you
203 have to explicitly request support for these functions by adding one or
204 more C<#define>s in your source code before the inclusion of F<ppport.h>.
206 These functions or variables will be marked C<explicit> in the list shown
207 by C<--list-provided>.
209 Depending on whether you module has a single or multiple files that
210 use such functions or variables, you want either C<static> or global
213 For a C<static> function or variable (used only in a single source
216 #define NEED_function
217 #define NEED_variable
219 For a global function or variable (used in multiple source files),
222 #define NEED_function_GLOBAL
223 #define NEED_variable_GLOBAL
225 Note that you mustn't have more than one global request for the
226 same function or variable in your project.
230 To avoid namespace conflicts, you can change the namespace of the
231 explicitly exported functions / variables using the C<DPPP_NAMESPACE>
232 macro. Just C<#define> the macro before including C<ppport.h>:
234 #define DPPP_NAMESPACE MyOwnNamespace_
237 The default namespace is C<DPPP_>.
241 The good thing is that most of the above can be checked by running
242 F<ppport.h> on your source code. See the next section for
247 To verify whether F<ppport.h> is needed for your module, whether you
248 should make any changes to your code, and whether any special defines
249 should be used, F<ppport.h> can be run as a Perl script to check your
250 source code. Simply say:
254 The result will usually be a list of patches suggesting changes
255 that should at least be acceptable, if not necessarily the most
256 efficient solution, or a fix for all possible problems.
258 If you know that your XS module uses features only available in
259 newer Perl releases, if you're aware that it uses C++ comments,
260 and if you want all suggestions as a single patch file, you could
261 use something like this:
263 perl ppport.h --compat-version=5.6.0 --cplusplus --patch=test.diff
265 If you only want your code to be scanned without any suggestions
268 perl ppport.h --nochanges
270 You can specify a different C<diff> program or options, using
271 the C<--diff> option:
273 perl ppport.h --diff='diff -C 10'
275 This would output context diffs with 10 lines of context.
277 If you want to create patched copies of your files instead, use:
279 perl ppport.h --copy=.new
281 To display portability information for the C<newSVpvn> function,
284 perl ppport.h --api-info=newSVpvn
286 Since the argument to C<--api-info> can be a regular expression,
289 perl ppport.h --api-info=/_nomg$/
291 to display portability information for all C<_nomg> functions or
293 perl ppport.h --api-info=/./
295 to display information for all known API elements.
299 If this version of F<ppport.h> is causing failure during
300 the compilation of this module, please check if newer versions
301 of either this module or C<Devel::PPPort> are available on CPAN
302 before sending a bug report.
304 If F<ppport.h> was generated using the latest version of
305 C<Devel::PPPort> and is causing failure of this module, please
306 file a bug report using the CPAN Request Tracker at L<http://rt.cpan.org/>.
308 Please include the following information:
314 The complete output from running "perl -V"
322 The name and version of the module you were trying to build.
326 A full log of the build that failed.
330 Any other information that you think could be relevant.
334 For the latest version of this code, please get the C<Devel::PPPort>
339 Version 3.x, Copyright (c) 2004-2008, Marcus Holland-Moritz.
341 Version 2.x, Copyright (C) 2001, Paul Marquess.
343 Version 1.x, Copyright (C) 1999, Kenneth Albanowski.
345 This program is free software; you can redistribute it and/or
346 modify it under the same terms as Perl itself.
350 See L<Devel::PPPort>.