Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 416 lines (267 sloc) 13.216 kb
10a5214 @ayardley Added DESCRIPTION and upcased '=head1' tags.
ayardley authored
1 # Copyright (C) 2007-2012, Parrot Foundation.
fc8fec0 @paultcochrane [docs] Added the very beginnings of a cage cleaners guide.
paultcochrane authored
2
10a5214 @ayardley Added DESCRIPTION and upcased '=head1' tags.
ayardley authored
3 =pod
4
5 =head1 NAME
6
e1ebff5 @ayardley Fixed typo.
ayardley authored
7 docs/project/cage_cleaners_guide.pod - Cage Cleaner Guide.
10a5214 @ayardley Added DESCRIPTION and upcased '=head1' tags.
ayardley authored
8
9 =head1 DESCRIPTION
fc8fec0 @paultcochrane [docs] Added the very beginnings of a cage cleaners guide.
paultcochrane authored
10
ab91e2d @bschmalhofer Move roles_responsibilities.pod
bschmalhofer authored
11 From F<docs/project/roles_responsibilities.pod>:
fc8fec0 @paultcochrane [docs] Added the very beginnings of a cage cleaners guide.
paultcochrane authored
12
10a5214 @ayardley Added DESCRIPTION and upcased '=head1' tags.
ayardley authored
13 Fixes failing tests, makes sure coding standards are implemented,
14 reviews documentation and examples. A class of tickets in the
15 tracking system (Trac) has been created for use by this
16 group. This is an entry level position, and viewed as a good way
17 to get familiar with parrot internals.
fc8fec0 @paultcochrane [docs] Added the very beginnings of a cage cleaners guide.
paultcochrane authored
18
10a5214 @ayardley Added DESCRIPTION and upcased '=head1' tags.
ayardley authored
19 =head1 TESTING PARROT AFTER MAKING A CODE CLEANING CHANGE
ea3ce6e @paultcochrane [docs] Added some notes on the processes I use as a Cage Cleaner to test
paultcochrane authored
20
21 To be really I<really> sure you're not breaking anything after doing code
22 cleaning or attending to the newspaper at the bottom of our Parrot's cage
23 here are is the process I (ptc) go through before committing a new change:
24
25 make realclean > make_realclean.out 2>&1
26 perl Configure.pl > perl_configure.out 2>&1
27 make buildtools_tests > buildtools_tests.out 2>&1
28 make test > make_test.out 2>&1
29
30 Then I diff the C<*.out> files with copies of the C<*.out> files I made on a
31 previous test run. If the diffs show nothing nasty is happening, you can be
32 more sure that you've not broken anything and can commit the change. Then
33 rename the C<*.out> files to something like C<*.out.old> so that you
34 maintain reasonably up to date references for the diffs.
35
36 This process should be put into a script and stored somewhere...
37
10a5214 @ayardley Added DESCRIPTION and upcased '=head1' tags.
ayardley authored
38 =head1 PARROT CAGE CLEANERS' HIGH-LEVEL GOALS
5b63ade @paultcochrane [docs] Moved information about cage cleaners' high level goals from
paultcochrane authored
39
40 =head2 Smoke testing on many platforms with many compilers
41
42 The more platforms we have, the more likely we are to find portability
43 problems. Parrot has to be the most portable thing we've created.
44
45 More platforms also means more compilers. Maybe your DEC compiler
46 is more picky than gcc, and spews more warnings. Good! More
47 opportunities for cleaning!
48
f19eda0 @paultcochrane [docs] Added some notes to cage cleaners guide about building parrot …
paultcochrane authored
49 =head3 icc
50
51 C<icc> is the Intel C/C++ Compiler and is available for free for
52 non-commercial use. To use C<icc> to build parrot, use the following
53 arguments to C<Configure.pl>:
54
a1b2422 @Infinoid [doc] Apply documentation patch from Matt Kraai in RT #52026. kraai++
Infinoid authored
55 perl Configure.pl --cc=icc --ld=icc
f19eda0 @paultcochrane [docs] Added some notes to cage cleaners guide about building parrot …
paultcochrane authored
56
57 (courtesy of Steve Peters, C<steve at fisharerojo dot org>).
58
5b63ade @paultcochrane [docs] Moved information about cage cleaners' high level goals from
paultcochrane authored
59 =head2 Compiler pickiness
60
61 Use as many compiler warnings as we possibly can. The more warnings
62 we enable, the less likely something will pass the watchful eye of
63 the compiler.
64
9a504bf @paultcochrane [docs] mentioning the `--cage` configure option for more warnings
paultcochrane authored
65 Note that warnings may not just be -W flags. Some warnings in gcc only show
66 up when optimization is enabled. Use the C<--cage> option to
67 C<Configure.pl> to enable extra warnings which are useful in keeping the
68 cage clean.
5b63ade @paultcochrane [docs] Moved information about cage cleaners' high level goals from
paultcochrane authored
69
1bb39fa @paultcochrane [docs] adding notes to cage cleaners guide about FORTIFY_SOURCE
paultcochrane authored
70 =head3 gcc fortify source macro
71
72 In gcc it is possible to use the C<-D_FORTIFY_SOURCE=x> macro to provide "a
73 lightweight buffer overflow protection to some memory and string functions"
74 (C<http://gcc.gnu.org/ml/gcc-patches/2004-09/msg02055.html>). Checks are
75 implemented at compile- and run-time, thus it is also a good idea to run the
76 test suite in combination with this compiler option. There are two levels
77 to this macro usage:
78
79 =over 4
80
81 =item C<-D_FORTIFY_SOURCE=1>
82
83 This option is only available in combination with at least the C<-O1>
84 optimisation option and performs security checks that shouldn't change the
85 behaviour of conforming programs. Add this option to the C<--ccflags>
86 configure option to enable it, e.g.:
87
88 perl Configure.pl --ccflags="-D_FORTIFY_SOURCE=1 -O1"
89
90 =item C<-D_FORTIFY_SOURCE=2>
91
92 This option is only available in combination with at least the C<-O2>
93 optimisation option and performs more checking which might cause conforming
94 programs to fail. It can be added to the C<--ccflags> configure option and
95 used in combination with the C<--optimize> configure option like so:
96
97 perl Configure.pl --optimize --ccflags="-D_FORTIFY_SOURCE=2"
98
99 =back
100
5b63ade @paultcochrane [docs] Moved information about cage cleaners' high level goals from
paultcochrane authored
101 =head2 splint
102
103 Splint (L<http://www.splint.org>) is a very very picky lint tool, and
104 setup and configuration is a pain. Andy has tried to get Perl 5
105 running under it nicely, but has met with limited success. Maybe
106 the Parrot will be nicer.
107
108 =head2 Solaris lint
109
110 Sun has made its dev tools freely available at
111 L<http://developers.sun.com/prodtech/cc/>. Its lint is the best one
112 out there, except from Gimpel's FlexeLint
113 (L<http://www.gimpel.com/html/flex.htm>) which costs many dollars.
114
115 =head2 Enforcing coding standards, naming conventions, etc
116
117 =over 4
118
119 =item * Automatic standards checking
120
121 The docs in F<filename here> explains what our code should look
122 like. Write something that automatically validates it in a .t file.
123
124 =item * C<const> checking
125
126 Declaring variables as C<const> wherever possible lets the compiler
127 do lots of checking that wouldn't normally be possible. Walk the
128 source code adding the C<const> qualifier wherever possible. The
129 biggest bang is always in passing pointers into functions.
130
d40bd07 @coke pod cleanup
coke authored
131 =back
132
d9148bc @paultcochrane [docs] Moved the cage consting guide into the cage cleaners guide. R…
paultcochrane authored
133 =head2 Why consting is good
5b63ade @paultcochrane [docs] Moved information about cage cleaners' high level goals from
paultcochrane authored
134
d9148bc @paultcochrane [docs] Moved the cage consting guide into the cage cleaners guide. R…
paultcochrane authored
135 In Perl, we have the C<use constant> pragma to define unchanging
136 values. The L<Readonly> module extends this to allow arrays and
137 hashes to be non-modifiable as well.
5b63ade @paultcochrane [docs] Moved information about cage cleaners' high level goals from
paultcochrane authored
138
d9148bc @paultcochrane [docs] Moved the cage consting guide into the cage cleaners guide. R…
paultcochrane authored
139 In C, we have C<const> numbers and pointers, and using them wherever
140 possible lets us put safety checks in our code, and the compiler
141 will watch over our shoulders.
142
143 =head3 C<const> numbers
144
145 The easiest way to use the C<const> qualifier is by flagging numbers
146 that are set at the top of a block. For example:
147
148 int max_elements;
149
150 max_elements = nusers * ELEMENTS_PER_USER;
151
152 ...
153
154 array[max_elements++] = n;
155 /* but you really meant array[max_elements] = n++; */
156
157 Adding a C<const> qualifier means you can't accidentally modify
158 C<max_elements>.
159
160 const int max_elements = nusers * ELEMENTS_PER_USER;
161
162 =head3 C<const> pointers
163
164 If a pointer is qualified as const, then its contents cannot be
165 modified. This lets the compiler protect you from doing naughty
166 things to yourself.
167
168 Here are two examples for functions you're familiar with:
169
170 int strlen( const char *str );
171 void memset( char *ptr, char value, int length );
172
173 In the case of C<strlen>, the caller is guaranteed that any string
174 passed in won't be modified. How terrible it would be if it was
175 possible for C<strlen> to modify what gets passed in!
176
177 The const on C<strlen>'s parameter also lets the compiler know that
178 C<strlen> can't be initializing what's passed in. For example:
179
180 char buffer[ MAX_LEN ];
181
182 int n = strlen( buffer );
183
184 The compiler knows that C<buffer> hasn't been initialized, and
185 that C<strlen> can't be initializing it, so the call to C<strlen>
186 is on an uninitialized value.
187
188 Without the const, the compiler assumes that the contents of any
189 pointer are getting initialized or modified.
190
191 =head3 C<const> arrays
192
193 Consting arrays makes all the values in the array non-modifiable.
194
195 const int days_per_month[] =
196 { 31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31 };
197
198 You don't want to be able to do C<days_per_month[1] = 4;>, right?
199 (We'll ignore that about 25% of the time you want C<days_per_month[1]>
200 to be 29.)
201
202 =head3 Mixing C<consts>
203
204 Combining C<const>s on a pointer and its contents can get confusing.
205 It's important to know on which side of the asterisk that the
206 C<const> lies.
207
208 To the left of the asterisk, the characters are constant. To the
209 right of the asterisk, the pointer is constant.
210
211 Note the difference between a pointer to constant characters:
212
213 /* Pointer to constant characters */
214 const char *str = "Don't change me.";
215 str++; /* legal, now points at "o" */
216 *str = "x"; /* not legal */
217
218 and a constant pointer to characters:
219
220 /* Constant pointer to characters */
221 char * const str = buffer;
222 str++; /* not legal */
223 *str = 'x'; /* buffer[0] is now 'x' */
224
225 Note the difference between which side of the asterisk that the
226 C<const> is on.
227
228 You can also combine the two, with a constant pointer to constant
229 characters:
230
231 const char * const str = "Don't change me";
232
233 or even an array of constant pointers to constant characters:
234
235 const char * const days[] =
236 { "Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat" };
237
238 If you see a declaration you don't understand, use C<cdecl>. It's
239 standard in many C compiler suites, and is freely available around
240 the net.
241
242 $ cdecl
243 Type `help' or `?' for help
244 cdecl> explain const char * str;
245 declare str as pointer to const char
246 cdecl> explain char * const str;
6a94dc7 @particle [docs]: fix pod error
particle authored
247 declare str as const pointer to char
5b63ade @paultcochrane [docs] Moved information about cage cleaners' high level goals from
paultcochrane authored
248
249 =head2 Decreasing the amount of repeated code
250
251 PMD (L<http://pmd.sourceforge.net/>) has been used on C code, even
252 though it's a Java tool. It looks for repeated strings of tokens
253 that are candidates for either functions or macros.
254
ca4cab1 @paultcochrane [docs] Added a note on how to use pmd to search for unused code in pa…
paultcochrane authored
255 =head3 PMD usage
256
257 General usage:
258
259 pmd [directory] [report format] [ruleset file]
260
261 To generate html output of unused code within parrot use:
262
263 pmd . html rulesets/unusedcode.xml > unused_code.html
264
0ea687b @paultcochrane [docs] Added notes on how to use the GUI of te copy and paste detecto…
paultcochrane authored
265 Also distributed with PMD is the CPD (Copy/Paste Detector) which finds
266 duplicate code. An easy way to get started with this tool is to use the gui
267 (cpdgui). Set the root source directory to your parrot working directory,
268 and choose the C<by extension...> option of the C<Language:> menu. Then put
269 C<.c> in the C<Extension:> box and click C<Go>.
270
5b63ade @paultcochrane [docs] Moved information about cage cleaners' high level goals from
paultcochrane authored
271 =head2 Automated source macros
272
273 Perl5 has a lot of good source management techniques that we can use.
274
275 =over 4
276
277 =item * Macro for interp argument
278
279 A macro for declaring the interpreter argument, and maybe a macro
280 for passing it
281
282 BTW, our Perl experience teaches us that somebody is going to want
283 to make the interpreter a C++ object for Windows environments, and
284 it wouldn't hurt to make that possible, or at least work in that
285 direction, as long as clarity doesn't suffer.
286
287 =item * Parrot_xxx macros
288
289 Automated processing that would make a macro to let us write
290
291 somefunc(interp,a,b,c)
292
293 while the linkage is
294
295 Parrot_somefunc(interp,a,b,c)
296
297 for namespace cleanup. This is straight out of F<embed.fnc> and
298 F<proto.h> in Perl5.
299
300 =back
301
302 =head2 Automated generation of C headers
303
304 This has started significantly with the F<headerizer.pl> program.
305 Right now, it extracts the function headers correctly, but now I
306 have to have it create the F<.h> files.
307
308 =head2 Creating automated code checking tools
309
310 =head2 Documenting function behavior and structure members
311
312 =head2 Developing coverage tools
313
314 =head2 Automatically running the coverage tools
315
316 =head2 Run on many different C compilers
317
318 Most of Andy's work right now is with GCC 4.2 on Linux. We need
319 many more.
320
321 =head2 Run under valgrind
322
323 Valgrind (L<http://valgrind.org/>) is a profiler/debugger most notable
324 for the way it magically monitors memory accesses and management.
325
2f57b86 @paultcochrane [docs] Added chromatic++'s valgrind argument set to the docs for future
paultcochrane authored
326 To run parrot under Valgrind, the following argument set should be helpful:
327
328 valgrind --num-callers=500 \
329 --leak-check=full --leak-resolution=high --show-reachable=yes \
330 parrot --leak-test
331
332 (adapted from a post to C<parrot-porters> by chromatic).
333
4c5d82d @leto [doc][ci skip] Add a note to the cage cleaner guide about running par…
leto authored
334 See also the F<tools/dev/vgp> and F<tools/dev/parrot.supp> files. C<vgp>
335 is a wrapper around running parrot with valgrind and uses a custom set
336 of "valgrind suppressions".
337
5b63ade @paultcochrane [docs] Moved information about cage cleaners' high level goals from
paultcochrane authored
338 =head2 IMCC cleanup
339
340 From #parrot:
341
342 vsoni: there seems to be some dead code/feature....I had a chat
343 with leo and I am going to send and email to p6i for deprecation
344 of certain old features
345
346 =head2 Help other contributors hack their patches into Parrot-style industrial-strength C code.
347
348 From chip's comment at
349 L<http://www.oreillynet.com/onlamp/blog/2006/07/calling_for_parrot_janitors.html>
350
351 We've just had contributed an improved register allocation
352 implementation, but since the contributor is new to Parrot,
353 there are some style and coding standards issues that need to
354 be worked out. It'd be great if a Cage Cleaner could step up
355 and help our new contributor bang the code into Parrotish form.
356
30d12df @coke [docs] - more info on deprecation...
coke authored
357 =head2 Remove usage of deprecated features
358
f4fcd0e @leto Merge branch 'leto/deprecations_as_data'
leto authored
359 The F<api.yaml> file lists features that are deprecated but not yet
7f1d5ca @leto [doc] DEPRECATED.pod is now called docs/changes/api.yaml
leto authored
360 removed, as well as experimental features. A Trac ticket will document how
361 this deprecated feature is to be replaced. Help prepare for the actual removal
362 of the feature by replacing its usage.
5b63ade @paultcochrane [docs] Moved information about cage cleaners' high level goals from
paultcochrane authored
363
364 =head2 Clean up skipped tests
365
366 Parrot has too many skipped tests. Pick a test file with a skipped test,
367 disable the skip() line, then make it pass. The Parrot code may not compile,
368 or you may have to modify it to bring it up to date. The test may not even be
369 useful anymore; we won't know until you try.
370
371 If you can make it pass, great!
372
373 If you can make it run, great! Make it a TODO test instead.
374
375 If neither, please report your findings so that everyone can decide what to do.
376
10a5214 @ayardley Added DESCRIPTION and upcased '=head1' tags.
ayardley authored
377 =head1 HANDY CONFIGURATION TIPS
55c9e3f @paultcochrane [docs] Added settings advice from particle++ and offby1++ about vim a…
paultcochrane authored
378
379 =head2 Displaying trailing whitespace in vim and emacs
380
381 =head3 Vim
382
383 Add this to your C<.vimrc>:
384
385 set list
386 set listchars=trail:-,tab:\.\
387
388 B<NOTE>: there is a space character after the last backslash. It is very
389 important!
390
391 Contributed by Jerry Gay <jerry dot gay at gmail dot com>.
392
393 =head3 Emacs
394
395 Add this to your C<.emacs>:
396
397 (setq-default show-trailing-whitespace t)
398
399 Emacs 22 users can highlight tabs like this:
400
401 (global-hi-lock-mode 1)
402 (highlight-regexp "\t")
403
404 Contributed by Eric Hanchrow <offby1 at blarg dot net>.
405
fc8fec0 @paultcochrane [docs] Added the very beginnings of a cage cleaners guide.
paultcochrane authored
406 =head1 AUTHOR
407
5e25476 @paultcochrane [docs] Giving Andy Lester credit for the original document in the AUT…
paultcochrane authored
408 Paul Cochrane a.k.a. ptc; original document by Andy Lester
fc8fec0 @paultcochrane [docs] Added the very beginnings of a cage cleaners guide.
paultcochrane authored
409
410 =head1 SEE ALSO
411
ab91e2d @bschmalhofer Move roles_responsibilities.pod
bschmalhofer authored
412 F<docs/project/roles_responsibilities.pod>, F<RESPONSIBLE_PARTIES>
1408b09 @perlpilot new github cage url
perlpilot authored
413 and the list of Cage items in github L<https://github.com/parrot/parrot/issues?labels=cage&state=open>.
5b63ade @paultcochrane [docs] Moved information about cage cleaners' high level goals from
paultcochrane authored
414
fc8fec0 @paultcochrane [docs] Added the very beginnings of a cage cleaners guide.
paultcochrane authored
415 =cut
Something went wrong with that request. Please try again.