Commit | Line | Data |
adfe19db |
1 | ################################################################################ |
2 | ## |
3 | ## $Revision: 17 $ |
4 | ## $Author: mhx $ |
5 | ## $Date: 2004/08/13 12:45:56 +0200 $ |
6 | ## |
7 | ################################################################################ |
8 | ## |
9 | ## Version 3.x, Copyright (C) 2004, Marcus Holland-Moritz. |
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 |
24 | DPPP_NAMESPACE |
25 | |
26 | =implementation |
27 | |
28 | =pod |
29 | |
30 | =head1 NAME |
31 | |
32 | ppport.h - Perl/Pollution/Portability version __VERSION__ |
33 | |
34 | =head1 SYNOPSIS |
35 | |
36 | perl ppport.h [options] [files] |
37 | |
38 | --help show short help |
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 | |
52 | --list-provided list provided API |
53 | --list-unsupported list unsupported API |
54 | |
55 | =head1 COMPATIBILITY |
56 | |
57 | This version of F<ppport.h> is designed to support operation with Perl |
58 | installations back to __MIN_PERL__, and has been tested up to __MAX_PERL__. |
59 | |
60 | =head1 OPTIONS |
61 | |
62 | =head2 --help |
63 | |
64 | Display a brief usage summary. |
65 | |
66 | =head2 --patch=I<file> |
67 | |
68 | If this option is given, a single patch file will be created if |
69 | any changes are suggested. This requires a working diff program |
70 | to be installed on your system. |
71 | |
72 | =head2 --copy=I<suffix> |
73 | |
74 | If this option is given, a copy of each file will be saved with |
75 | the given suffix that contains the suggested changes. This does |
76 | not require any external programs. |
77 | |
78 | If neither C<--patch> or C<--copy> are given, the default is to |
79 | simply print the diffs for each file. This requires either |
80 | C<Text::Diff> or a C<diff> program to be installed. |
81 | |
82 | =head2 --diff=I<program> |
83 | |
84 | Manually set the diff program and options to use. The default |
85 | is to use C<Text::Diff>, when installed, and output unified |
86 | context diffs. |
87 | |
88 | =head2 --compat-version=I<version> |
89 | |
90 | Tell F<ppport.h> to check for compatibility with the given |
91 | Perl version. The default is to check for compatibility with Perl |
92 | version __MIN_PERL__. You can use this option to reduce the output |
93 | of F<ppport.h> if you intend to be backward compatible only |
94 | up to a certain Perl version. |
95 | |
96 | =head2 --cplusplus |
97 | |
98 | Usually, F<ppport.h> will detect C++ style comments and |
99 | replace them with C style comments for portability reasons. |
100 | Using this option instructs F<ppport.h> to leave C++ |
101 | comments untouched. |
102 | |
103 | =head2 --quiet |
104 | |
105 | Be quiet. Don't print anything except fatal errors. |
106 | |
107 | =head2 --nodiag |
108 | |
109 | Don't output any diagnostic messages. Only portability |
110 | alerts will be printed. |
111 | |
112 | =head2 --nohints |
113 | |
114 | Don't output any hints. Hints often contain useful portability |
115 | notes. |
116 | |
117 | =head2 --nochanges |
118 | |
119 | Don't suggest any changes. Only give diagnostic output and hints |
120 | unless these are also deactivated. |
121 | |
122 | =head2 --list-provided |
123 | |
124 | Lists the API elements for which compatibility is provided by |
125 | F<ppport.h>. Also lists if it must be explicitly requested, |
126 | if it has dependencies, and if there are hints for it. |
127 | |
128 | =head2 --list-unsupported |
129 | |
130 | Lists the API elements that are known not to be supported by |
131 | F<ppport.h> and below which version of Perl they probably |
132 | won't be available or work. |
133 | |
134 | =head1 DESCRIPTION |
135 | |
136 | In order for a Perl extension (XS) module to be as portable as possible |
137 | across differing versions of Perl itself, certain steps need to be taken. |
138 | |
139 | =over 4 |
140 | |
141 | =item * |
142 | |
143 | Including this header is the first major one. This alone will give you |
144 | access to a large part of the Perl API that hasn't been available in |
145 | earlier Perl releases. Use |
146 | |
147 | perl ppport.h --list-provided |
148 | |
149 | to see which API elements are provided by ppport.h. |
150 | |
151 | =item * |
152 | |
153 | You should avoid using deprecated parts of the API. For example, using |
154 | global Perl variables without the C<PL_> prefix is deprecated. Also, |
155 | some API functions used to have a C<perl_> prefix. Using this form is |
156 | also deprecated. You can safely use the supported API, as F<ppport.h> |
157 | will provide wrappers for older Perl versions. |
158 | |
159 | =item * |
160 | |
161 | If you use one of a few functions that were not present in earlier |
162 | versions of Perl, and that can't be provided using a macro, you have |
163 | to explicitly request support for these functions by adding one or |
164 | more C<#define>s in your source code before the inclusion of F<ppport.h>. |
165 | |
166 | These functions will be marked C<explicit> in the list shown by |
167 | C<--list-provided>. |
168 | |
169 | Depending on whether you module has a single or multiple files that |
170 | use such functions, you want either C<static> or global variants. |
171 | |
172 | For a C<static> function, use: |
173 | |
174 | #define NEED_function |
175 | |
176 | For a global function, use: |
177 | |
178 | #define NEED_function_GLOBAL |
179 | |
180 | Note that you mustn't have more than one global request for one |
181 | function in your project. |
182 | |
183 | __EXPLICIT_API__ |
184 | |
185 | To avoid namespace conflicts, you can change the namespace of the |
186 | explicitly exported functions using the C<DPPP_NAMESPACE> macro. |
187 | Just C<#define> the macro before including C<ppport.h>: |
188 | |
189 | #define DPPP_NAMESPACE MyOwnNamespace_ |
190 | #include "ppport.h" |
191 | |
192 | The default namespace is C<DPPP_>. |
193 | |
194 | =back |
195 | |
196 | The good thing is that most of the above can be checked by running |
197 | F<ppport.h> on your source code. See the next section for |
198 | details. |
199 | |
200 | =head1 EXAMPLES |
201 | |
202 | To verify whether F<ppport.h> is needed for your module, whether you |
203 | should make any changes to your code, and whether any special defines |
204 | should be used, F<ppport.h> can be run as a Perl script to check your |
205 | source code. Simply say: |
206 | |
207 | perl ppport.h |
208 | |
209 | The result will usually be a list of patches suggesting changes |
210 | that should at least be acceptable, if not necessarily the most |
211 | efficient solution, or a fix for all possible problems. |
212 | |
213 | If you know that your XS module uses features only available in |
214 | newer Perl releases, if you're aware that it uses C++ comments, |
215 | and if you want all suggestions as a single patch file, you could |
216 | use something like this: |
217 | |
218 | perl ppport.h --compat-version=5.6.0 --cplusplus --patch=test.diff |
219 | |
220 | If you only want your code to be scanned without any suggestions |
221 | for changes, use: |
222 | |
223 | perl ppport.h --nochanges |
224 | |
225 | You can specify a different C<diff> program or options, using |
226 | the C<--diff> option: |
227 | |
228 | perl ppport.h --diff='diff -C 10' |
229 | |
230 | This would output context diffs with 10 lines of context. |
231 | |
232 | =head1 BUGS |
233 | |
234 | If this version of F<ppport.h> is causing failure during |
235 | the compilation of this module, please check if newer versions |
236 | of either this module or C<Devel::PPPort> are available on CPAN |
237 | before sending a bug report. |
238 | |
239 | If F<ppport.h> was generated using the latest version of |
240 | C<Devel::PPPort> and is causing failure of this module, please |
241 | file a bug report using the CPAN Request Tracker at L<http://rt.cpan.org/>. |
242 | |
243 | Please include the following information: |
244 | |
245 | =over 4 |
246 | |
247 | =item 1. |
248 | |
249 | The complete output from running "perl -V" |
250 | |
251 | =item 2. |
252 | |
253 | This file. |
254 | |
255 | =item 3. |
256 | |
257 | The name and version of the module you were trying to build. |
258 | |
259 | =item 4. |
260 | |
261 | A full log of the build that failed. |
262 | |
263 | =item 5. |
264 | |
265 | Any other information that you think could be relevant. |
266 | |
267 | =back |
268 | |
269 | For the latest version of this code, please get the C<Devel::PPPort> |
270 | module from CPAN. |
271 | |
272 | =head1 COPYRIGHT |
273 | |
274 | Version 3.x, Copyright (c) 2004, Marcus Holland-Moritz. |
275 | |
276 | Version 2.x, Copyright (C) 2001, Paul Marquess. |
277 | |
278 | Version 1.x, Copyright (C) 1999, Kenneth Albanowski. |
279 | |
280 | This program is free software; you can redistribute it and/or |
281 | modify it under the same terms as Perl itself. |
282 | |
283 | =head1 SEE ALSO |
284 | |
285 | See L<Devel::PPPort>. |
286 | |