ext/Devel/PPPort/parts/inc/ppphdoc

   1 ################################################################################
   2 ##
   3 ##  $Revision: 18 $
   4 ##  $Author: mhx $
   5 ##  $Date: 2004/12/29 14:55:00 +0100 $
   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   --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 I<name> is treated as a Perl regular expression.
 139
 140 =head1 DESCRIPTION
 141
 142 In order for a Perl extension (XS) module to be as portable as possible
 143 across differing versions of Perl itself, certain steps need to be taken.
 144
 145 =over 4
 146
 147 =item *
 148
 149 Including this header is the first major one. This alone will give you
 150 access to a large part of the Perl API that hasn't been available in
 151 earlier Perl releases. Use
 152
 153     perl ppport.h --list-provided
 154
 155 to see which API elements are provided by ppport.h.
 156
 157 =item *
 158
 159 You should avoid using deprecated parts of the API. For example, using
 160 global Perl variables without the C<PL_> prefix is deprecated. Also,
 161 some API functions used to have a C<perl_> prefix. Using this form is
 162 also deprecated. You can safely use the supported API, as F<ppport.h>
 163 will provide wrappers for older Perl versions.
 164
 165 =item *
 166
 167 If you use one of a few functions that were not present in earlier
 168 versions of Perl, and that can't be provided using a macro, you have
 169 to explicitly request support for these functions by adding one or
 170 more C<#define>s in your source code before the inclusion of F<ppport.h>.
 171
 172 These functions will be marked C<explicit> in the list shown by
 173 C<--list-provided>.
 174
 175 Depending on whether you module has a single or multiple files that
 176 use such functions, you want either C<static> or global variants.
 177
 178 For a C<static> function, use:
 179
 180     #define NEED_function
 181
 182 For a global function, use:
 183
 184     #define NEED_function_GLOBAL
 185
 186 Note that you mustn't have more than one global request for one
 187 function in your project.
 188
 189     __EXPLICIT_API__
 190
 191 To avoid namespace conflicts, you can change the namespace of the
 192 explicitly exported functions using the C<DPPP_NAMESPACE> macro.
 193 Just C<#define> the macro before including C<ppport.h>:
 194
 195     #define DPPP_NAMESPACE MyOwnNamespace_
 196     #include "ppport.h"
 197
 198 The default namespace is C<DPPP_>.
 199
 200 =back
 201
 202 The good thing is that most of the above can be checked by running
 203 F<ppport.h> on your source code. See the next section for
 204 details.
 205
 206 =head1 EXAMPLES
 207
 208 To verify whether F<ppport.h> is needed for your module, whether you
 209 should make any changes to your code, and whether any special defines
 210 should be used, F<ppport.h> can be run as a Perl script to check your
 211 source code. Simply say:
 212
 213     perl ppport.h
 214
 215 The result will usually be a list of patches suggesting changes
 216 that should at least be acceptable, if not necessarily the most
 217 efficient solution, or a fix for all possible problems.
 218
 219 If you know that your XS module uses features only available in
 220 newer Perl releases, if you're aware that it uses C++ comments,
 221 and if you want all suggestions as a single patch file, you could
 222 use something like this:
 223
 224     perl ppport.h --compat-version=5.6.0 --cplusplus --patch=test.diff
 225
 226 If you only want your code to be scanned without any suggestions
 227 for changes, use:
 228
 229     perl ppport.h --nochanges
 230
 231 You can specify a different C<diff> program or options, using
 232 the C<--diff> option:
 233
 234     perl ppport.h --diff='diff -C 10'
 235
 236 This would output context diffs with 10 lines of context.
 237
 238 =head1 BUGS
 239
 240 If this version of F<ppport.h> is causing failure during
 241 the compilation of this module, please check if newer versions
 242 of either this module or C<Devel::PPPort> are available on CPAN
 243 before sending a bug report.
 244
 245 If F<ppport.h> was generated using the latest version of
 246 C<Devel::PPPort> and is causing failure of this module, please
 247 file a bug report using the CPAN Request Tracker at L<http://rt.cpan.org/>.
 248
 249 Please include the following information:
 250
 251 =over 4
 252
 253 =item 1.
 254
 255 The complete output from running "perl -V"
 256
 257 =item 2.
 258
 259 This file.
 260
 261 =item 3.
 262
 263 The name and version of the module you were trying to build.
 264
 265 =item 4.
 266
 267 A full log of the build that failed.
 268
 269 =item 5.
 270
 271 Any other information that you think could be relevant.
 272
 273 =back
 274
 275 For the latest version of this code, please get the C<Devel::PPPort>
 276 module from CPAN.
 277
 278 =head1 COPYRIGHT
 279
 280 Version 3.x, Copyright (c) 2004, Marcus Holland-Moritz.
 281
 282 Version 2.x, Copyright (C) 2001, Paul Marquess.
 283
 284 Version 1.x, Copyright (C) 1999, Kenneth Albanowski.
 285
 286 This program is free software; you can redistribute it and/or
 287 modify it under the same terms as Perl itself.
 288
 289 =head1 SEE ALSO
 290
 291 See L<Devel::PPPort>.
 292