blob: a58931ae7aa9c32f8b8b35e6b5852b8ac8ba7199 [file] [log] [blame]
Mark Whitley40bfc762000-07-24 22:36:06 +00001Busybox Style Guide
2===================
3
4This document describes the coding style conventions used in Busybox. If you
5add a new file to Busybox or are editing an existing file, please format your
6code according to this style. If you are the maintainer of a file that does
7not follow these guidelines, please -- at your own convenience -- modify the
8file(s) you maintain to bring them into conformance with this style guide.
9Please note that this is a low priority task.
10
11To help you format the whitespace of your programs, an ".indent.pro" file is
12included in the main Busybox source directory that contains option flags to
13format code as per this style guide. This way you can run GNU indent on your
14files by typing 'indent myfile.c myfile.h' and it will magically apply all the
15right formatting rules to your file. Please _do_not_ run this on all the files
16in the directory, just your own.
17
Mark Whitley2368a382000-08-22 00:20:21 +000018
Mark Whitleyd58ff872000-11-22 19:25:39 +000019
Mark Whitley40bfc762000-07-24 22:36:06 +000020Declaration Order
21-----------------
22
Denis Vlasenko91de7c02007-04-15 08:39:39 +000023Here is the preferred order in which code should be laid out in a file:
Mark Whitley40bfc762000-07-24 22:36:06 +000024
Mark Whitley9028e2c2000-11-17 21:28:39 +000025 - commented program name and one-line description
Mark Whitley40bfc762000-07-24 22:36:06 +000026 - commented author name and email address(es)
27 - commented GPL boilerplate
Mark Whitley9028e2c2000-11-17 21:28:39 +000028 - commented longer description / notes for the program (if needed)
Mark Whitley9ead6892001-03-03 00:44:55 +000029 - #includes of .h files with angle brackets (<>) around them
30 - #includes of .h files with quotes ("") around them
31 - #defines (if any, note the section below titled "Avoid the Preprocessor")
Mark Whitley9028e2c2000-11-17 21:28:39 +000032 - const and global variables
Mark Whitley40bfc762000-07-24 22:36:06 +000033 - function declarations (if necessary)
34 - function implementations
35
Mark Whitley2368a382000-08-22 00:20:21 +000036
Mark Whitleyd58ff872000-11-22 19:25:39 +000037
38Whitespace and Formatting
39-------------------------
Mark Whitley40bfc762000-07-24 22:36:06 +000040
Mark Whitley2368a382000-08-22 00:20:21 +000041This is everybody's favorite flame topic so let's get it out of the way right
42up front.
43
44
Mark Whitley9028e2c2000-11-17 21:28:39 +000045Tabs vs. Spaces in Line Indentation
Mark Whitleyd58ff872000-11-22 19:25:39 +000046~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Mark Whitley2368a382000-08-22 00:20:21 +000047
48The preference in Busybox is to indent lines with tabs. Do not indent lines
49with spaces and do not indents lines using a mixture of tabs and spaces. (The
50indentation style in the Apache and Postfix source does this sort of thing:
51\s\s\s\sif (expr) {\n\tstmt; --ick.) The only exception to this rule is
52multi-line comments that use an asterisk at the beginning of each line, i.e.:
Mark Whitley40bfc762000-07-24 22:36:06 +000053
Mike Frysinger434ccd92006-07-05 22:19:21 +000054 \t/*
55 \t * This is a block comment.
56 \t * Note that it has multiple lines
57 \t * and that the beginning of each line has a tab plus a space
58 \t * except for the opening '/*' line where the slash
59 \t * is used instead of a space.
60 \t */
Mark Whitley40bfc762000-07-24 22:36:06 +000061
62Furthermore, The preference is that tabs be set to display at four spaces
63wide, but the beauty of using only tabs (and not spaces) at the beginning of
Mark Whitley9028e2c2000-11-17 21:28:39 +000064lines is that you can set your editor to display tabs at *whatever* number of
Mark Whitley40bfc762000-07-24 22:36:06 +000065spaces is desired and the code will still look fine.
66
67
Mark Whitley2368a382000-08-22 00:20:21 +000068Operator Spacing
69~~~~~~~~~~~~~~~~
70
71Put spaces between terms and operators. Example:
Mark Whitley40bfc762000-07-24 22:36:06 +000072
73 Don't do this:
74
75 for(i=0;i<num_items;i++){
76
77 Do this instead:
78
79 for (i = 0; i < num_items; i++) {
80
81 While it extends the line a bit longer, the spaced version is more
82 readable. An allowable exception to this rule is the situation where
83 excluding the spacing makes it more obvious that we are dealing with a
Mark Whitley9028e2c2000-11-17 21:28:39 +000084 single term (even if it is a compound term) such as:
Mark Whitley40bfc762000-07-24 22:36:06 +000085
86 if (str[idx] == '/' && str[idx-1] != '\\')
87
88 or
89
90 if ((argc-1) - (optind+1) > 0)
91
92
Mark Whitley2368a382000-08-22 00:20:21 +000093Bracket Spacing
94~~~~~~~~~~~~~~~
95
96If an opening bracket starts a function, it should be on the
Mark Whitley9028e2c2000-11-17 21:28:39 +000097next line with no spacing before it. However, if a bracket follows an opening
Mark Whitley40bfc762000-07-24 22:36:06 +000098control block, it should be on the same line with a single space (not a tab)
Mark Whitley9028e2c2000-11-17 21:28:39 +000099between it and the opening control block statement. Examples:
Mark Whitley40bfc762000-07-24 22:36:06 +0000100
101 Don't do this:
102
Mark Whitley9028e2c2000-11-17 21:28:39 +0000103 while (!done)
104 {
105
106 do
107 {
108
109 Don't do this either:
110
Mark Whitley40bfc762000-07-24 22:36:06 +0000111 while (!done){
Mark Whitley925edb82001-02-03 00:20:14 +0000112
Mark Whitley40bfc762000-07-24 22:36:06 +0000113 do{
114
Mark Whitley3680c582000-12-20 22:35:12 +0000115 And for heaven's sake, don't do this:
116
117 while (!done)
118 {
Mark Whitley925edb82001-02-03 00:20:14 +0000119
Mark Whitley3680c582000-12-20 22:35:12 +0000120 do
121 {
122
Mark Whitley40bfc762000-07-24 22:36:06 +0000123 Do this instead:
124
125 while (!done) {
Mark Whitley925edb82001-02-03 00:20:14 +0000126
Mark Whitley40bfc762000-07-24 22:36:06 +0000127 do {
128
Denis Vlasenko91de7c02007-04-15 08:39:39 +0000129If you have long logic statements that need to be wrapped, then uncuddling
130the bracket to improve readability is allowed. Generally, this style makes
131it easier for reader to notice that 2nd and following lines are still
132inside 'if':
Mike Frysinger0612b5f2006-02-24 01:18:24 +0000133
Denis Vlasenko91de7c02007-04-15 08:39:39 +0000134 if (some_really_long_checks && some_other_really_long_checks
135 && some_more_really_long_checks
136 && even_more_of_long_checks
137 ) {
Mike Frysinger0612b5f2006-02-24 01:18:24 +0000138 do_foo_now;
Mark Whitley2368a382000-08-22 00:20:21 +0000139
Mark Whitley925edb82001-02-03 00:20:14 +0000140Spacing around Parentheses
141~~~~~~~~~~~~~~~~~~~~~~~~~~
Mark Whitley2368a382000-08-22 00:20:21 +0000142
Mark Whitley7ddaf7c2001-03-14 21:04:53 +0000143Put a space between C keywords and left parens, but not between function names
144and the left paren that starts it's parameter list (whether it is being
145declared or called). Examples:
Mark Whitley2368a382000-08-22 00:20:21 +0000146
147 Don't do this:
148
149 while(foo) {
150 for(i = 0; i < n; i++) {
151
152 Do this instead:
153
154 while (foo) {
155 for (i = 0; i < n; i++) {
156
Mark Whitley9028e2c2000-11-17 21:28:39 +0000157 But do functions like this:
Mark Whitley2368a382000-08-22 00:20:21 +0000158
159 static int my_func(int foo, char bar)
160 ...
161 baz = my_func(1, 2);
162
Mark Whitley925edb82001-02-03 00:20:14 +0000163Also, don't put a space between the left paren and the first term, nor between
164the last arg and the right paren.
165
166 Don't do this:
167
168 if ( x < 1 )
169 strcmp( thisstr, thatstr )
170
171 Do this instead:
172
173 if (x < 1)
174 strcmp(thisstr, thatstr)
175
Mark Whitley2368a382000-08-22 00:20:21 +0000176
177Cuddled Elses
178~~~~~~~~~~~~~
179
Mark Whitley9028e2c2000-11-17 21:28:39 +0000180Also, please "cuddle" your else statements by putting the else keyword on the
181same line after the right bracket that closes an 'if' statement.
Mark Whitley40bfc762000-07-24 22:36:06 +0000182
183 Don't do this:
184
185 if (foo) {
186 stmt;
187 }
188 else {
189 stmt;
190 }
191
192 Do this instead:
193
194 if (foo) {
195 stmt;
196 } else {
197 stmt;
198 }
199
Mark Whitley9028e2c2000-11-17 21:28:39 +0000200The exception to this rule is if you want to include a comment before the else
201block. Example:
202
203 if (foo) {
204 stmts...
205 }
206 /* otherwise, we're just kidding ourselves, so re-frob the input */
207 else {
208 other_stmts...
209 }
210
Mark Whitley40bfc762000-07-24 22:36:06 +0000211
Denis Vlasenko91de7c02007-04-15 08:39:39 +0000212Labels
213~~~~~~
214
215Labels should start at the beginning of the line, not indented to the block
216level (because they do not "belong" to block scope, only to whole function).
217
218 if (foo) {
219 stmt;
220 label:
221 stmt2;
222 stmt;
223 }
224
225(Putting label at position 1 prevents diff -p from confusing label for function
226name, but it's not a policy of busybox project to enforce such a minor detail).
227
228
Mark Whitleyd58ff872000-11-22 19:25:39 +0000229
Mark Whitley40bfc762000-07-24 22:36:06 +0000230Variable and Function Names
231---------------------------
232
233Use the K&R style with names in all lower-case and underscores occasionally
Mark Whitley9028e2c2000-11-17 21:28:39 +0000234used to separate words (e.g., "variable_name" and "numchars" are both
Mark Whitley40bfc762000-07-24 22:36:06 +0000235acceptable). Using underscores makes variable and function names more readable
236because it looks like whitespace; using lower-case is easy on the eyes.
237
Mark Whitley3680c582000-12-20 22:35:12 +0000238 Frowned upon:
239
240 hitList
241 TotalChars
Mark Whitleya5b55ca2001-01-24 00:18:13 +0000242 szFileName
243 pf_Nfol_TriState
Mark Whitley3680c582000-12-20 22:35:12 +0000244
245 Preferred:
246
247 hit_list
248 total_chars
249 file_name
Mark Whitleya5b55ca2001-01-24 00:18:13 +0000250 sensible_name
Mark Whitley3680c582000-12-20 22:35:12 +0000251
Mark Whitleya5b55ca2001-01-24 00:18:13 +0000252Exceptions:
253
Mark Whitley7ddaf7c2001-03-14 21:04:53 +0000254 - Enums, macros, and constant variables are occasionally written in all
Denys Vlasenko5370bfb2009-09-06 02:58:59 +0200255 upper-case with words optionally separated by underscores (i.e. FIFO_TYPE,
Mark Whitley7ddaf7c2001-03-14 21:04:53 +0000256 ISBLKDEV()).
Mark Whitleya5b55ca2001-01-24 00:18:13 +0000257
258 - Nobody is going to get mad at you for using 'pvar' as the name of a
259 variable that is a pointer to 'var'.
Mark Whitley3680c582000-12-20 22:35:12 +0000260
Mark Whitley40bfc762000-07-24 22:36:06 +0000261
Mark Whitley7ddaf7c2001-03-14 21:04:53 +0000262Converting to K&R
263~~~~~~~~~~~~~~~~~
264
265The Busybox codebase is very much a mixture of code gathered from a variety of
266sources. This explains why the current codebase contains such a hodge-podge of
267different naming styles (Java, Pascal, K&R, just-plain-weird, etc.). The K&R
268guideline explained above should therefore be used on new files that are added
269to the repository. Furthermore, the maintainer of an existing file that uses
270alternate naming conventions should, at his own convenience, convert those
271names over to K&R style. Converting variable names is a very low priority
272task.
273
274If you want to do a search-and-replace of a single variable name in different
275files, you can do the following in the busybox directory:
Mark Whitleya5b55ca2001-01-24 00:18:13 +0000276
277 $ perl -pi -e 's/\bOldVar\b/new_var/g' *.[ch]
278
Mark Whitley7ddaf7c2001-03-14 21:04:53 +0000279If you want to convert all the non-K&R vars in your file all at once, follow
280these steps:
281
Eric Andersenbdfd0d72001-10-24 05:00:29 +0000282 - In the busybox directory type 'examples/mk2knr.pl files-to-convert'. This
Mark Whitley7ddaf7c2001-03-14 21:04:53 +0000283 does not do the actual conversion, rather, it generates a script called
284 'convertme.pl' that shows what will be converted, giving you a chance to
285 review the changes beforehand.
286
287 - Review the 'convertme.pl' script that gets generated in the busybox
288 directory and remove / edit any of the substitutions in there. Please
289 especially check for false positives (strings that should not be
290 converted).
291
292 - Type './convertme.pl same-files-as-before' to perform the actual
293 conversion.
294
295 - Compile and see if everything still works.
Eric Andersenc7bda1c2004-03-15 08:29:22 +0000296
Mark Whitley7ddaf7c2001-03-14 21:04:53 +0000297Please be aware of changes that have cascading effects into other files. For
298example, if you're changing the name of something in, say utility.c, you
Eric Andersenbdfd0d72001-10-24 05:00:29 +0000299should probably run 'examples/mk2knr.pl utility.c' at first, but when you run
Mark Whitley7ddaf7c2001-03-14 21:04:53 +0000300the 'convertme.pl' script you should run it on _all_ files like so:
301'./convertme.pl *.[ch]'.
302
Mark Whitley40bfc762000-07-24 22:36:06 +0000303
Mark Whitley40bfc762000-07-24 22:36:06 +0000304
Mark Whitleyd58ff872000-11-22 19:25:39 +0000305Avoid The Preprocessor
306----------------------
Mark Whitley40bfc762000-07-24 22:36:06 +0000307
Mark Whitleyd58ff872000-11-22 19:25:39 +0000308At best, the preprocessor is a necessary evil, helping us account for platform
309and architecture differences. Using the preprocessor unnecessarily is just
310plain evil.
Mark Whitley2368a382000-08-22 00:20:21 +0000311
Mark Whitley40bfc762000-07-24 22:36:06 +0000312
Mark Whitleyd58ff872000-11-22 19:25:39 +0000313The Folly of #define
314~~~~~~~~~~~~~~~~~~~~
Mark Whitley40bfc762000-07-24 22:36:06 +0000315
Mark Whitleyd58ff872000-11-22 19:25:39 +0000316Use 'const <type> var' for declaring constants.
Mark Whitley40bfc762000-07-24 22:36:06 +0000317
318 Don't do this:
319
Denis Vlasenko91de7c02007-04-15 08:39:39 +0000320 #define CONST 80
Mark Whitleyd58ff872000-11-22 19:25:39 +0000321
322 Do this instead, when the variable is in a header file and will be used in
Eric Andersenc7bda1c2004-03-15 08:29:22 +0000323 several source files:
Mark Whitleyd58ff872000-11-22 19:25:39 +0000324
Denis Vlasenko91de7c02007-04-15 08:39:39 +0000325 enum { CONST = 80 };
Mark Whitleyd58ff872000-11-22 19:25:39 +0000326
Denis Vlasenko91de7c02007-04-15 08:39:39 +0000327Although enum may look ugly to some people, it is better for code size.
328With "const int" compiler may fail to optimize it out and will reserve
329a real storage in rodata for it! (Hopefully, newer gcc will get better
330at it...). With "define", you have slight risk of polluting namespace
331(#define doesn't allow you to redefine the name in the inner scopes),
332and complex "define" are evaluated each time they uesd, not once
333at declarations like enums. Also, the preprocessor does _no_ type checking
334whatsoever, making it much more error prone.
Mark Whitleyd58ff872000-11-22 19:25:39 +0000335
336
337The Folly of Macros
338~~~~~~~~~~~~~~~~~~~
339
340Use 'static inline' instead of a macro.
341
342 Don't do this:
343
344 #define mini_func(param1, param2) (param1 << param2)
Mark Whitley40bfc762000-07-24 22:36:06 +0000345
346 Do this instead:
347
Mark Whitleyd58ff872000-11-22 19:25:39 +0000348 static inline int mini_func(int param1, param2)
Mark Whitley40bfc762000-07-24 22:36:06 +0000349 {
Mark Whitleyd58ff872000-11-22 19:25:39 +0000350 return (param1 << param2);
351 }
Mark Whitley40bfc762000-07-24 22:36:06 +0000352
Mark Whitleyd58ff872000-11-22 19:25:39 +0000353Static inline functions are greatly preferred over macros. They provide type
Mark Whitley7ddaf7c2001-03-14 21:04:53 +0000354safety, have no length limitations, no formatting limitations, have an actual
355return value, and under gcc they are as cheap as macros. Besides, really long
356macros with backslashes at the end of each line are ugly as sin.
Mark Whitleyd58ff872000-11-22 19:25:39 +0000357
358
359The Folly of #ifdef
360~~~~~~~~~~~~~~~~~~~
361
362Code cluttered with ifdefs is difficult to read and maintain. Don't do it.
Mark Whitley7ddaf7c2001-03-14 21:04:53 +0000363Instead, put your ifdefs at the top of your .c file (or in a header), and
364conditionally define 'static inline' functions, (or *maybe* macros), which are
Eric Andersenc7bda1c2004-03-15 08:29:22 +0000365used in the code.
Mark Whitleyd58ff872000-11-22 19:25:39 +0000366
367 Don't do this:
368
369 ret = my_func(bar, baz);
370 if (!ret)
371 return -1;
Eric Andersenbdfd0d72001-10-24 05:00:29 +0000372 #ifdef CONFIG_FEATURE_FUNKY
Mark Whitleyd58ff872000-11-22 19:25:39 +0000373 maybe_do_funky_stuff(bar, baz);
374 #endif
375
376 Do this instead:
377
378 (in .h header file)
379
Denis Vlasenkoe3241842007-08-13 10:36:25 +0000380 #if ENABLE_FEATURE_FUNKY
381 static inline void maybe_do_funky_stuff(int bar, int baz)
Mark Whitleyd238a7b2001-02-09 00:28:59 +0000382 {
383 /* lotsa code in here */
384 }
385 #else
Denis Vlasenkoe3241842007-08-13 10:36:25 +0000386 static inline void maybe_do_funky_stuff(int bar, int baz) {}
Mark Whitleyd58ff872000-11-22 19:25:39 +0000387 #endif
388
389 (in the .c source file)
390
391 ret = my_func(bar, baz);
392 if (!ret)
393 return -1;
394 maybe_do_funky_stuff(bar, baz);
395
396The great thing about this approach is that the compiler will optimize away
Mark Whitleyd238a7b2001-02-09 00:28:59 +0000397the "no-op" case (the empty function) when the feature is turned off.
Mark Whitleyd58ff872000-11-22 19:25:39 +0000398
399Note also the use of the word 'maybe' in the function name to indicate
400conditional execution.
401
402
403
404Notes on Strings
405----------------
406
407Strings in C can get a little thorny. Here's some guidelines for dealing with
408strings in Busybox. (There is surely more that could be added to this
409section.)
410
411
412String Files
413~~~~~~~~~~~~
414
415Put all help/usage messages in usage.c. Put other strings in messages.c.
416Putting these strings into their own file is a calculated decision designed to
417confine spelling errors to a single place and aid internationalization
418efforts, if needed. (Side Note: we might want to use a single file - maybe
419called 'strings.c' - instead of two, food for thought).
420
421
422Testing String Equivalence
423~~~~~~~~~~~~~~~~~~~~~~~~~~
424
425There's a right way and a wrong way to test for sting equivalence with
426strcmp():
427
428 The wrong way:
429
430 if (!strcmp(string, "foo")) {
431 ...
432
433 The right way:
434
435 if (strcmp(string, "foo") == 0){
436 ...
437
438The use of the "equals" (==) operator in the latter example makes it much more
439obvious that you are testing for equivalence. The former example with the
440"not" (!) operator makes it look like you are testing for an error. In a more
441perfect world, we would have a streq() function in the string library, but
442that ain't the world we're living in.
443
444
Mark Whitleya5b55ca2001-01-24 00:18:13 +0000445Avoid Dangerous String Functions
446~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
447
448Unfortunately, the way C handles strings makes them prone to overruns when
449certain library functions are (mis)used. The following table offers a summary
450of some of the more notorious troublemakers:
451
Denis Vlasenko91de7c02007-04-15 08:39:39 +0000452function overflows preferred
453-------------------------------------------------
454strcpy dest string safe_strncpy
455strncpy may fail to 0-terminate dst safe_strncpy
456strcat dest string strncat
457gets string it gets fgets
458getwd buf string getcwd
459[v]sprintf str buffer [v]snprintf
460realpath path buffer use with pathconf
461[vf]scanf its arguments just avoid it
Mark Whitleya5b55ca2001-01-24 00:18:13 +0000462
463
464The above is by no means a complete list. Be careful out there.
465
466
467
468Avoid Big Static Buffers
469------------------------
470
Denis Vlasenko91de7c02007-04-15 08:39:39 +0000471First, some background to put this discussion in context: static buffers look
Mark Whitleya5b55ca2001-01-24 00:18:13 +0000472like this in code:
473
474 /* in a .c file outside any functions */
Rob Landley6a249762005-12-20 15:23:20 +0000475 static char buffer[BUFSIZ]; /* happily used by any function in this file,
Mark Whitleya5b55ca2001-01-24 00:18:13 +0000476 but ick! big! */
477
478The problem with these is that any time any busybox app is run, you pay a
479memory penalty for this buffer, even if the applet that uses said buffer is
480not run. This can be fixed, thusly:
481
Eric Andersend35c2152001-01-25 23:49:09 +0000482 static char *buffer;
Mark Whitleya5b55ca2001-01-24 00:18:13 +0000483 ...
484 other_func()
485 {
486 strcpy(buffer, lotsa_chars); /* happily uses global *buffer */
487 ...
488 foo_main()
489 {
490 buffer = xmalloc(sizeof(char)*BUFSIZ);
491 ...
492
493However, this approach trades bss segment for text segment. Rather than
494mallocing the buffers (and thus growing the text size), buffers can be
495declared on the stack in the *_main() function and made available globally by
496assigning them to a global pointer thusly:
497
Eric Andersend35c2152001-01-25 23:49:09 +0000498 static char *pbuffer;
Mark Whitleya5b55ca2001-01-24 00:18:13 +0000499 ...
500 other_func()
501 {
502 strcpy(pbuffer, lotsa_chars); /* happily uses global *pbuffer */
503 ...
504 foo_main()
505 {
506 char *buffer[BUFSIZ]; /* declared locally, on stack */
507 pbuffer = buffer; /* but available globally */
508 ...
509
Eric Andersend35c2152001-01-25 23:49:09 +0000510This last approach has some advantages (low code size, space not used until
511it's needed), but can be a problem in some low resource machines that have
Mark Whitleyd238a7b2001-02-09 00:28:59 +0000512very limited stack space (e.g., uCLinux).
513
514A macro is declared in busybox.h that implements compile-time selection
515between xmalloc() and stack creation, so you can code the line in question as
516
Eric Andersenbdfd0d72001-10-24 05:00:29 +0000517 RESERVE_CONFIG_BUFFER(buffer, BUFSIZ);
Mark Whitleyd238a7b2001-02-09 00:28:59 +0000518
519and the right thing will happen, based on your configuration.
Mark Whitleya5b55ca2001-01-24 00:18:13 +0000520
Denis Vlasenko91de7c02007-04-15 08:39:39 +0000521Another relatively new trick of similar nature is explained
522in keep_data_small.txt.
523
Mark Whitleya5b55ca2001-01-24 00:18:13 +0000524
Mark Whitleyd58ff872000-11-22 19:25:39 +0000525
526Miscellaneous Coding Guidelines
527-------------------------------
528
529The following are important items that don't fit into any of the above
530sections.
531
532
533Model Busybox Applets After GNU Counterparts
534~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
535
536When in doubt about the proper behavior of a Busybox program (output,
537formatting, options, etc.), model it after the equivalent GNU program.
538Doesn't matter how that program behaves on some other flavor of *NIX; doesn't
539matter what the POSIX standard says or doesn't say, just model Busybox
Mark Whitley7ddaf7c2001-03-14 21:04:53 +0000540programs after their GNU counterparts and it will make life easier on (nearly)
541everyone.
Mark Whitleyd58ff872000-11-22 19:25:39 +0000542
543The only time we deviate from emulating the GNU behavior is when:
544
545 - We are deliberately not supporting a feature (such as a command line
546 switch)
547 - Emulating the GNU behavior is prohibitively expensive (lots more code
548 would be required, lots more memory would be used, etc.)
Eric Andersen07309432000-11-29 22:12:19 +0000549 - The difference is minor or cosmetic
Mark Whitleyd58ff872000-11-22 19:25:39 +0000550
Denis Vlasenko91de7c02007-04-15 08:39:39 +0000551A note on the 'cosmetic' case: output differences might be considered
Mark Whitleyd58ff872000-11-22 19:25:39 +0000552cosmetic, but if the output is significant enough to break other scripts that
553use the output, it should really be fixed.
554
555
556Scope
557~~~~~
558
559If a const variable is used only in a single source file, put it in the source
560file and not in a header file. Likewise, if a const variable is used in only
561one function, do not make it global to the file. Instead, declare it inside
Eric Andersen07309432000-11-29 22:12:19 +0000562the function body. Bottom line: Make a conscious effort to limit declarations
Mark Whitleyd58ff872000-11-22 19:25:39 +0000563to the smallest scope possible.
564
565Inside applet files, all functions should be declared static so as to keep the
566global name space clean. The only exception to this rule is the "applet_main"
567function which must be declared extern.
568
569If you write a function that performs a task that could be useful outside the
570immediate file, turn it into a general-purpose function with no ties to any
571applet and put it in the utility.c file instead.
572
573
574Brackets Are Your Friends
575~~~~~~~~~~~~~~~~~~~~~~~~~
576
577Please use brackets on all if and else statements, even if it is only one
578line. Example:
Mark Whitley40bfc762000-07-24 22:36:06 +0000579
580 Don't do this:
581
582 if (foo)
Mark Whitley3680c582000-12-20 22:35:12 +0000583 stmt1;
584 stmt2
585 stmt3;
Mark Whitley40bfc762000-07-24 22:36:06 +0000586
587 Do this instead:
588
589 if (foo) {
Mark Whitley3680c582000-12-20 22:35:12 +0000590 stmt1;
Mark Whitley40bfc762000-07-24 22:36:06 +0000591 }
Mark Whitley3680c582000-12-20 22:35:12 +0000592 stmt2
593 stmt3;
Mark Whitley40bfc762000-07-24 22:36:06 +0000594
Mark Whitleyd58ff872000-11-22 19:25:39 +0000595The "bracketless" approach is error prone because someday you might add a line
596like this:
Mark Whitley40bfc762000-07-24 22:36:06 +0000597
598 if (foo)
Mark Whitley3680c582000-12-20 22:35:12 +0000599 stmt1;
Mark Whitley40bfc762000-07-24 22:36:06 +0000600 new_line();
Denis Vlasenko91de7c02007-04-15 08:39:39 +0000601 stmt2;
Mark Whitley3680c582000-12-20 22:35:12 +0000602 stmt3;
Mark Whitley40bfc762000-07-24 22:36:06 +0000603
Mark Whitleyd58ff872000-11-22 19:25:39 +0000604And the resulting behavior of your program would totally bewilder you. (Don't
605laugh, it happens to us all.) Remember folks, this is C, not Python.
606
607
608Function Declarations
609~~~~~~~~~~~~~~~~~~~~~
610
611Do not use old-style function declarations that declare variable types between
612the parameter list and opening bracket. Example:
613
614 Don't do this:
615
616 int foo(parm1, parm2)
617 char parm1;
618 float parm2;
619 {
620 ....
621
622 Do this instead:
623
624 int foo(char parm1, float parm2)
625 {
626 ....
627
628The only time you would ever need to use the old declaration syntax is to
Eric Andersen07309432000-11-29 22:12:19 +0000629support ancient, antediluvian compilers. To our good fortune, we have access
Mark Whitleyd58ff872000-11-22 19:25:39 +0000630to more modern compilers and the old declaration syntax is neither necessary
631nor desired.
632
Mark Whitley3680c582000-12-20 22:35:12 +0000633
634Emphasizing Logical Blocks
635~~~~~~~~~~~~~~~~~~~~~~~~~~
636
637Organization and readability are improved by putting extra newlines around
638blocks of code that perform a single task. These are typically blocks that
639begin with a C keyword, but not always.
640
641Furthermore, you should put a single comment (not necessarily one line, just
642one comment) before the block, rather than commenting each and every line.
Mike Frysinger434ccd92006-07-05 22:19:21 +0000643There is an optimal amount of commenting that a program can have; you can
Mark Whitley3680c582000-12-20 22:35:12 +0000644comment too much as well as too little.
645
Mark Whitley7ddaf7c2001-03-14 21:04:53 +0000646A picture is really worth a thousand words here, the following example
647illustrates how to emphasize logical blocks:
Mark Whitley3680c582000-12-20 22:35:12 +0000648
Denis Vlasenko91de7c02007-04-15 08:39:39 +0000649 while (line = xmalloc_fgets(fp)) {
Mark Whitley3680c582000-12-20 22:35:12 +0000650
651 /* eat the newline, if any */
Mark Whitley7ddaf7c2001-03-14 21:04:53 +0000652 chomp(line);
Mark Whitley3680c582000-12-20 22:35:12 +0000653
654 /* ignore blank lines */
655 if (strlen(file_to_act_on) == 0) {
656 continue;
657 }
658
659 /* if the search string is in this line, print it,
660 * unless we were told to be quiet */
661 if (strstr(line, search) && !be_quiet) {
662 puts(line);
663 }
664
665 /* clean up */
666 free(line);
667 }
Mark Whitley9ead6892001-03-03 00:44:55 +0000668
669
670Processing Options with getopt
671~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
672
Denis Vlasenko91de7c02007-04-15 08:39:39 +0000673If your applet needs to process command-line switches, please use getopt32() to
Mark Whitley9ead6892001-03-03 00:44:55 +0000674do so. Numerous examples can be seen in many of the existing applets, but
675basically it boils down to two things: at the top of the .c file, have this
Denis Vlasenko91de7c02007-04-15 08:39:39 +0000676line in the midst of your #includes, if you need to parse long options:
Mark Whitley9ead6892001-03-03 00:44:55 +0000677
678 #include <getopt.h>
679
Denis Vlasenko91de7c02007-04-15 08:39:39 +0000680Then have long options defined:
681
682 static const struct option <applet>_long_options[] = {
683 { "list", 0, NULL, 't' },
684 { "extract", 0, NULL, 'x' },
Denis Vlasenko84f75b02007-04-15 11:50:41 +0000685 { NULL, 0, NULL, 0 }
Denis Vlasenko91de7c02007-04-15 08:39:39 +0000686 };
687
Mark Whitley9ead6892001-03-03 00:44:55 +0000688And a code block similar to the following near the top of your applet_main()
689routine:
690
Denis Vlasenko91de7c02007-04-15 08:39:39 +0000691 char *str_b;
692
693 opt_complementary = "cryptic_string";
694 applet_long_options = <applet>_long_options; /* if you have them */
695 opt = getopt32(argc, argv, "ab:c", &str_b);
696 if (opt & 1) {
697 handle_option_a();
698 }
699 if (opt & 2) {
700 handle_option_b(str_b);
701 }
702 if (opt & 4) {
703 handle_option_c();
704 }
Mark Whitley9ead6892001-03-03 00:44:55 +0000705
706If your applet takes no options (such as 'init'), there should be a line
707somewhere in the file reads:
708
709 /* no options, no getopt */
710
711That way, when people go grepping to see which applets need to be converted to
712use getopt, they won't get false positives.
713
Denis Vlasenko91de7c02007-04-15 08:39:39 +0000714For more info and examples, examine getopt32.c, tar.c, wget.c etc.