1 # Copyright (C) 2007, Parrot Foundation.
4 =head1 Cage Cleaner Guide
6 From F<docs/project/roles_responsibilities.pod>:
8 Fixes failing tests, makes sure coding standards are implemented,
9 reviews documentation and examples. A class of tickets in the
10 tracking system (Trac) has been created for use by this
11 group. This is an entry level position, and viewed as a good way
12 to get familiar with parrot internals.
14 =head1 Testing Parrot after making a code cleaning change
16 To be really I<really> sure you're not breaking anything after doing code
17 cleaning or attending to the newspaper at the bottom of our Parrot's cage
18 here are is the process I (ptc) go through before committing a new change:
20 make realclean > make_realclean.out 2>&1
21 perl Configure.pl > perl_configure.out 2>&1
22 make buildtools_tests > buildtools_tests.out 2>&1
23 make test > make_test.out 2>&1
25 Then I diff the C<*.out> files with copies of the C<*.out> files I made on a
26 previous test run. If the diffs show nothing nasty is happening, you can be
27 more sure that you've not broken anything and can commit the change. Then
28 rename the C<*.out> files to something like C<*.out.old> so that you
29 maintain reasonably up to date references for the diffs.
31 This process should be put into a script and stored somewhere...
33 =head1 Parrot Cage Cleaners high-level goals
35 =head2 Smoke testing on many platforms with many compilers
37 The more platforms we have, the more likely we are to find portability
38 problems. Parrot has to be the most portable thing we've created.
40 More platforms also means more compilers. Maybe your DEC compiler
41 is more picky than gcc, and spews more warnings. Good! More
42 opportunities for cleaning!
46 C<icc> is the Intel C/C++ Compiler and is available for free for
47 non-commercial use. To use C<icc> to build parrot, use the following
48 arguments to C<Configure.pl>:
50 perl Configure.pl --cc=icc --ld=icc
52 (courtesy of Steve Peters, C<steve at fisharerojo dot org>).
54 =head2 Compiler pickiness
56 Use as many compiler warnings as we possibly can. The more warnings
57 we enable, the less likely something will pass the watchful eye of
60 Note that warnings may not just be -W flags. Some warnings in gcc
61 only show up when optimization is enabled.
65 Splint (L<http://www.splint.org>) is a very very picky lint tool, and
66 setup and configuration is a pain. Andy has tried to get Perl 5
67 running under it nicely, but has met with limited success. Maybe
68 the Parrot will be nicer.
72 Sun has made its dev tools freely available at
73 L<http://developers.sun.com/prodtech/cc/>. Its lint is the best one
74 out there, except from Gimpel's FlexeLint
75 (L<http://www.gimpel.com/html/flex.htm>) which costs many dollars.
77 =head2 Enforcing coding standards, naming conventions, etc
81 =item * Automatic standards checking
83 The docs in F<filename here> explains what our code should look
84 like. Write something that automatically validates it in a .t file.
86 =item * C<const> checking
88 Declaring variables as C<const> wherever possible lets the compiler
89 do lots of checking that wouldn't normally be possible. Walk the
90 source code adding the C<const> qualifier wherever possible. The
91 biggest bang is always in passing pointers into functions.
95 =head2 Why consting is good
97 In Perl, we have the C<use constant> pragma to define unchanging
98 values. The L<Readonly> module extends this to allow arrays and
99 hashes to be non-modifiable as well.
101 In C, we have C<const> numbers and pointers, and using them wherever
102 possible lets us put safety checks in our code, and the compiler
103 will watch over our shoulders.
105 =head3 C<const> numbers
107 The easiest way to use the C<const> qualifier is by flagging numbers
108 that are set at the top of a block. For example:
112 max_elements = nusers * ELEMENTS_PER_USER;
116 array[max_elements++] = n;
117 /* but you really meant array[max_elements] = n++; */
119 Adding a C<const> qualifier means you can't accidentally modify
122 const int max_elements = nusers * ELEMENTS_PER_USER;
124 =head3 C<const> pointers
126 If a pointer is qualified as const, then its contents cannot be
127 modified. This lets the compiler protect you from doing naughty
130 Here are two examples for functions you're familiar with:
132 int strlen( const char *str );
133 void memset( char *ptr, char value, int length );
135 In the case of C<strlen>, the caller is guaranteed that any string
136 passed in won't be modified. How terrible it would be if it was
137 possible for C<strlen> to modify what gets passed in!
139 The const on C<strlen>'s parameter also lets the compiler know that
140 C<strlen> can't be initializing what's passed in. For example:
142 char buffer[ MAX_LEN ];
144 int n = strlen( buffer );
146 The compiler knows that C<buffer> hasn't been initialized, and
147 that C<strlen> can't be initializing it, so the call to C<strlen>
148 is on an uninitialized value.
150 Without the const, the compiler assumes that the contents of any
151 pointer are getting initialized or modified.
153 =head3 C<const> arrays
155 Consting arrays makes all the values in the array non-modifiable.
157 const int days_per_month[] =
158 { 31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31 };
160 You don't want to be able to do C<days_per_month[1] = 4;>, right?
161 (We'll ignore that about 25% of the time you want C<days_per_month[1]>
164 =head3 Mixing C<consts>
166 Combining C<const>s on a pointer and its contents can get confusing.
167 It's important to know on which side of the asterisk that the
170 To the left of the asterisk, the characters are constant. To the
171 right of the asterisk, the pointer is constant.
173 Note the difference between a pointer to constant characters:
175 /* Pointer to constant characters */
176 const char *str = "Don't change me.";
177 str++; /* legal, now points at "o" */
178 *str = "x"; /* not legal */
180 and a constant pointer to characters:
182 /* Constant pointer to characters */
183 char * const str = buffer;
184 str++; /* not legal */
185 *str = 'x'; /* buffer[0] is now 'x' */
187 Note the difference between which side of the asterisk that the
190 You can also combine the two, with a constant pointer to constant
193 const char * const str = "Don't change me";
195 or even an array of constant pointers to constant characters:
197 const char * const days[] =
198 { "Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat" };
200 If you see a declaration you don't understand, use C<cdecl>. It's
201 standard in many C compiler suites, and is freely available around
205 Type `help' or `?' for help
206 cdecl> explain const char * str;
207 declare str as pointer to const char
208 cdecl> explain char * const str;
209 declare str as const pointer to char
211 =head2 Decreasing the amount of repeated code
213 PMD (L<http://pmd.sourceforge.net/>) has been used on C code, even
214 though it's a Java tool. It looks for repeated strings of tokens
215 that are candidates for either functions or macros.
221 pmd [directory] [report format] [ruleset file]
223 To generate html output of unused code within parrot use:
225 pmd . html rulesets/unusedcode.xml > unused_code.html
227 Also distributed with PMD is the CPD (Copy/Paste Detector) which finds
228 duplicate code. An easy way to get started with this tool is to use the gui
229 (cpdgui). Set the root source directory to your parrot working directory,
230 and choose the C<by extension...> option of the C<Language:> menu. Then put
231 C<.c> in the C<Extension:> box and click C<Go>.
233 =head2 Automated source macros
235 Perl5 has a lot of good source management techniques that we can use.
239 =item * Macro for interp argument
241 A macro for declaring the interpreter argument, and maybe a macro
244 BTW, our Perl experience teaches us that somebody is going to want
245 to make the interpreter a C++ object for Windows environments, and
246 it wouldn't hurt to make that possible, or at least work in that
247 direction, as long as clarity doesn't suffer.
249 =item * Parrot_xxx macros
251 Automated processing that would make a macro to let us write
253 somefunc(interp,a,b,c)
257 Parrot_somefunc(interp,a,b,c)
259 for namespace cleanup. This is straight out of F<embed.fnc> and
264 =head2 Automated generation of C headers
266 This has started significantly with the F<headerizer.pl> program.
267 Right now, it extracts the function headers correctly, but now I
268 have to have it create the F<.h> files.
270 =head2 Creating automated code checking tools
272 =head2 Documenting function behavior and structure members
274 =head2 Developing coverage tools
276 =head2 Automatically running the coverage tools
278 =head2 Run on many different C compilers
280 Most of Andy's work right now is with GCC 4.2 on Linux. We need
283 =head2 Run under valgrind
285 Valgrind (L<http://valgrind.org/>) is a profiler/debugger most notable
286 for the way it magically monitors memory accesses and management.
288 To run parrot under Valgrind, the following argument set should be helpful:
290 valgrind --num-callers=500 \
291 --leak-check=full --leak-resolution=high --show-reachable=yes \
294 (adapted from a post to C<parrot-porters> by chromatic).
300 vsoni: there seems to be some dead code/feature....I had a chat
301 with leo and I am going to send and email to p6i for deprecation
302 of certain old features
304 =head2 Help other contributors hack their patches into Parrot-style industrial-strength C code.
306 From chip's comment at
307 L<http://www.oreillynet.com/onlamp/blog/2006/07/calling_for_parrot_janitors.html>
309 We've just had contributed an improved register allocation
310 implementation, but since the contributor is new to Parrot,
311 there are some style and coding standards issues that need to
312 be worked out. It'd be great if a Cage Cleaner could step up
313 and help our new contributor bang the code into Parrotish form.
315 =head2 Remove usage of deprecated features
317 F<DEPRECATED.pod> lists features that are deprecated but not yet removed;
318 A Trac ticket will document how this deprecated feature is to be replaced.
319 Help prepare for the actual removal of the feature by replacing its usage.
321 =head2 Clean up skipped tests
323 Parrot has too many skipped tests. Pick a test file with a skipped test,
324 disable the skip() line, then make it pass. The Parrot code may not compile,
325 or you may have to modify it to bring it up to date. The test may not even be
326 useful anymore; we won't know until you try.
328 If you can make it pass, great!
330 If you can make it run, great! Make it a TODO test instead.
332 If neither, please report your findings so that everyone can decide what to do.
334 =head1 Handy configuration tips
336 =head2 Subversion configuration and automatic properties
338 There is an example C<.subversion/config> file in
339 F<editor/subversion_config> which is useful in automatically setting the
340 appropriate Subversion properties relevant to Parrot on addition of new
343 =head2 Displaying trailing whitespace in vim and emacs
347 Add this to your C<.vimrc>:
350 set listchars=trail:-,tab:\.\
352 B<NOTE>: there is a space character after the last backslash. It is very
355 Contributed by Jerry Gay <jerry dot gay at gmail dot com>.
359 Add this to your C<.emacs>:
361 (setq-default show-trailing-whitespace t)
363 Emacs 22 users can highlight tabs like this:
365 (global-hi-lock-mode 1)
366 (highlight-regexp "\t")
368 Contributed by Eric Hanchrow <offby1 at blarg dot net>.
372 Paul Cochrane a.k.a. ptc; original document by Andy Lester
376 F<docs/project/roles_responsibilities.pod>, F<RESPONSIBLE_PARTIES>
377 and the list of Cage items in Trac L<http://trac.parrot.org>.