ext/Devel/PPPort/parts/inc/ppphdoc

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