dist/Devel-PPPort/parts/inc/ppphdoc

   1 ################################################################################
   2 ##
   3 ##  Version 3.x, Copyright (C) 2004-2013, Marcus Holland-Moritz.
   4 ##  Version 2.x, Copyright (C) 2001, Paul Marquess.
   5 ##  Version 1.x, Copyright (C) 1999, Kenneth Albanowski.
   6 ##
   7 ##  This program is free software; you can redistribute it and/or
   8 ##  modify it under the same terms as Perl itself.
   9 ##
  10 ################################################################################
  11
  12 =provides
  13
  14 =dontwarn
  15
  16 NEED_function
  17 NEED_function_GLOBAL
  18 NEED_variable
  19 NEED_variable_GLOBAL
  20 DPPP_NAMESPACE
  21
  22 =implementation
  23
  24 =pod
  25
  26 =head1 NAME
  27
  28 ppport.h - Perl/Pollution/Portability version __VERSION__
  29
  30 =head1 SYNOPSIS
  31
  32   perl ppport.h [options] [source files]
  33
  34   Searches current directory for files if no [source files] are given
  35
  36   --help                      show short help
  37
  38   --version                   show version
  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   --nofilter                  don't filter input files
  52
  53   --strip                     strip all script and doc functionality
  54                               from ppport.h
  55
  56   --list-provided             list provided API
  57   --list-unsupported          list API that isn't supported all the way
  58                               back
  59   --api-info=name             show Perl API portability information
  60
  61 =head1 COMPATIBILITY
  62
  63 This version of F<ppport.h> is designed to support operation with Perl
  64 installations back to __MIN_PERL__, and has been tested up to __MAX_PERL__.
  65
  66 =head1 OPTIONS
  67
  68 =head2 --help
  69
  70 Display a brief usage summary.
  71
  72 =head2 --version
  73
  74 Display the version of F<ppport.h>.
  75
  76 =head2 --patch=I<file>
  77
  78 If this option is given, a single patch file will be created if
  79 any changes are suggested. This requires a working diff program
  80 to be installed on your system.
  81
  82 =head2 --copy=I<suffix>
  83
  84 If this option is given, a copy of each file will be saved with
  85 the given suffix that contains the suggested changes. This does
  86 not require any external programs. Note that this does not
  87 automagically add a dot between the original filename and the
  88 suffix. If you want the dot, you have to include it in the option
  89 argument.
  90
  91 If neither C<--patch> or C<--copy> are given, the default is to
  92 simply print the diffs for each file. This requires either
  93 C<Text::Diff> or a C<diff> program to be installed.
  94
  95 =head2 --diff=I<program>
  96
  97 Manually set the diff program and options to use. The default
  98 is to use C<Text::Diff>, when installed, and output unified
  99 context diffs.
 100
 101 =head2 --compat-version=I<version>
 102
 103 Tell F<ppport.h> to check for compatibility with the given
 104 Perl version. The default is to check for compatibility with Perl
 105 version __MIN_PERL__. You can use this option to reduce the output
 106 of F<ppport.h> if you intend to be backward compatible only
 107 down to a certain Perl version.
 108
 109 =head2 --cplusplus
 110
 111 Usually, F<ppport.h> will detect C++ style comments and
 112 replace them with C style comments for portability reasons.
 113 Using this option instructs F<ppport.h> to leave C++
 114 comments untouched.
 115
 116 =head2 --quiet
 117
 118 Be quiet. Don't print anything except fatal errors.
 119
 120 =head2 --nodiag
 121
 122 Don't output any diagnostic messages. Only portability
 123 alerts will be printed.
 124
 125 =head2 --nohints
 126
 127 Don't output any hints. Hints often contain useful portability
 128 notes. Warnings will still be displayed.
 129
 130 =head2 --nochanges
 131
 132 Don't suggest any changes. Only give diagnostic output and hints
 133 unless these are also deactivated.
 134
 135 =head2 --nofilter
 136
 137 Don't filter the list of input files. By default, files not looking
 138 like source code (i.e. not *.xs, *.c, *.cc, *.cpp or *.h) are skipped.
 139
 140 =head2 --strip
 141
 142 Strip all script and documentation functionality from F<ppport.h>.
 143 This reduces the size of F<ppport.h> dramatically and may be useful
 144 if you want to include F<ppport.h> in smaller modules without
 145 increasing their distribution size too much.
 146
 147 The stripped F<ppport.h> will have a C<--unstrip> option that allows
 148 you to undo the stripping, but only if an appropriate C<Devel::PPPort>
 149 module is installed.
 150
 151 =head2 --list-provided
 152
 153 Lists the API elements for which compatibility is provided by
 154 F<ppport.h>. Also lists if it must be explicitly requested,
 155 if it has dependencies, and if there are hints or warnings for it.
 156
 157 =head2 --list-unsupported
 158
 159 Lists the API elements that are known not to be FULLY supported by F<ppport.h>,
 160 and below which version of Perl they probably won't be available or work.
 161 By FULLY, we mean that support isn't provided all the way back to the first
 162 version of Perl that F<ppport.h> supports at all.
 163
 164 =head2 --api-info=I<name>
 165
 166 Show portability information for elements matching I<name>.
 167 If I<name> is surrounded by slashes, it is interpreted as a regular
 168 expression.
 169
 170 Normally, only API elements are shown, but if there are no matching API
 171 elements but there are some other matching elements, those are shown.  This
 172 allows you to conveniently find when functions internal to the core
 173 implementation were added; only people working on the core are likely to find
 174 this last part useful.
 175
 176 =head1 DESCRIPTION
 177
 178 In order for a Perl extension (XS) module to be as portable as possible
 179 across differing versions of Perl itself, certain steps need to be taken.
 180
 181 =over 4
 182
 183 =item *
 184
 185 Including this header is the first major one. This alone will give you
 186 access to a large part of the Perl API that hasn't been available in
 187 earlier Perl releases. Use
 188
 189     perl ppport.h --list-provided
 190
 191 to see which API elements are provided by ppport.h.
 192
 193 =item *
 194
 195 You should avoid using deprecated parts of the API. For example, using
 196 global Perl variables without the C<PL_> prefix is deprecated. Also,
 197 some API functions used to have a C<perl_> prefix. Using this form is
 198 also deprecated. You can safely use the supported API, as F<ppport.h>
 199 will provide wrappers for older Perl versions.
 200
 201 =item *
 202
 203 Although the purpose of F<ppport.h> is to keep you from having to concern
 204 yourself with what version you are running under, there may arise instances
 205 where you have to do so.  These macros, the same ones as in base Perl, are
 206 available to you in all versions, and are what you should use:
 207
 208 =over 4
 209
 210 =item C<PERL_VERSION_I<xx>(major, minor, patch)>
 211
 212 Returns whether or not the perl currently being compiled has the specified
 213 relationship I<xx> to the perl given by the parameters.  I<xx> is one of
 214 C<EQ>, C<NE>, C<LT>, C<LE>, C<GT>, C<GE>.
 215
 216 For example,
 217
 218  #if PERL_VERSION_GT(5,24,2)
 219    code that will only be compiled on perls after v5.24.2
 220  #else
 221    fallback code
 222  #endif
 223
 224 Note that this is usable in making compile-time decisions
 225
 226 You may use the special value '*' for the final number to mean ALL possible
 227 values for it.  Thus,
 228
 229  #if PERL_VERSION_EQ(5,31,'*')
 230
 231 means all perls in the 5.31 series.  And
 232
 233  #if PERL_VERSION_NE(5,24,'*')
 234
 235 means all perls EXCEPT 5.24 ones.  And
 236
 237  #if PERL_VERSION_LE(5,9,'*')
 238
 239 is effectively
 240
 241  #if PERL_VERSION_LT(5,10,0)
 242
 243 =back
 244
 245 =item *
 246
 247 If you use one of a few functions or variables that were not present in
 248 earlier versions of Perl, and that can't be provided using a macro, you
 249 have to explicitly request support for these functions by adding one or
 250 more C<#define>s in your source code before the inclusion of F<ppport.h>.
 251
 252 These functions or variables will be marked C<explicit> in the list shown
 253 by C<--list-provided>.
 254
 255 Depending on whether you module has a single or multiple files that
 256 use such functions or variables, you want either C<static> or global
 257 variants.
 258
 259 For a C<static> function or variable (used only in a single source
 260 file), use:
 261
 262     #define NEED_function
 263     #define NEED_variable
 264
 265 For a global function or variable (used in multiple source files),
 266 use:
 267
 268     #define NEED_function_GLOBAL
 269     #define NEED_variable_GLOBAL
 270
 271 Note that you mustn't have more than one global request for the
 272 same function or variable in your project.
 273
 274     __EXPLICIT_API__
 275
 276 To avoid namespace conflicts, you can change the namespace of the
 277 explicitly exported functions / variables using the C<DPPP_NAMESPACE>
 278 macro. Just C<#define> the macro before including C<ppport.h>:
 279
 280     #define DPPP_NAMESPACE MyOwnNamespace_
 281     #include "ppport.h"
 282
 283 The default namespace is C<DPPP_>.
 284
 285 =back
 286
 287 The good thing is that most of the above can be checked by running
 288 F<ppport.h> on your source code. See the next section for
 289 details.
 290
 291 =head1 EXAMPLES
 292
 293 To verify whether F<ppport.h> is needed for your module, whether you
 294 should make any changes to your code, and whether any special defines
 295 should be used, F<ppport.h> can be run as a Perl script to check your
 296 source code. Simply say:
 297
 298     perl ppport.h
 299
 300 The result will usually be a list of patches suggesting changes
 301 that should at least be acceptable, if not necessarily the most
 302 efficient solution, or a fix for all possible problems.
 303
 304 If you know that your XS module uses features only available in
 305 newer Perl releases, if you're aware that it uses C++ comments,
 306 and if you want all suggestions as a single patch file, you could
 307 use something like this:
 308
 309     perl ppport.h --compat-version=5.6.0 --cplusplus --patch=test.diff
 310
 311 If you only want your code to be scanned without any suggestions
 312 for changes, use:
 313
 314     perl ppport.h --nochanges
 315
 316 You can specify a different C<diff> program or options, using
 317 the C<--diff> option:
 318
 319     perl ppport.h --diff='diff -C 10'
 320
 321 This would output context diffs with 10 lines of context.
 322
 323 If you want to create patched copies of your files instead, use:
 324
 325     perl ppport.h --copy=.new
 326
 327 To display portability information for the C<newSVpvn> function,
 328 use:
 329
 330     perl ppport.h --api-info=newSVpvn
 331
 332 Since the argument to C<--api-info> can be a regular expression,
 333 you can use
 334
 335     perl ppport.h --api-info=/_nomg$/
 336
 337 to display portability information for all C<_nomg> functions or
 338
 339     perl ppport.h --api-info=/./
 340
 341 to display information for all known API elements.
 342
 343 =head1 BUGS
 344
 345 Some of the suggested edits and/or generated patches may not compile as-is
 346 without tweaking manually.  This is generally due to the need for an extra
 347 parameter to be added to the call to prevent buffer overflow.
 348
 349 If this version of F<ppport.h> is causing failure during
 350 the compilation of this module, please check if newer versions
 351 of either this module or C<Devel::PPPort> are available on CPAN
 352 before sending a bug report.
 353
 354 If F<ppport.h> was generated using the latest version of
 355 C<Devel::PPPort> and is causing failure of this module, please
 356 file a bug report at L<https://github.com/Dual-Life/Devel-PPPort/issues>
 357
 358 Please include the following information:
 359
 360 =over 4
 361
 362 =item 1.
 363
 364 The complete output from running "perl -V"
 365
 366 =item 2.
 367
 368 This file.
 369
 370 =item 3.
 371
 372 The name and version of the module you were trying to build.
 373
 374 =item 4.
 375
 376 A full log of the build that failed.
 377
 378 =item 5.
 379
 380 Any other information that you think could be relevant.
 381
 382 =back
 383
 384 For the latest version of this code, please get the C<Devel::PPPort>
 385 module from CPAN.
 386
 387 =head1 COPYRIGHT
 388
 389 Version 3.x, Copyright (c) 2004-2013, Marcus Holland-Moritz.
 390
 391 Version 2.x, Copyright (C) 2001, Paul Marquess.
 392
 393 Version 1.x, Copyright (C) 1999, Kenneth Albanowski.
 394
 395 This program is free software; you can redistribute it and/or
 396 modify it under the same terms as Perl itself.
 397
 398 =head1 SEE ALSO
 399
 400 See L<Devel::PPPort>.
 401
 402 =cut