ext/Devel/PPPort/parts/inc/ppphdoc

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