Commit | Line | Data |
adfe19db |
1 | ################################################################################ |
2 | ## |
bfc37ff7 |
3 | ## $Revision: 33 $ |
adfe19db |
4 | ## $Author: mhx $ |
bfc37ff7 |
5 | ## $Date: 2010/03/07 13:15:47 +0100 $ |
adfe19db |
6 | ## |
7 | ################################################################################ |
8 | ## |
bfc37ff7 |
9 | ## Version 3.x, Copyright (C) 2004-2010, Marcus Holland-Moritz. |
adfe19db |
10 | ## Version 2.x, Copyright (C) 2001, Paul Marquess. |
11 | ## Version 1.x, Copyright (C) 1999, Kenneth Albanowski. |
12 | ## |
13 | ## This program is free software; you can redistribute it and/or |
14 | ## modify it under the same terms as Perl itself. |
15 | ## |
16 | ################################################################################ |
17 | |
18 | =provides |
19 | |
20 | =dontwarn |
21 | |
22 | NEED_function |
23 | NEED_function_GLOBAL |
0d0f8426 |
24 | NEED_variable |
25 | NEED_variable_GLOBAL |
adfe19db |
26 | DPPP_NAMESPACE |
27 | |
28 | =implementation |
29 | |
30 | =pod |
31 | |
32 | =head1 NAME |
33 | |
34 | ppport.h - Perl/Pollution/Portability version __VERSION__ |
35 | |
36 | =head1 SYNOPSIS |
37 | |
4a582685 |
38 | perl ppport.h [options] [source files] |
39 | |
40 | Searches current directory for files if no [source files] are given |
adfe19db |
41 | |
42 | --help show short help |
43 | |
78b4ff79 |
44 | --version show version |
45 | |
adfe19db |
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 |
49 | |
50 | --compat-version=version provide compatibility with Perl version |
51 | --cplusplus accept C++ comments |
52 | |
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 |
4a582685 |
57 | --nofilter don't filter input files |
adfe19db |
58 | |
0d0f8426 |
59 | --strip strip all script and doc functionality from |
78b4ff79 |
60 | ppport.h |
0d0f8426 |
61 | |
adfe19db |
62 | --list-provided list provided API |
63 | --list-unsupported list unsupported API |
04fc8b94 |
64 | --api-info=name show Perl API portability information |
adfe19db |
65 | |
66 | =head1 COMPATIBILITY |
67 | |
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__. |
70 | |
71 | =head1 OPTIONS |
72 | |
73 | =head2 --help |
74 | |
75 | Display a brief usage summary. |
76 | |
78b4ff79 |
77 | =head2 --version |
78 | |
79 | Display the version of F<ppport.h>. |
80 | |
adfe19db |
81 | =head2 --patch=I<file> |
82 | |
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. |
86 | |
87 | =head2 --copy=I<suffix> |
88 | |
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 |
679ad62d |
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 |
94 | argument. |
adfe19db |
95 | |
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. |
99 | |
100 | =head2 --diff=I<program> |
101 | |
102 | Manually set the diff program and options to use. The default |
103 | is to use C<Text::Diff>, when installed, and output unified |
104 | context diffs. |
105 | |
106 | =head2 --compat-version=I<version> |
107 | |
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 |
0d0f8426 |
112 | down to a certain Perl version. |
adfe19db |
113 | |
114 | =head2 --cplusplus |
115 | |
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++ |
119 | comments untouched. |
120 | |
121 | =head2 --quiet |
122 | |
123 | Be quiet. Don't print anything except fatal errors. |
124 | |
125 | =head2 --nodiag |
126 | |
127 | Don't output any diagnostic messages. Only portability |
128 | alerts will be printed. |
129 | |
130 | =head2 --nohints |
131 | |
132 | Don't output any hints. Hints often contain useful portability |
679ad62d |
133 | notes. Warnings will still be displayed. |
adfe19db |
134 | |
135 | =head2 --nochanges |
136 | |
137 | Don't suggest any changes. Only give diagnostic output and hints |
138 | unless these are also deactivated. |
139 | |
4a582685 |
140 | =head2 --nofilter |
141 | |
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. |
144 | |
0d0f8426 |
145 | =head2 --strip |
146 | |
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. |
151 | |
78b4ff79 |
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> |
154 | module is installed. |
155 | |
adfe19db |
156 | =head2 --list-provided |
157 | |
158 | Lists the API elements for which compatibility is provided by |
159 | F<ppport.h>. Also lists if it must be explicitly requested, |
679ad62d |
160 | if it has dependencies, and if there are hints or warnings for it. |
adfe19db |
161 | |
162 | =head2 --list-unsupported |
163 | |
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. |
167 | |
04fc8b94 |
168 | =head2 --api-info=I<name> |
169 | |
170 | Show portability information for API elements matching I<name>. |
9132e1a3 |
171 | If I<name> is surrounded by slashes, it is interpreted as a regular |
172 | expression. |
04fc8b94 |
173 | |
adfe19db |
174 | =head1 DESCRIPTION |
175 | |
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. |
178 | |
179 | =over 4 |
180 | |
181 | =item * |
182 | |
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 |
186 | |
187 | perl ppport.h --list-provided |
188 | |
189 | to see which API elements are provided by ppport.h. |
190 | |
191 | =item * |
192 | |
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. |
198 | |
199 | =item * |
200 | |
0d0f8426 |
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 |
adfe19db |
204 | more C<#define>s in your source code before the inclusion of F<ppport.h>. |
205 | |
0d0f8426 |
206 | These functions or variables will be marked C<explicit> in the list shown |
207 | by C<--list-provided>. |
adfe19db |
208 | |
209 | Depending on whether you module has a single or multiple files that |
0d0f8426 |
210 | use such functions or variables, you want either C<static> or global |
211 | variants. |
adfe19db |
212 | |
0d0f8426 |
213 | For a C<static> function or variable (used only in a single source |
214 | file), use: |
adfe19db |
215 | |
216 | #define NEED_function |
0d0f8426 |
217 | #define NEED_variable |
adfe19db |
218 | |
0d0f8426 |
219 | For a global function or variable (used in multiple source files), |
220 | use: |
adfe19db |
221 | |
222 | #define NEED_function_GLOBAL |
0d0f8426 |
223 | #define NEED_variable_GLOBAL |
adfe19db |
224 | |
0d0f8426 |
225 | Note that you mustn't have more than one global request for the |
226 | same function or variable in your project. |
adfe19db |
227 | |
228 | __EXPLICIT_API__ |
229 | |
230 | To avoid namespace conflicts, you can change the namespace of the |
0d0f8426 |
231 | explicitly exported functions / variables using the C<DPPP_NAMESPACE> |
232 | macro. Just C<#define> the macro before including C<ppport.h>: |
adfe19db |
233 | |
234 | #define DPPP_NAMESPACE MyOwnNamespace_ |
235 | #include "ppport.h" |
236 | |
237 | The default namespace is C<DPPP_>. |
238 | |
239 | =back |
240 | |
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 |
243 | details. |
244 | |
245 | =head1 EXAMPLES |
246 | |
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: |
251 | |
252 | perl ppport.h |
253 | |
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. |
257 | |
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: |
262 | |
263 | perl ppport.h --compat-version=5.6.0 --cplusplus --patch=test.diff |
264 | |
265 | If you only want your code to be scanned without any suggestions |
266 | for changes, use: |
267 | |
268 | perl ppport.h --nochanges |
269 | |
270 | You can specify a different C<diff> program or options, using |
271 | the C<--diff> option: |
272 | |
273 | perl ppport.h --diff='diff -C 10' |
274 | |
275 | This would output context diffs with 10 lines of context. |
276 | |
679ad62d |
277 | If you want to create patched copies of your files instead, use: |
278 | |
279 | perl ppport.h --copy=.new |
280 | |
9132e1a3 |
281 | To display portability information for the C<newSVpvn> function, |
282 | use: |
283 | |
284 | perl ppport.h --api-info=newSVpvn |
285 | |
286 | Since the argument to C<--api-info> can be a regular expression, |
287 | you can use |
288 | |
289 | perl ppport.h --api-info=/_nomg$/ |
290 | |
291 | to display portability information for all C<_nomg> functions or |
292 | |
293 | perl ppport.h --api-info=/./ |
294 | |
295 | to display information for all known API elements. |
296 | |
adfe19db |
297 | =head1 BUGS |
298 | |
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. |
303 | |
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/>. |
307 | |
308 | Please include the following information: |
309 | |
310 | =over 4 |
311 | |
312 | =item 1. |
313 | |
314 | The complete output from running "perl -V" |
315 | |
316 | =item 2. |
317 | |
318 | This file. |
319 | |
320 | =item 3. |
321 | |
322 | The name and version of the module you were trying to build. |
323 | |
324 | =item 4. |
325 | |
326 | A full log of the build that failed. |
327 | |
328 | =item 5. |
329 | |
330 | Any other information that you think could be relevant. |
331 | |
332 | =back |
333 | |
334 | For the latest version of this code, please get the C<Devel::PPPort> |
335 | module from CPAN. |
336 | |
337 | =head1 COPYRIGHT |
338 | |
bfc37ff7 |
339 | Version 3.x, Copyright (c) 2004-2010, Marcus Holland-Moritz. |
adfe19db |
340 | |
341 | Version 2.x, Copyright (C) 2001, Paul Marquess. |
342 | |
343 | Version 1.x, Copyright (C) 1999, Kenneth Albanowski. |
344 | |
345 | This program is free software; you can redistribute it and/or |
346 | modify it under the same terms as Perl itself. |
347 | |
348 | =head1 SEE ALSO |
349 | |
350 | See L<Devel::PPPort>. |
351 | |
c07deaaf |
352 | =cut |
353 | |