2 <!DOCTYPE html PUBLIC
"-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
3 <html xmlns=
"http://www.w3.org/1999/xhtml">
5 <title>Devel::PPPort - Perl/Pollution/Portability
</title>
6 <meta http-equiv=
"content-type" content=
"text/html; charset=utf-8" />
7 <link rev=
"made" href=
"mailto:" />
10 <body style=
"background-color: white">
11 <table border=
"0" width=
"100%" cellspacing=
"0" cellpadding=
"3">
12 <tr><td class=
"block" style=
"background-color: #cccccc" valign=
"middle">
13 <big><strong><span class=
"block"> Devel::PPPort - Perl/Pollution/Portability
</span></strong></big>
17 <p><a name=
"__index__"></a></p>
22 <li><a href=
"#name">NAME
</a></li>
23 <li><a href=
"#synopsis">SYNOPSIS
</a></li>
24 <li><a href=
"#description">DESCRIPTION
</a></li>
27 <li><a href=
"#why_use_ppport_h">Why use ppport.h?
</a></li>
28 <li><a href=
"#how_to_use_ppport_h">How to use ppport.h
</a></li>
29 <li><a href=
"#running_ppport_h">Running ppport.h
</a></li>
32 <li><a href=
"#functions">FUNCTIONS
</a></li>
35 <li><a href=
"#writefile">WriteFile
</a></li>
38 <li><a href=
"#compatibility">COMPATIBILITY
</a></li>
41 <li><a href=
"#provided_perl_compatibility_api">Provided Perl compatibility API
</a></li>
42 <li><a href=
"#perl_api_not_supported_by_ppport_h">Perl API not supported by ppport.h
</a></li>
45 <li><a href=
"#bugs">BUGS
</a></li>
46 <li><a href=
"#authors">AUTHORS
</a></li>
47 <li><a href=
"#copyright">COPYRIGHT
</a></li>
48 <li><a href=
"#see_also">SEE ALSO
</a></li>
55 <h1><a name=
"name">NAME
</a></h1>
56 <p>Devel::PPPort - Perl/Pollution/Portability
</p>
60 <h1><a name=
"synopsis">SYNOPSIS
</a></h1>
62 Devel::PPPort::WriteFile(); # defaults to ./ppport.h
63 Devel::PPPort::WriteFile('someheader.h');
</pre>
67 <h1><a name=
"description">DESCRIPTION
</a></h1>
68 <p>Perl's API has changed over time, gaining new features, new functions,
69 increasing its flexibility, and reducing the impact on the C namespace
70 environment (reduced pollution). The header file written by this module,
71 typically
<em>ppport.h
</em>, attempts to bring some of the newer Perl API
72 features to older versions of Perl, so that you can worry less about
73 keeping track of old releases, but users can still reap the benefit.
</p>
74 <p><code>Devel::PPPort
</code> contains a single function, called
<code>WriteFile
</code>. Its
75 only purpose is to write the
<em>ppport.h
</em> C header file. This file
76 contains a series of macros and, if explicitly requested, functions that
77 allow XS modules to be built using older versions of Perl. Currently,
78 Perl versions from
5.003 to
5.9.3 are supported.
</p>
79 <p>This module is used by
<code>h2xs
</code> to write the file
<em>ppport.h
</em>.
</p>
82 <h2><a name=
"why_use_ppport_h">Why use ppport.h?
</a></h2>
83 <p>You should use
<em>ppport.h
</em> in modern code so that your code will work
84 with the widest range of Perl interpreters possible, without significant
86 <p>You should attempt older code to fully use
<em>ppport.h
</em>, because the
87 reduced pollution of newer Perl versions is an important thing. It's so
88 important that the old polluting ways of original Perl modules will not be
89 supported very far into the future, and your module will almost certainly
90 break! By adapting to it now, you'll gain compatibility and a sense of
91 having done the electronic ecology some good.
</p>
94 <h2><a name=
"how_to_use_ppport_h">How to use ppport.h
</a></h2>
95 <p>Don't direct the users of your module to download
<code>Devel::PPPort
</code>.
96 They are most probably no XS writers. Also, don't make
<em>ppport.h
</em>
97 optional. Rather, just take the most recent copy of
<em>ppport.h
</em> that
98 you can find (e.g. by generating it with the latest
<code>Devel::PPPort
</code>
99 release from CPAN), copy it into your project, adjust your project to
100 use it, and distribute the header along with your module.
</p>
103 <h2><a name=
"running_ppport_h">Running ppport.h
</a></h2>
104 <p>But
<em>ppport.h
</em> is more than just a C header. It's also a Perl script
105 that can check your source code. It will suggest hints and portability
106 notes, and can even make suggestions on how to change your code. You
107 can run it like any other Perl program:
</p>
109 perl ppport.h [options] [files]
</pre>
110 <p>It also has embedded documentation, so you can use
</p>
112 <a href=
"//C|\msysgit\mingw\html/pod/perldoc.html">perldoc
</a> ppport.h
</pre>
113 <p>to find out more about how to use it.
</p>
117 <h1><a name=
"functions">FUNCTIONS
</a></h1>
120 <h2><a name=
"writefile">WriteFile
</a></h2>
121 <p><code>WriteFile
</code> takes one optional argument. When called with one
122 argument, it expects to be passed a filename. When called with
123 no arguments, it defaults to the filename
<em>ppport.h
</em>.
</p>
124 <p>The function returns a true value if the file was written successfully.
125 Otherwise it returns a false value.
</p>
129 <h1><a name=
"compatibility">COMPATIBILITY
</a></h1>
130 <p><em>ppport.h
</em> supports Perl versions from
5.003 to
5.9.3
131 in threaded and non-threaded configurations.
</p>
134 <h2><a name=
"provided_perl_compatibility_api">Provided Perl compatibility API
</a></h2>
135 <p>The header file written by this module, typically
<em>ppport.h
</em>, provides
136 access to the following elements of the Perl API that is not available
137 in older Perl releases:
</p>
193 IN_LOCALE_COMPILETIME
197 IS_NUMBER_GREATER_THAN_UV_MAX
232 PERL_GCC_BRACE_GROUPS_FORBIDDEN
254 PERL_MAGIC_overload_elem
255 PERL_MAGIC_overload_table
260 PERL_MAGIC_regex_global
262 PERL_MAGIC_shared_scalar
270 PERL_MAGIC_tiedscalar
279 PERL_SCAN_ALLOW_UNDERSCORES
280 PERL_SCAN_DISALLOW_PREFIX
281 PERL_SCAN_GREATER_THAN_UV_MAX
282 PERL_SCAN_SILENT_ILLDIGIT
314 PL_perl_destruct_level
351 sv_catpvf_mg_nocontext
363 sv_setpvf_mg_nocontext
405 <h2><a name=
"perl_api_not_supported_by_ppport_h">Perl API not supported by ppport.h
</a></h2>
406 <p>There is still a big part of the API not supported by
<em>ppport.h
</em>.
407 Either because it doesn't make sense to back-port that part of the API,
408 or simply because it hasn't been implemented yet. Patches welcome!
</p>
409 <p>Here's a list of the currently unsupported API, and also the version of
410 Perl below which it is unsupported:
</p>
412 <dt><strong><a name=
"item_perl_5_2e9_2e3">perl
5.9.3</a></strong>
430 is_utf8_string_loclen
433 stashpv_hvname_match
</pre>
435 <dt><strong><a name=
"item_perl_5_2e9_2e2">perl
5.9.2</a></strong>
448 <dt><strong><a name=
"item_perl_5_2e9_2e1">perl
5.9.1</a></strong>
453 hv_clear_placeholders
459 <dt><strong><a name=
"item_perl_5_2e9_2e0">perl
5.9.0</a></strong>
470 <dt><strong><a name=
"item_perl_5_2e8_2e3">perl
5.8.3</a></strong>
475 SvIsCOW_shared_hash
</pre>
477 <dt><strong><a name=
"item_perl_5_2e8_2e1">perl
5.8.1</a></strong>
494 <dt><strong><a name=
"item_perl_5_2e8_2e0">perl
5.8.0</a></strong>
503 <dt><strong><a name=
"item_perl_5_2e7_2e3">perl
5.7.3</a></strong>
539 gv_fetchmeth_autoload
571 <dt><strong><a name=
"item_perl_5_2e7_2e2">perl
5.7.2</a></strong>
590 sv_utf8_upgrade_flags
593 <dt><strong><a name=
"item_perl_5_2e7_2e1">perl
5.7.1</a></strong>
610 sv_force_normal_flags
622 <dt><strong><a name=
"item_perl_5_2e6_2e1">perl
5.6.1</a></strong>
633 utf16_to_utf8_reversed
636 <dt><strong><a name=
"item_perl_5_2e6_2e0">perl
5.6.0</a></strong>
796 <dt><strong><a name=
"item_perl_5_2e005_03">perl
5.005_03
</a></strong>
802 save_generic_svref
</pre>
804 <dt><strong><a name=
"item_perl_5_2e005">perl
5.005</a></strong>
835 <dt><strong><a name=
"item_perl_5_2e004_05">perl
5.004_05
</a></strong>
843 <dt><strong><a name=
"item_perl_5_2e004">perl
5.004</a></strong>
872 gv_fetchmethod_autoload
916 <h1><a name=
"bugs">BUGS
</a></h1>
917 <p>If you find any bugs,
<code>Devel::PPPort
</code> doesn't seem to build on your
918 system or any of its tests fail, please use the CPAN Request Tracker
919 at
<a href=
"http://rt.cpan.org/">http://rt.cpan.org/
</a> to create a ticket for the module.
</p>
923 <h1><a name=
"authors">AUTHORS
</a></h1>
926 <p>Version
1.x of Devel::PPPort was written by Kenneth Albanowski.
</p>
929 <p>Version
2.x was ported to the Perl core by Paul Marquess.
</p>
932 <p>Version
3.x was ported back to CPAN by Marcus Holland-Moritz.
</p>
938 <h1><a name=
"copyright">COPYRIGHT
</a></h1>
939 <p>Version
3.x, Copyright (C)
2004-
2005, Marcus Holland-Moritz.
</p>
940 <p>Version
2.x, Copyright (C)
2001, Paul Marquess.
</p>
941 <p>Version
1.x, Copyright (C)
1999, Kenneth Albanowski.
</p>
942 <p>This program is free software; you can redistribute it and/or
943 modify it under the same terms as Perl itself.
</p>
947 <h1><a name=
"see_also">SEE ALSO
</a></h1>
948 <p>See
<a href=
"file://C|\msysgit\mingw\html/utils/h2xs.html">the h2xs manpage
</a>,
<a href=
"file://C|\msysgit\mingw\html/ext/Cwd/ppport.h.html">the ppport.h manpage
</a>.
</p>
949 <table border=
"0" width=
"100%" cellspacing=
"0" cellpadding=
"3">
950 <tr><td class=
"block" style=
"background-color: #cccccc" valign=
"middle">
951 <big><strong><span class=
"block"> Devel::PPPort - Perl/Pollution/Portability
</span></strong></big>