ext/Devel/PPPort/parts/inc/ppphdoc

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