I<see> that the community efforts really work. So after each of his
sync points, you are to 'make test' to check if everything is still
in working order. If it is, you do 'make ok', which will send an OK
-report to perlbug@perl.org. (If you do not have access to a mailer
+report to I<perlbug@perl.org>. (If you do not have access to a mailer
from the system you just finished successfully 'make test', you can
do 'make okfile', which creates the file C<perl.ok>, which you can
than take to your favourite mailer and mail yourself).
function edit {
if [ -L $1 ]; then
mv $1 $1.orig
- cp $1.orig $1
- vi $1
+ cp $1.orig $1
+ vi $1
else
- /bin/vi $1
- fi
+ vi $1
+ fi
}
function unedit {
if [ -L $1.orig ]; then
rm $1
- mv $1.orig $1
- fi
+ mv $1.orig $1
+ fi
}
Replace "vi" with your favorite flavor of editor.
mkpatchorig() {
local diffopts
- for f in `find . -name '*.orig' | sed s,^\./,,`
- do
- case `echo $f | sed 's,.orig$,,;s,.*\.,,'` in
- c) diffopts=-p ;;
+ for f in `find . -name '*.orig' | sed s,^\./,,`
+ do
+ case `echo $f | sed 's,.orig$,,;s,.*\.,,'` in
+ c) diffopts=-p ;;
pod) diffopts='-F^=' ;;
*) diffopts= ;;
- esac
- diff -du $diffopts $f `echo $f | sed 's,.orig$,,'`
- done
+ esac
+ diff -du $diffopts $f `echo $f | sed 's,.orig$,,'`
+ done
}
This function produces patches which include enough context to make
=head2 Perlbug administration
-There is a single remote administrative interface for modifying bug status,
-category, open issues etc. using the B<RT> I<bugtracker> system, maintained
-by I<Robert Spier>. Become an administrator, and close any bugs you can get
+There is a single remote administrative interface for modifying bug status,
+category, open issues etc. using the B<RT> bugtracker system, maintained
+by Robert Spier. Become an administrator, and close any bugs you can get
your sticky mitts on:
- http://rt.perl.org
-
-The bugtracker mechanism for B<perl5> bugs in particular is at:
-
- http://bugs6.perl.org/perlbug
+ http://rt.perl.org/rt3/
To email the bug system administrators:
"perlbug-admin" <perlbug-admin@perl.org>
-
=head2 Submitting patches
Always submit patches to I<perl5-porters@perl.org>. If you're
maint branch. Only patches that survive the heat of the development
branch get applied to maintenance versions.
-Your patch should also update the documentation and test suite. See
-L<Writing a test>.
+Your patch should update the documentation and test suite. See
+L<Writing a test>. If you have added or removed files in the distribution,
+edit the MANIFEST file accordingly, sort the MANIFEST file using
+C<make manisort>, and include those changes as part of your patch.
Patching documentation also follows the same order: if accepted, a patch
is first applied to B<development>, and if relevant then it's backported
Perl (if you can't get Perl to work, send mail to the address
I<perlbug@perl.org> or I<perlbug@perl.com>). Reporting bugs through
I<perlbug> feeds into the automated bug-tracking system, access to
-which is provided through the web at http://bugs.perl.org/ . It
+which is provided through the web at http://rt.perl.org/rt3/ . It
often pays to check the archives of the perl5-porters mailing list to
see whether the bug you're reporting has been reported before, and if
so whether it was considered a bug. See above for the location of
The CPAN testers ( http://testers.cpan.org/ ) are a group of
volunteers who test CPAN modules on a variety of platforms. Perl
-Smokers ( http://archives.develooper.com/daily-build@perl.org/ )
-automatically tests Perl source releases on platforms with various
+Smokers ( http://www.nntp.perl.org/group/perl.daily-build )
+automatically test Perl source releases on platforms with various
configurations. Both efforts welcome volunteers.
It's a good idea to read and lurk for a while before chipping in.
=item The perl5-porters FAQ
-This should be available from http://simon-cozens.org/writings/p5p-faq ;
-alternatively, you can get the FAQ emailed to you by sending mail to
-C<perl5-porters-faq@perl.org>. It contains hints on reading perl5-porters,
-information on how perl5-porters works and how Perl development in general
-works.
+This should be available from http://dev.perl.org/perl5/docs/p5p-faq.html .
+It contains hints on reading perl5-porters, information on how
+perl5-porters works and how Perl development in general works.
=back
analysis of Java code, but later the cpd part of it was extended to
parse also C and C++.
-Download the pmd-X.y.jar from the SourceForge site, and then run
-it on source code thusly:
+Download the pmd-bin-X.Y.zip () from the SourceForge site, extract the
+pmd-X.Y.jar from it, and then run that on source code thusly:
java -cp pmd-X.Y.jar net.sourceforge.pmd.cpd.CPD --minimum-tokens 100 --files /some/where/src --language c > cpd.txt
The first one explicitly passes in the context, which is needed for e.g.
threaded builds. The second one does that implicitly; do not get them
-mixed. If you are not passing in a aTHX_, you will need to do a dTHX as
-the first thing in the function.
+mixed. If you are not passing in a aTHX_, you will need to do a dTHX
+(or a dVAR) as the first thing in the function.
See L<perlguts/"How multiple interpreters and concurrency are supported">
for further discussion about context.
Introducing (non-read-only) globals
Do not introduce any modifiable globals, truly global or file static.
-They are bad form and break multithreading. The right way is to
-introduce them as new interpreter variables, see F<intrpvar.h> (at the
-very end for binary compatibility).
+They are bad form and complicate multithreading and other forms of
+concurrency. The right way is to introduce them as new interpreter
+variables, see F<intrpvar.h> (at the very end for binary compatibility).
Introducing read-only (const) globals is okay, as long as you verify
with e.g. C<nm libperl.a|egrep -v ' [TURtr] '> (if your C<nm> has
static const char etc[] = "...";
-If you want to have arrays of static strings, note carefully
+If you want to have arrays of constant strings, note carefully
the right combination of C<const>s:
static const char * const yippee[] =
{"hi", "ho", "silver"};
+There is a way to completely hide any modifiable globals (they are all
+moved to heap), the compilation setting C<-DPERL_GLOBAL_STRUCT_PRIVATE>.
+It is not normally used, but can be used for testing, read more
+about it in L<perlguts/"Background and PERL_IMPLICIT_CONTEXT">.
+
=item *
Not exporting your new function
The new shiny result of either genuine new functionality or your
arduous refactoring is now ready and correctly exported. So what
-could possibly be wrong?
+could possibly go wrong?
Maybe simply that your function did not need to be exported in the
first place. Perl has a long and not so glorious history of exporting
Use the Configure C<-Dgccansipedantic> flag to enable the gcc
C<-ansi -pedantic> flags which enforce stricter ANSI rules.
+If using the C<gcc -Wall> note that not all the possible warnings
+(like C<-Wunitialized>) are given unless you also compile with C<-O>.
+
+Note that if using gcc, starting from Perl 5.9.5 the Perl core source
+code files (the ones at the top level of the source code distribution,
+but not e.g. the extensions under ext/) are automatically compiled
+with as many as possible of the C<-std=c89>, C<-ansi>, C<-pedantic>,
+and a selection of C<-W> flags (see cflags.SH).
+
Also study L<perlport> carefully to avoid any bad assumptions
-about the operating system, filesystem, and so forth.
+about the operating system, filesystems, and so forth.
-You may once in a while try a "make miniperl" to see whether we
+You may once in a while try a "make microperl" to see whether we
can still compile Perl with just the bare minimum of interfaces.
+(See README.micro.)
Do not assume an operating system indicates a certain compiler.
Assuming one can dereference any type of pointer for any type of data
char *p = ...;
- long pony = *p;
+ long pony = *p; /* BAD */
Many platforms, quite rightly so, will give you a core dump instead
of a pony if the p happens not be correctly aligned.
Lvalue casts
- (int)*p = ...;
+ (int)*p = ...; /* BAD */
Simply not portable. Get your lvalue to be of the right type,
-or maybe use temporary variables.
+or maybe use temporary variables, or dirty tricks with unions.
+
+=item *
+
+Assume B<anything> about structs (especially the ones you
+don't control, like the ones coming from the system headers)
+
+=over 8
+
+=item *
+
+That a certain field exists in a struct
+
+=item *
+
+That no other fields exist besides the ones you know of
+
+=item *
+
+That a field is of certain signedness, sizeof, or type
+
+=item *
+
+That the fields are in a certain order
+
+=over 8
+
+=item *
+
+While C guarantees the ordering specified in the struct definition,
+between different platforms the definitions might differ
+
+=back
+
+=item *
+
+That the sizeof(struct) or the alignments are the same everywhere
+
+=over 8
+
+=item *
+
+There might be padding bytes between the fields to align the fields -
+the bytes can be anything
+
+=item *
+
+Structs are required to be aligned to the maximum alignment required
+by the fields - which for native types is for usually equivalent to
+sizeof() of the field
+
+=back
+
+=back
=item *
Mixing #define and #ifdef
#define BURGLE(x) ... \
- #ifdef BURGLE_OLD_STYLE
+ #ifdef BURGLE_OLD_STYLE /* BAD */
... do it the old way ... \
#else
... do it the new way ... \
#ifdef SNOSH
...
- #else !SNOSH
+ #else !SNOSH /* BAD */
...
- #endif SNOSH
+ #endif SNOSH /* BAD */
-The #endif and #else cannot portably have anything after them. If you
-want to document what is going (which is a good idea especially if the
-branches are long), use (C) comments:
+The #endif and #else cannot portably have anything non-comment after
+them. If you want to document what is going (which is a good idea
+especially if the branches are long), use (C) comments:
#ifdef SNOSH
...
=item *
+Having a comma after the last element of an enum list
+
+ enum color {
+ CERULEAN,
+ CHARTREUSE,
+ CINNABAR, /* BAD */
+ };
+
+is not portable. Leave out the last comma.
+
+Also note that whether enums are implicitly morphable to ints
+varies between compilers, you might need to (int).
+
+=item *
+
Using //-comments
- // This function bamfoodles the zorklator.
+ // This function bamfoodles the zorklator. /* BAD */
That is C99 or C++. Perl is C89. Using the //-comments is silently
allowed by many C compilers but cranking up the ANSI C89 strictness
void zorklator()
{
int n = 3;
- set_zorkmids(n);
+ set_zorkmids(n); /* BAD */
int q = 4;
That is C99 or C++. Some C compilers allow that, but you shouldn't.
Introducing variables inside for()
- for(int i = ...; ...; ...)
+ for(int i = ...; ...; ...) { /* BAD */
That is C99 or C++. While it would indeed be awfully nice to have that
also in C89, to limit the scope of the loop variable, alas, we cannot.
int foo(char *s) { ... }
...
unsigned char *t = ...; /* Or U8* t = ... */
- foo(t);
+ foo(t); /* BAD */
While this is legal practice, it is certainly dubious, and downright
fatal in at least one platform: for example VMS cc considers this a
-fatal error. One cause for people often making this mistake is that
-a "naked char" and therefore dereferencing a "naked char pointer" have
-an undefined signedness: it depends on the compiler and the platform
-whether the result is signed or unsigned. For this very same reason
-using a 'char' as an array index is bad.
+fatal error. One cause for people often making this mistake is that a
+"naked char" and therefore dereferencing a "naked char pointer" have
+an undefined signedness: it depends on the compiler and the flags of
+the compiler and the underlying platform whether the result is signed
+or unsigned. For this very same reason using a 'char' as an array
+index is bad.
=item *
Macros that have string constants and their arguments as substrings of
the string constants
- #define FOO(n) printf("number = %d\n", n)
+ #define FOO(n) printf("number = %d\n", n) /* BAD */
FOO(10);
Pre-ANSI semantics for that was equivalent to
Using printf formats for non-basic C types
IV i = ...;
- printf("i = %d\n", i);
+ printf("i = %d\n", i); /* BAD */
While this might by accident work in some platform (where IV happens
to be an C<int>), in general it cannot. IV might be something larger.
configuration step in F<config.h>):
Uid_t who = ...;
- printf("who = %d\n", who);
+ printf("who = %d\n", who); /* BAD */
The problem here is that Uid_t might be not only not C<int>-wide
but it might also be unsigned, in which case large uids would be
=item *
-Using gcc brace groups
+Using gcc statement expressions
- val = ({...;...;...});
+ val = ({...;...;...}); /* BAD */
-While a nice extension, it's not portable.
+While a nice extension, it's not portable. The Perl code does
+admittedly use them if available to gain some extra speed
+(essentially as a funky form of inlining), but you shouldn't.
=item *
Testing for operating systems or versions when should be testing for features
- #ifdef __FOONIX__
+ #ifdef __FOONIX__ /* BAD */
foo = quux();
#endif
foo = quux();
#endif
-How does the HAS_QUUX become defined where it needs to be? Well, if
+How does the HAS_QUUX become defined where it needs to be? Well, if
Foonix happens to be UNIXy enought to be able to run the Configure
script, and Configure has been taught about detecting and testing
quux(), the HAS_QUUX will be correctly defined. In other platforms,
=back
+=head2 Problematic System Interfaces
+
+=over 4
+
+=item *
+
+malloc(0), realloc(0), calloc(0, 0) are nonportable. To be portable
+allocate at least one byte. (In general you should rarely need to
+work at this low level, but instead use the various malloc wrappers.)
+
+=item *
+
+snprintf() - the return type is unportable. Use my_snprintf() instead.
+
+=back
+
=head2 Security problems
Last but not least, here are various tips for safer coding.
is a good sign of these. Fixing these leaks is non-trivial,
unfortunately, but they must be fixed eventually.
+B<NOTE 4>: L<DynaLoader> will not clean up after itself completely
+unless Perl is built with the Configure option
+C<-Accflags=-DDL_UNLOAD_ALL_AT_EXIT>.
+
=head2 Rational Software's Purify
Purify is a commercial tool that is helpful in identifying
or 0xEFEFEFEF, you may be seeing the effect of the Poison() macros,
see L<perlclib>.
+=item *
+
+Under ithreads the optree is read only. If you want to enforce this, to check
+for write accesses from buggy code, compile with C<-DPL_OP_SLAB_ALLOC> to
+enable the OP slab allocator and C<-DPERL_DEBUG_READONLY_OPS> to enable code
+that allocates op memory via C<mmap>, and sets it read-only at run time.
+Any write access to an op results in a C<SIGBUS> and abort.
+
+This code is intended for development only, and may not be portable even to
+all Unix variants. Also, it is an 80% solution, in that it isn't able to make
+all ops read only. Specifically it
+
+=over
+
+=item 1
+
+Only sets read-only on all slabs of ops at C<CHECK> time, hence ops allocated
+later via C<require> or C<eval> will be re-write
+
+=item 2
+
+Turns an entire slab of ops read-write if the refcount of any op in the slab
+needs to be decreased.
+
+=item 3
+
+Turns an entire slab of ops read-write if any op from the slab is freed.
+
=back
+It's not possible to turn the slabs to read-only after an action requiring
+read-write access, as either can happen during op tree building time, so
+there may still be legitimate write access.
+
+However, as an 80% solution it is still effective, as currently it catches
+a write access during the generation of F<Config.pm>, which means that we
+can't yet build F<perl> with this enabled.
+
+=back
+
+
=head1 CONCLUSION
We've had a brief look around the Perl source, how to maintain quality
https://perl5.git.perl.org / perl5.git / blobdiff