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