ext/Devel/PPPort/parts/inc/ppphdoc

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