=head1 Parrot Cage Cleaners high-level goals

=head2 Smoke testing on many platforms with many compilers

The more platforms we have, the more likely we are to find portability
problems.  Parrot has to be the most portable thing we've created.

More platforms also means more compilers.  Maybe your DEC compiler
is more picky than gcc, and spews more warnings.  Good!  More
opportunities for cleaning!

=head2 Compiler pickiness

Use as many compiler warnings as we possibly can.  The more warnings
we enable, the less likely something will pass the watchful eye of
the compiler.

Note that warnings may not just be -W flags.  Some warnings in gcc
only show up when optimization is enabled.

=head2 splint

Splint (L<http://www.splint.org>) is a very very picky lint tool, and
setup and configuration is a pain.  Andy has tried to get Perl 5
running under it nicely, but has met with limited success.  Maybe
the Parrot will be nicer.

=over 4

=item * Create a F<make> target for splint.

Make splint run against all the F<*.c> files.

=item * Make a reasonable set of rules for splint.

splint spews many many errors by default.  Take a look at the
Makefile that perl5 has for the start of some rules that Andy worked
on for the perl5 code.

=back

=head2 Solaris lint

Sun has made its dev tools freely available at
L<http://developers.sun.com/prodtech/cc/>.  Its lint is the best one
out there, except from Gimpel's FlexeLint
(L<http://www.gimpel.com/html/flex.htm>) which costs many dollars.

=over 4

=item * Create a F<make> target for lint.

Make lint run against all the F<*.c> files.

=item * Make a reasonable set of rules for lint.

Andy has a pretty decent set of rules for perl5's code in that
project's Makefile.  Take a look at those for a start.

=back

=head2 Enforcing coding standards, naming conventions, etc

=over 4

=item * Automatic standards checking

The docs in F<filename here> explains what our code should look
like.  Write something that automatically validates it in a .t file.

=item * C<const> checking

Declaring variables as C<const> wherever possible lets the compiler
do lots of checking that wouldn't normally be possible.  Walk the
source code adding the C<const> qualifier wherever possible.  The
biggest bang is always in passing pointers into functions.

=item * C<const> explaining

The description above is pretty sparse.  A good description of
C<const> and its benefit would be helpful for newcomers.

=back

=head2 Decreasing the amount of repeated code

PMD (L<http://pmd.sourceforge.net/>) has been used on C code, even
though it's a Java tool.  It looks for repeated strings of tokens
that are candidates for either functions or macros.

=head2 Automated source macros

Perl5 has a lot of good source management techniques that we can use.

=over 4

=item * Standardizing on "interp"

Standarizing on "interp" or maybe even "intr" as the interpreter
variable, for brevity & consistency

=item * Macro for interp argument

A macro for declaring the interpreter argument, and maybe a macro
for passing it

BTW, our Perl experience teaches us that somebody is going to want
to make the interpreter a C++ object for Windows environments, and
it wouldn't hurt to make that possible, or at least work in that
direction, as long as clarity doesn't suffer.

=item * Redo CONTEXT(interp->ctx)->foo

Eliminating the C<< CONTEXT(interp->ctx)->foo >> usage in favor of
the much simpler C<< interp->ctx->foo >>, or similar simplification.

=item * Parrot_xxx macros

Automated processing that would make a macro to let us write

    somefunc(interp,a,b,c)

while the linkage is

    Parrot_somefunc(interp,a,b,c)

for namespace cleanup.  This is straight out of F<embed.fnc> and
F<proto.h> in Perl5.

=back

=head2 Automated generation of C headers

This has started significantly with the F<headerizer.pl> program.
Right now, it extracts the function headers correctly, but now I
have to have it create the F<.h> files.

=head2 Improve low-level code quality

=over 4

=item * Fix symbol table namespace pollution

Extern functions and variables must have names that begin with C<Parrot> .

=item * Fix non-symbol-table namespace pollution in public headers

Public headers are the ones in C<include/parrot> directory.  These are
included by embedders and extenders.  They must not declare or define any
symbol that isn't clearly Parrot-specific.  Prefixing symbols with C<Parrot>
or C<PARROT> is the easiest & safest way, but it can lead to a lot of
verbosity, so Chip is willing to entertain exceptions or new conventions.

It's OK for public headers might have non-public parts protected with
C<#ifdef PARROT_IN_CORE>.  Those non-public parts might #define shorter
versions of the public symbols, e.g. C<#define foo Parrot_foo>.

=back

=head2 Creating automated code checking tools

=head2 Documenting function behavior and structure members

=head2 Developing coverage tools

=head2 Automatically running the coverage tools

=head2 Run on many different C compilers

Most of Andy's work right now is with GCC 4.2 on Linux.  We need
many more.

=head2 Run under valgrind

Valgrind (L<http://valgrind.org/>) is a profiler/debugger most notable
for the way it magically monitors memory accesses and management.

=over 4

=item * Make a "make valgrind" target

=back

=head2 Run under Coverity Prevent

Coverity already runs Prevent on the Perl 5 source.  Let's get
Parrot running under it, too. L<http://scan.coverity.com/>

=head2 IMCC cleanup

From #parrot:

    vsoni: there seems to be some dead code/feature....I had a chat
    with leo and I am going to send and email to p6i for deprecation
    of certain old features

=head2 Help other contributors hack their patches into Parrot-style industrial-strength C code.

From chip's comment at
L<http://www.oreillynet.com/onlamp/blog/2006/07/calling_for_parrot_janitors.html>

    We've just had contributed an improved register allocation
    implementation, but since the contributor is new to Parrot,
    there are some style and coding standards issues that need to
    be worked out. It'd be great if a Cage Cleaner could step up
    and help our new contributor bang the code into Parrotish form.

=head2 Fix usage of deprecated features

=over 4

=back

=head2 Clean up skipped tests

Parrot has too many skipped tests.  Pick a test file with a skipped test,
disable the skip() line, then make it pass.  The Parrot code may not compile,
or you may have to modify it to bring it up to date.  The test may not even be
useful anymore; we won't know until you try.

If you can make it pass, great!

If you can make it run, great!  Make it a TODO test instead.

If neither, please report your findings so that everyone can decide what to do.

=head1 See Also

Also look at F<docs/BROKEN.pod>, F<docs/ROADMAP.pod>, and
the list of Cage items on RT: L<http://xrl.us/owsd> (Link to rt.perl.org)
