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