1Contributing To Busybox 2======================= 3 4This document describes what you need to do to contribute to Busybox, where 5you can help, guidelines on testing, and how to submit a well-formed patch 6that is more likely to be accepted. 7 8The Busybox home page is at: http://busybox.net/ 9 10 11 12Pre-Contribution Checklist 13-------------------------- 14 15So you want to contribute to Busybox, eh? Great, wonderful, glad you want to 16help. However, before you dive in, headlong and hotfoot, there are some things 17you need to do: 18 19 20Checkout the Latest Code from CVS 21~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 22 23This is a necessary first step. Please do not try to work with the last 24released version, as there is a good chance that somebody has already fixed 25the bug you found. Somebody might have even added the feature you had in mind. 26Don't make your work obsolete before you start! 27 28For information on how to check out Busybox from CVS, please look at the 29following links: 30 31 http://busybox.net/cvs_anon.html 32 http://busybox.net/cvs_howto.html 33 34 35Read the Mailing List 36~~~~~~~~~~~~~~~~~~~~~ 37 38No one is required to read the entire archives of the mailing list, but you 39should at least read up on what people have been talking about lately. If 40you've recently discovered a problem, chances are somebody else has too. If 41you're the first to discover a problem, post a message and let the rest of us 42know. 43 44Archives can be found here: 45 46 http://busybox.net/lists/busybox/ 47 48If you have a serious interest in Busybox, i.e., you are using it day-to-day or 49as part of an embedded project, it would be a good idea to join the mailing 50list. 51 52A web-based sign-up form can be found here: 53 54 http://busybox.net/mailman/listinfo/busybox 55 56 57Coordinate with the Applet Maintainer 58~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 59 60Some (not all) of the applets in Busybox are "owned" by a maintainer who has 61put significant effort into it and is probably more familiar with it than 62others. To find the maintainer of an applet, look at the top of the .c file 63for a name following the word 'Copyright' or 'Written by' or 'Maintainer'. 64 65Before plunging ahead, it's a good idea to send a message to the mailing list 66that says: "Hey, I was thinking about adding the 'transmogrify' feature to the 67'foo' applet. Would this be useful? Is anyone else working on it?" You might 68want to CC the maintainer (if any) with your question. 69 70 71 72Areas Where You Can Help 73------------------------ 74 75Busybox can always use improvement! If you're looking for ways to help, there 76are a variety of areas where you could help. 77 78 79What Busybox Doesn't Need 80~~~~~~~~~~~~~~~~~~~~~~~~~ 81 82Before listing the areas where you _can_ help, it's worthwhile to mention the 83areas where you shouldn't bother. While Busybox strives to be the "Swiss Army 84Knife" of embedded Linux, there are some applets that will not be accepted: 85 86 - Any filesystem manipulation tools: Busybox is filesystem independent and 87 we do not want to start adding mkfs/fsck tools for every (or any) 88 filesystem under the sun. (fsck_minix.c and mkfs_minix.c are living on 89 borrowed time.) There are far too many of these tools out there. Use 90 the upstream version. Not everything has to be part of Busybox. 91 92 - Any partitioning tools: Partitioning a device is typically done once and 93 only once, and tools which do this generally do not need to reside on the 94 target device (esp a flash device). If you need a partitioning tool, grab 95 one (such as fdisk, sfdisk, or cfdisk from util-linux) and use that, but 96 don't try to merge it into busybox. These are nasty and complex and we 97 don't want to maintain them. 98 99 - Any disk, device, or media-specific tools: Use the -utils or -tools package 100 that was designed for your device; don't try to shoehorn them into Busybox. 101 102 - Any architecture specific tools: Busybox is (or should be) architecture 103 independent. Do not send us tools that cannot be used across multiple 104 platforms / arches. 105 106 - Any daemons that are not essential to basic system operation. To date, only 107 syslogd and klogd meet this requirement. We do not need a web server, an 108 ftp daemon, a dhcp server, a mail transport agent or a dns resolver. If you 109 need one of those, you are welcome to ask the folks on the mailing list for 110 recommendations, but please don't bloat up Busybox with any of these. 111 112 113Bug Reporting 114~~~~~~~~~~~~~ 115 116If you find bugs, please submit a detailed bug report to the busybox mailing 117list at busybox@busybox.net. A well-written bug report should include a 118transcript of a shell session that demonstrates the bad behavior and enables 119anyone else to duplicate the bug on their own machine. The following is such 120an example: 121 122 To: busybox@busybox.net 123 From: diligent@testing.linux.org 124 Subject: /bin/date doesn't work 125 126 Package: busybox 127 Version: 1.00 128 129 When I execute Busybox 'date' it produces unexpected results. 130 With GNU date I get the following output: 131 132 $ date 133 Wed Mar 21 14:19:41 MST 2001 134 135 But when I use BusyBox date I get this instead: 136 137 $ date 138 llegal instruction 139 140 I am using Debian unstable, kernel version 2.4.19-rmk1 on an Netwinder, 141 and the latest uClibc from CVS. Thanks for the wonderful program! 142 143 -Diligent 144 145Note the careful description and use of examples showing not only what BusyBox 146does, but also a counter example showing what an equivalent GNU app does. Bug 147reports lacking such detail may never be fixed... Thanks for understanding. 148 149 150 151Write Documentation 152~~~~~~~~~~~~~~~~~~~ 153 154Chances are, documentation in Busybox is either missing or needs improvement. 155Either way, help is welcome. 156 157Work is being done to automatically generate documentation from sources, 158especially from the usage.h file. If you want to correct the documentation, 159please make changes to the pre-generation parts, rather than the generated 160documentation. [More to come on this later...] 161 162It is preferred that modifications to documentation be submitted in patch 163format (more on this below), but we're a little more lenient when it comes to 164docs. You could, for example, just say "after the listing of the mount 165options, the following example would be helpful..." 166 167 168Consult Existing Sources 169~~~~~~~~~~~~~~~~~~~~~~~~ 170 171For a quick listing of "needs work" spots in the sources, cd into the Busybox 172directory and run the following: 173 174 for i in TODO FIXME XXX; do find -name '*.[ch]'|xargs grep $i; done 175 176This will show all of the trouble spots or 'questionable' code. Pick a spot, 177any spot, these are all invitations for you to contribute. 178 179 180Add a New Applet 181~~~~~~~~~~~~~~~~ 182 183If you want to add a new applet to Busybox, we'd love to see it. However, 184before you write any code, please ask beforehand on the mailing list something 185like "Do you think applet 'foo' would be useful in Busybox?" or "Would you 186guys accept applet 'foo' into Busybox if I were to write it?" If the answer is 187"no" by the folks on the mailing list, then you've saved yourself some time. 188Conversely, you could get some positive responses from folks who might be 189interested in helping you implement it, or can recommend the best approach. 190Perhaps most importantly, this is your way of calling "dibs" on something and 191avoiding duplication of effort. 192 193Also, before you write a line of code, please read the 'new-applet-HOWTO.txt' 194file in the docs/ directory. 195 196 197Janitorial Work 198~~~~~~~~~~~~~~~ 199 200These are dirty jobs, but somebody's gotta do 'em. 201 202 - Converting applets to use getopt() for option processing. Type 'find -name 203 '*.c'|grep -L getopt' to get a listing of the applets that currently don't 204 use getopt. If a .c file processes no options, it should have a line that 205 reads: /* no options, no getopt */ somewhere in the file. 206 207 - Replace any "naked" calls to malloc, calloc, realloc, str[n]dup, fopen with 208 the x* equivalents found in libbb/xfuncs.c. 209 210 - Security audits: 211 http://www.securityfocus.com/popups/forums/secprog/intro.shtml 212 213 - Synthetic code removal: http://www.perl.com/pub/2000/06/commify.html - This 214 is very Perl-specific, but the advice given in here applies equally well to 215 C. 216 217 - C library function use audits: Verifying that functions are being used 218 properly (called with the right args), replacing unsafe library functions 219 with safer versions, making sure return codes are being checked, etc. 220 221 - Where appropriate, replace preprocessor defined macros and values with 222 compile-time equivalents. 223 224 - Style guide compliance. See: docs/style-guide.txt 225 226 - Add testcases to tests/testcases. 227 228 - Makefile improvements: 229 http://www.canb.auug.org.au/~millerp/rmch/recu-make-cons-harm.html 230 (I think the recursive problems are pretty much taken care of at this point, non?) 231 232 - "Ten Commandments" compliance: (this is a "maybe", certainly not as 233 important as any of the previous items.) 234 http://www.lysator.liu.se/c/ten-commandments.html 235 236Other useful links: 237 238 - the comp.lang.c FAQ: http://web.onetelnet.ch/~twolf/tw/c/index.html#Sources 239 240 241 242Submitting Patches To Busybox 243----------------------------- 244 245Here are some guidelines on how to submit a patch to Busybox. 246 247 248Making A Patch 249~~~~~~~~~~~~~~ 250 251If you've got anonymous CVS access set up, making a patch is simple. Just make 252sure you're in the busybox/ directory and type 'cvs diff -bwu > mychanges.patch'. 253You can send the resulting .patch file to the mailing list with a description 254of what it does. (But not before you test it! See the next section for some 255guidelines.) It is preferred that patches be sent as attachments, but it is 256not required. 257 258Also, feel free to help test other people's patches and reply to them with 259comments. You can apply a patch by saving it into your busybox/ directory and 260typing 'patch < mychanges.patch'. Then you can recompile, see if it runs, test 261if it works as advertised, and post your findings to the mailing list. 262 263NOTE: Please do not include extraneous or irrelevant changes in your patches. 264Please do not try to "bundle" two patches together into one. Make single, 265discreet changes on a per-patch basis. Sometimes you need to make a patch that 266touches code in many places, but these kind of patches are rare and should be 267coordinated with a maintainer. 268 269 270Testing Guidelines 271~~~~~~~~~~~~~~~~~~ 272 273It's considered good form to test your new feature before you submit a patch 274to the mailing list, and especially before you commit a change to CVS. Here 275are some guidelines on how to test your changes. 276 277 - Always test Busybox applets against GNU counterparts and make sure the 278 behavior / output is identical between the two. 279 280 - Try several different permutations and combinations of the features you're 281 adding (i.e., different combinations of command-line switches) and make sure 282 they all work; make sure one feature does not interfere with another. 283 284 - Make sure you test compiling against the source both with the feature 285 turned on and turned off in Config.h and make sure Busybox compiles cleanly 286 both ways. 287 288 - Run the multibuild.pl script in the tests directory and make sure 289 everything checks out OK. (Do this from within the busybox/ directory by 290 typing: 'tests/multibuild.pl'.) 291 292 293Making Sure Your Patch Doesn't Get Lost 294~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 295 296If you don't want your patch to be lost or forgotten, send it to the busybox 297mailing list with a subject line something like this: 298 299 [PATCH] - Adds "transmogrify" feature to "foo" 300 301In the body, you should have a pseudo-header that looks like the following: 302 303 Package: busybox 304 Version: v1.01pre (or whatever the current version is) 305 Severity: wishlist 306 307The remainder of the body should read along these lines: 308 309 This patch adds the "transmogrify" feature to the "foo" applet. I have 310 tested this on [arch] system(s) and it works. I have tested it against the 311 GNU counterparts and the outputs are identical. I have run the scripts in 312 the 'tests' directory and nothing breaks. 313 314 315 316Improving Your Chances of Patch Acceptance 317------------------------------------------ 318 319Even after you send a brilliant patch to the mailing list, sometimes it can go 320unnoticed, un-replied-to, and sometimes (sigh) even lost. This is an 321unfortunate fact of life, but there are steps you can take to help your patch 322get noticed and convince a maintainer that it should be added: 323 324 325Be Succinct 326~~~~~~~~~~~ 327 328A patch that includes small, isolated, obvious changes is more likely to be 329accepted than a patch that touches code in lots of different places or makes 330sweeping, dubious changes. 331 332 333Back It Up 334~~~~~~~~~~ 335 336Hard facts on why your patch is better than the existing code will go a long 337way toward convincing maintainers that your patch should be included. 338Specifically, patches are more likely to be accepted if they are provably more 339correct, smaller, faster, simpler, or more maintainable than the existing 340code. 341 342Conversely, any patch that is supported with nothing more than "I think this 343would be cool" or "this patch is good because I say it is and I've got a Phd 344in Computer Science" will likely be ignored. 345 346 347Follow The Style Guide 348~~~~~~~~~~~~~~~~~~~~~~ 349 350It's considered good form to abide by the established coding style used in a 351project; Busybox is no exception. We have gone so far as to delineate the 352"elements of Busybox style" in the file docs/style-guide.txt. Please follow 353them. 354 355 356Work With Someone Else 357~~~~~~~~~~~~~~~~~~~~~~ 358 359Working on a patch in isolation is less effective than working with someone 360else for a variety of reasons. If another Busybox user is interested in what 361you're doing, then it's two (or more) voices instead of one that can petition 362for inclusion of the patch. You'll also have more people that can test your 363changes, or even offer suggestions on better approaches you could take. 364 365Getting other folks interested follows as a natural course if you've received 366responses from queries to applet maintainer or positive responses from folks 367on the mailing list. 368 369We've made strident efforts to put a useful "collaboration" infrastructure in 370place in the form of mailing lists, the bug tracking system, and CVS. Please 371use these resources. 372 373 374Send Patches to the Bug Tracking System 375~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 376 377This was mentioned above in the "Making Sure Your Patch Doesn't Get Lost" 378section, but it is worth mentioning again. A patch sent to the mailing list 379might be unnoticed and forgotten. A patch sent to the bug tracking system will 380be stored and closely connected to the bug it fixes. 381 382 383Be Polite 384~~~~~~~~~ 385 386The old saying "You'll catch more flies with honey than you will with vinegar" 387applies when submitting patches to the mailing list for approval. The way you 388present your patch is sometimes just as important as the actual patch itself 389(if not more so). Being rude to the maintainers is not an effective way to 390convince them that your patch should be included; it will likely have the 391opposite effect. 392 393 394 395Committing Changes to CVS 396------------------------- 397 398If you submit several patches that demonstrate that you are a skilled and wise 399coder, you may be invited to become a committer, thus enabling you to commit 400changes directly to CVS. This is nice because you don't have to wait for 401someone else to commit your change for you, you can just do it yourself. 402 403But note that this is a privilege that comes with some responsibilities. You 404should test your changes before you commit them. You should also talk to an 405applet maintainer before you make any kind of sweeping changes to somebody 406else's code. Big changes should still go to the mailing list first. Remember, 407being wise, polite, and discreet is more important than being clever. 408 409 410When To Commit 411~~~~~~~~~~~~~~ 412 413Generally, you should feel free to commit a change if: 414 415 - Your changes are small and don't touch many files 416 - You are fixing a bug 417 - Somebody has told you that it's okay 418 - It's obviously the Right Thing 419 420The more of the above are true, the better it is to just commit a change 421directly to CVS. 422 423 424When Not To Commit 425~~~~~~~~~~~~~~~~~~ 426 427Even if you have commit rights, you should probably still post a patch to the 428mailing list if: 429 430 - Your changes are broad and touch many different files 431 - You are adding a feature 432 - Your changes are speculative or experimental (i.e., trying a new algorithm) 433 - You are not the maintainer and your changes make the maintainer cringe 434 435The more of the above are true, the better it is to post a patch to the 436mailing list instead of committing. 437 438 439 440Final Words 441----------- 442 443If all of this seems complicated, don't panic, it's really not that tough. If 444you're having difficulty following some of the steps outlined in this 445document don't worry, the folks on the Busybox mailing list are a fairly 446good-natured bunch and will work with you to help get your patches into shape 447or help you make contributions. 448 449 450