This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
parts/inc/ppphdoc: Add caution to pod
[perl5.git] / dist / Devel-PPPort / parts / inc / ppphdoc
1 ################################################################################
2 ##
3 ##  Version 3.x, Copyright (C) 2004-2013, Marcus Holland-Moritz.
4 ##  Version 2.x, Copyright (C) 2001, Paul Marquess.
5 ##  Version 1.x, Copyright (C) 1999, Kenneth Albanowski.
6 ##
7 ##  This program is free software; you can redistribute it and/or
8 ##  modify it under the same terms as Perl itself.
9 ##
10 ################################################################################
11
12 =provides
13
14 =dontwarn
15
16 NEED_function
17 NEED_function_GLOBAL
18 NEED_variable
19 NEED_variable_GLOBAL
20 DPPP_NAMESPACE
21
22 =implementation
23
24 =pod
25
26 =head1 NAME
27
28 ppport.h - Perl/Pollution/Portability version __VERSION__
29
30 =head1 SYNOPSIS
31
32   perl ppport.h [options] [source files]
33
34   Searches current directory for files if no [source files] are given
35
36   --help                      show short help
37
38   --version                   show version
39
40   --patch=file                write one patch file with changes
41   --copy=suffix               write changed copies with suffix
42   --diff=program              use diff program and options
43
44   --compat-version=version    provide compatibility with Perl version
45   --cplusplus                 accept C++ comments
46
47   --quiet                     don't output anything except fatal errors
48   --nodiag                    don't show diagnostics
49   --nohints                   don't show hints
50   --nochanges                 don't suggest changes
51   --nofilter                  don't filter input files
52
53   --strip                     strip all script and doc functionality
54                               from ppport.h
55
56   --list-provided             list provided API
57   --list-unsupported          list unsupported API
58   --api-info=name             show Perl API portability information
59
60 =head1 COMPATIBILITY
61
62 This version of F<ppport.h> is designed to support operation with Perl
63 installations back to __MIN_PERL__, and has been tested up to __MAX_PERL__.
64
65 =head1 OPTIONS
66
67 =head2 --help
68
69 Display a brief usage summary.
70
71 =head2 --version
72
73 Display the version of F<ppport.h>.
74
75 =head2 --patch=I<file>
76
77 If this option is given, a single patch file will be created if
78 any changes are suggested. This requires a working diff program
79 to be installed on your system.
80
81 =head2 --copy=I<suffix>
82
83 If this option is given, a copy of each file will be saved with
84 the given suffix that contains the suggested changes. This does
85 not require any external programs. Note that this does not
86 automagically add a dot between the original filename and the
87 suffix. If you want the dot, you have to include it in the option
88 argument.
89
90 If neither C<--patch> or C<--copy> are given, the default is to
91 simply print the diffs for each file. This requires either
92 C<Text::Diff> or a C<diff> program to be installed.
93
94 =head2 --diff=I<program>
95
96 Manually set the diff program and options to use. The default
97 is to use C<Text::Diff>, when installed, and output unified
98 context diffs.
99
100 =head2 --compat-version=I<version>
101
102 Tell F<ppport.h> to check for compatibility with the given
103 Perl version. The default is to check for compatibility with Perl
104 version __MIN_PERL__. You can use this option to reduce the output
105 of F<ppport.h> if you intend to be backward compatible only
106 down to a certain Perl version.
107
108 =head2 --cplusplus
109
110 Usually, F<ppport.h> will detect C++ style comments and
111 replace them with C style comments for portability reasons.
112 Using this option instructs F<ppport.h> to leave C++
113 comments untouched.
114
115 =head2 --quiet
116
117 Be quiet. Don't print anything except fatal errors.
118
119 =head2 --nodiag
120
121 Don't output any diagnostic messages. Only portability
122 alerts will be printed.
123
124 =head2 --nohints
125
126 Don't output any hints. Hints often contain useful portability
127 notes. Warnings will still be displayed.
128
129 =head2 --nochanges
130
131 Don't suggest any changes. Only give diagnostic output and hints
132 unless these are also deactivated.
133
134 =head2 --nofilter
135
136 Don't filter the list of input files. By default, files not looking
137 like source code (i.e. not *.xs, *.c, *.cc, *.cpp or *.h) are skipped.
138
139 =head2 --strip
140
141 Strip all script and documentation functionality from F<ppport.h>.
142 This reduces the size of F<ppport.h> dramatically and may be useful
143 if you want to include F<ppport.h> in smaller modules without
144 increasing their distribution size too much.
145
146 The stripped F<ppport.h> will have a C<--unstrip> option that allows
147 you to undo the stripping, but only if an appropriate C<Devel::PPPort>
148 module is installed.
149
150 =head2 --list-provided
151
152 Lists the API elements for which compatibility is provided by
153 F<ppport.h>. Also lists if it must be explicitly requested,
154 if it has dependencies, and if there are hints or warnings for it.
155
156 =head2 --list-unsupported
157
158 Lists the API elements that are known not to be supported by
159 F<ppport.h> and below which version of Perl they probably
160 won't be available or work.
161
162 =head2 --api-info=I<name>
163
164 Show portability information for API elements matching I<name>.
165 If I<name> is surrounded by slashes, it is interpreted as a regular
166 expression.
167
168 =head1 DESCRIPTION
169
170 In order for a Perl extension (XS) module to be as portable as possible
171 across differing versions of Perl itself, certain steps need to be taken.
172
173 =over 4
174
175 =item *
176
177 Including this header is the first major one. This alone will give you
178 access to a large part of the Perl API that hasn't been available in
179 earlier Perl releases. Use
180
181     perl ppport.h --list-provided
182
183 to see which API elements are provided by ppport.h.
184
185 =item *
186
187 You should avoid using deprecated parts of the API. For example, using
188 global Perl variables without the C<PL_> prefix is deprecated. Also,
189 some API functions used to have a C<perl_> prefix. Using this form is
190 also deprecated. You can safely use the supported API, as F<ppport.h>
191 will provide wrappers for older Perl versions.
192
193 =item *
194
195 If you use one of a few functions or variables that were not present in
196 earlier versions of Perl, and that can't be provided using a macro, you
197 have to explicitly request support for these functions by adding one or
198 more C<#define>s in your source code before the inclusion of F<ppport.h>.
199
200 These functions or variables will be marked C<explicit> in the list shown
201 by C<--list-provided>.
202
203 Depending on whether you module has a single or multiple files that
204 use such functions or variables, you want either C<static> or global
205 variants.
206
207 For a C<static> function or variable (used only in a single source
208 file), use:
209
210     #define NEED_function
211     #define NEED_variable
212
213 For a global function or variable (used in multiple source files),
214 use:
215
216     #define NEED_function_GLOBAL
217     #define NEED_variable_GLOBAL
218
219 Note that you mustn't have more than one global request for the
220 same function or variable in your project.
221
222     __EXPLICIT_API__
223
224 To avoid namespace conflicts, you can change the namespace of the
225 explicitly exported functions / variables using the C<DPPP_NAMESPACE>
226 macro. Just C<#define> the macro before including C<ppport.h>:
227
228     #define DPPP_NAMESPACE MyOwnNamespace_
229     #include "ppport.h"
230
231 The default namespace is C<DPPP_>.
232
233 =back
234
235 The good thing is that most of the above can be checked by running
236 F<ppport.h> on your source code. See the next section for
237 details.
238
239 =head1 EXAMPLES
240
241 To verify whether F<ppport.h> is needed for your module, whether you
242 should make any changes to your code, and whether any special defines
243 should be used, F<ppport.h> can be run as a Perl script to check your
244 source code. Simply say:
245
246     perl ppport.h
247
248 The result will usually be a list of patches suggesting changes
249 that should at least be acceptable, if not necessarily the most
250 efficient solution, or a fix for all possible problems.
251
252 If you know that your XS module uses features only available in
253 newer Perl releases, if you're aware that it uses C++ comments,
254 and if you want all suggestions as a single patch file, you could
255 use something like this:
256
257     perl ppport.h --compat-version=5.6.0 --cplusplus --patch=test.diff
258
259 If you only want your code to be scanned without any suggestions
260 for changes, use:
261
262     perl ppport.h --nochanges
263
264 You can specify a different C<diff> program or options, using
265 the C<--diff> option:
266
267     perl ppport.h --diff='diff -C 10'
268
269 This would output context diffs with 10 lines of context.
270
271 If you want to create patched copies of your files instead, use:
272
273     perl ppport.h --copy=.new
274
275 To display portability information for the C<newSVpvn> function,
276 use:
277
278     perl ppport.h --api-info=newSVpvn
279
280 Since the argument to C<--api-info> can be a regular expression,
281 you can use
282
283     perl ppport.h --api-info=/_nomg$/
284
285 to display portability information for all C<_nomg> functions or
286
287     perl ppport.h --api-info=/./
288
289 to display information for all known API elements.
290
291 =head1 BUGS
292
293 Some of the suggested edits and/or generated patches may not compile as-is
294 without tweaking manually.  This is generally due to the need for an extra
295 parameter to be added to the call to prevent buffer overflow.
296
297 If this version of F<ppport.h> is causing failure during
298 the compilation of this module, please check if newer versions
299 of either this module or C<Devel::PPPort> are available on CPAN
300 before sending a bug report.
301
302 If F<ppport.h> was generated using the latest version of
303 C<Devel::PPPort> and is causing failure of this module, please
304 send a bug report to L<perlbug@perl.org|mailto:perlbug@perl.org>.
305
306 Please include the following information:
307
308 =over 4
309
310 =item 1.
311
312 The complete output from running "perl -V"
313
314 =item 2.
315
316 This file.
317
318 =item 3.
319
320 The name and version of the module you were trying to build.
321
322 =item 4.
323
324 A full log of the build that failed.
325
326 =item 5.
327
328 Any other information that you think could be relevant.
329
330 =back
331
332 For the latest version of this code, please get the C<Devel::PPPort>
333 module from CPAN.
334
335 =head1 COPYRIGHT
336
337 Version 3.x, Copyright (c) 2004-2013, Marcus Holland-Moritz.
338
339 Version 2.x, Copyright (C) 2001, Paul Marquess.
340
341 Version 1.x, Copyright (C) 1999, Kenneth Albanowski.
342
343 This program is free software; you can redistribute it and/or
344 modify it under the same terms as Perl itself.
345
346 =head1 SEE ALSO
347
348 See L<Devel::PPPort>.
349
350 =cut