ext/Devel/PPPort/parts/inc/ppphdoc

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