1 Contributing To Busybox
2 =======================
4 This document describes what you need to do to contribute to Busybox, where
5 you can help, guidelines on testing, and how to submit a well-formed patch
6 that is more likely to be accepted.
8 The Busybox home page is at: http://busybox.lineo.com
12 Pre-Contribution Checklist
13 --------------------------
15 So you want to contribute to Busybox, eh? Great, wonderful, glad you want to
16 help. However, before you dive in, headlong and hotfoot, there are some things
20 Checkout the Latest Code from CVS
21 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
23 This is a necessary first step. Please do not try to work with the last
24 released version, as there is a good chance that somebody has already fixed
25 the bug you found. Somebody might have even added the feature you had in mind.
26 Don't make your work obsolete before you start!
28 For information on how to check out Busybox from CVS, please look at the
31 http://oss.lineo.com/cvs_anon.html
32 http://oss.lineo.com/cvs_howto.html
38 No one is required to read the entire archives of the mailing list, but you
39 should at least read up on what people have been talking about lately. If
40 you've recently discovered a problem, chances are somebody else has too. If
41 you're the first to discover a problem, post a message and let the rest of us
44 Archives can be found here:
46 http://opensource.lineo.com/lists/busybox/
48 If you have a serious interest in Busybox, i.e. you are using it day-to-day or
49 as part of an embedded project, it would be a good idea to join the mailing
52 A web-based sign-up form can be found here:
54 http://opensource.lineo.com/mailman/listinfo/busybox
57 Coordinate with the Applet Maintainer
58 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
60 Some (not all) of the applets in Busybox are "owned" by a maintainer who has
61 put significant effort into it and is probably more familiar with it than
62 others. To find the maintainer of an applet, look at the top of the .c file
63 for a name following the word 'Copyright' or 'Written by' or 'Maintainer'.
65 Before plunging ahead, it's a good idea to send a message to the mailing list
66 that 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
68 want to CC the maintainer (if any) with your question.
72 Areas Where You Can Help
73 ------------------------
75 Busybox can always use improvement! If you're looking for ways to help, there
76 there are a variety of areas where you could help.
79 What Busybox Doesn't Need
80 ~~~~~~~~~~~~~~~~~~~~~~~~~
82 Before listing the areas where you _can_ help, it's worthwhile to mention the
83 areas where you shouldn't bother. While Busybox strives to be the "Swiss Army
84 Knife" of embedded Linux, there are some applets that will not be accepted:
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.
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.
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.
102 - Any architecture specific tools: Busybox is (or should be) architecture
103 independent. Do not send us tools that cannot be used across multiple
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.
116 If you find a bug in Busybox, you can send a bug report to our bug tracking
117 system (homepage: http://bugs.lineo.com). Instructions on how to send a bug
118 report to the tracking system can be found at:
120 http://bugs.lineo.com/Reporting.html
122 The README file that comes with Busybox also describes how to submit a bug.
124 A well-written bug report should include a transcript of a shell session that
125 demonstrates the bad behavior and enables anyone else to duplicate the bug on
126 their own machine. The following is such an example:
128 When I execute Busybox 'date' it produces unexpected results.
130 This is using GNU date:
132 Wed Mar 21 14:19:41 MST 2001
134 This is using Busybox date:
142 Validating and confirming bugs is nearly as important as reporting them in the
143 first place. It is valuable to know if a bug can be duplicated on a different
144 machine, on a different filesystem, on a different architecture, with a
145 different C library, and so forth.
147 To see a listing of all the bugs currently filed against Busybox, look here:
149 http://bugs.lineo.com/db/pa/lbusybox.html
151 If you have comments to add to a bug (can / can't duplicate, think a bug
152 should be closed / reopened), please send it to [bugnumber]@bugs.lineo.com.
153 The message you send will automatically be forwarded to the mailing list for
160 Chances are, documentation in Busybox is either missing or needs improvement.
161 Either way, help is welcome.
163 Work is being done to automatically generate documentation from sources,
164 especially from the usage.h file. If you want to correct the documentation,
165 please make changes to the pre-generation parts, rather than the generated
166 documentation. [More to come on this later...]
168 It is preferred that modifications to documentation be submitted in patch
169 format (more on this below), but we're a little more lenient when it comes to
170 docs. You could, for example, just say "after the listing of the mount
171 options, the following example would be helpful..."
174 Consult Existing Sources
175 ~~~~~~~~~~~~~~~~~~~~~~~~
177 For a quick listing of "needs work" spots in the sources, cd into the Busybox
178 directory and run the following:
180 for i in TODO FIXME XXX; do grep $i *.[ch]; done
182 This will show all of the trouble spots or 'questionable' code. Pick a spot,
183 any spot, these are all invitations for you to contribute.
186 Consult The Bug-Tracking System
187 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
189 Head to: http://bugs.lineo.com/db/pa/lBusybox.html and look at the bugs on
190 there. Pick one you think you can fix, and fix it. If it's a wishlist item and
191 someone's requesting a new feature, take a stab at adding it. Everything
192 previously said about "reading the mailing list" and "coordinating with the
193 applet maintainer" still applies.
199 If you want to add a new applet to Busybox, we'd love to see it. However,
200 before you write any code, please ask beforehand on the mailing list something
201 like "Do you think applet 'foo' would be useful in Busybox?" or "Would you
202 guys accept applet 'foo' into Busybox if I were to write it?" If the answer is
203 "no" by the folks on the mailing list, then you've saved yourself some time.
204 Conversely, you could get some positive responses from folks who might be
205 interested in helping you implement it, or can recommend the best approach.
206 Perhaps most importantly, this is your way of calling "dibs" on something and
207 avoiding duplication of effort.
209 Also, before you write a line of code, please read the 'new-applet-HOWTO.txt'
210 file in the docs/ directory.
216 These are dirty jobs, but somebody's gotta do 'em.
218 - Converting applets to use getopt() for option processing. Type 'grep -L
219 getopt *.c' to get a listing of the applets that currently don't use
220 getopt. If a .c file processes no options, it should have a line that
221 reads: /* no options, no getopt */ somewhere in the file.
223 - Replace any "naked" calls to malloc, calloc, realloc, str[n]dup, fopen with
224 the x* equivalents found in utility.c.
227 http://www.securityfocus.com/frames/?content=/forums/secprog/secure-programming.html
229 - Synthetic code removal: http://www.perl.com/pub/2000/06/commify.html - This
230 is very Perl-specific, but the advice given in here applies equally well to
233 - C library funciton use audits: Verifying that functions are being used
234 properly (called with the right args), replacing unsafe library functions
235 with safer versions, making sure return codes are being checked, etc.
237 - Where appropriate, replace preprocessor defined macros and values with
238 compile-time equivalents.
240 - Style guide compliance. See: docs/style-guide.txt
242 - Add testcases to tests/testcases.
244 - Makefile improvements:
245 http://www.canb.auug.org.au/~millerp/rmch/recu-make-cons-harm.html
246 (I think the recursive problems are pretty much taken care of at this point, non?)
248 - "Ten Commandments" compliance: (this is a "maybe", certainly not as
249 important as any of the previous items.)
250 http://web.onetelnet.ch/~twolf/tw/c/ten_commandments.html
254 - the comp.lang.c FAQ: http://web.onetelnet.ch/~twolf/tw/c/index.html#Sources
258 Submitting Patches To Busybox
259 -----------------------------
261 Here are some guidelines on how to submit a patch to Busybox.
267 If you've got anonymous CVS access set up, making a patch is simple. Just make
268 sure you're in the busybox/ directory and type 'cvs diff -bwu > mychanges.patch'.
269 You can send the resulting .patch file to the mailing list with a description
270 of what it does. (But not before you test it! See the next section for some
271 guidelines.) It is preferred that patches be sent as attachments, but it is
274 Also, feel free to help test other people's patches and reply to them with
275 comments. You can apply a patch by saving it into your busybox/ directory and
276 typing 'patch < mychanges.patch'. Then you can recompile, see if it runs, test
277 if it works as advertised, and post your findings to the mailing list.
279 NOTE: Please do not include extraneous or irrelevant changes in your patches.
280 Please do not try to "bundle" two patches together into one. Make single,
281 discreet changes on a per-patch basis. Sometimes you need to make a patch that
282 touches code in many places, but these kind of patches are rare and should be
283 coordinated with a maintainer.
289 It's considered good form to test your new feature before you submit a patch
290 to the mailing list, and especially before you commit a change to CVS. Here
291 are some guidelines on how to test your changes.
293 - Always test Busybox applets against GNU counterparts and make sure the
294 behavior / output is identical between the two.
296 - Try several different permutations and combinations of the features you're
297 adding (i.e. different combinations of command-line switches) and make sure
298 they all work; make sure one feature does not interfere with another.
300 - Make sure you test compiling against the source both with the feature
301 turned on and turned off in Config.h and make sure Busybox compiles cleanly
304 - Run the multibuild.pl script in the tests directory and make sure
305 everything checks out OK. (Do this from within the busybox/ directory by
306 typing: 'tests/multibuild.pl'.)
309 Making Sure Your Patch Doesn't Get Lost
310 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
312 If you don't want your patch to be lost or forgotten, send it to the bug
313 tracking system (http://bugs.lineo.com). You do this by emailing your patch in
314 a message to submit@bugs.lineo.com with a subject line something like this:
316 [PATCH] - Adds "transmogrify" feature to "foo"
318 In the body, you should have a pseudo-header that looks like the following:
321 Version: v0.50pre (or whatever the current version is)
324 The remainder of the body should read along these lines:
326 This patch adds the "transmogrify" feature to the "foo" applet. I have
327 tested this on [arch] system(s) and it works. I have tested it against the
328 GNU counterparts and the outputs are identical. I have run the scripts in
329 the 'tests' directory and nothing breaks.
331 Detailed instructions on how to submit a bug to the tracking system are at:
333 http://bugs.lineo.com/Reporting.html
337 Improving Your Chances of Patch Acceptance
338 ------------------------------------------
340 Even after you send a brilliant patch to the mailing list, sometimes it can go
341 unnoticed, un-replied-to, and sometimes (sigh) even lost. This is an
342 unfortunate fact of life, but there are steps you can take to help your patch
343 get noticed and convince a maintainer that it should be added:
349 A patch that includes small, isolated, obvious changes is more likely to be
350 accepted than a patch that touches code in lots of different places or makes
351 sweeping, dubious changes.
357 Hard facts on why your patch is better than the existing code will go a long
358 way toward convincing maintainers that your patch should be included.
359 Specifically, patches are more likely to be accepted if they are provably more
360 correct, smaller, faster, simpler, or more maintainable than the existing
363 Conversely, any patch that is supported with nothing more than "I think this
364 would be cool" or "this patch is good because I say it is and I've got a Phd
365 in Computer Science" will likely be ignored.
368 Follow The Style Guide
369 ~~~~~~~~~~~~~~~~~~~~~~
371 It's considered good form to abide by the established coding style used in a
372 project; Busybox is no exception. We have gone so far as to delineate the
373 "elements of Busybox style" in the file docs/style-guide.txt. Please follow
377 Work With Someone Else
378 ~~~~~~~~~~~~~~~~~~~~~~
380 Working on a patch in isolation is less effective than working with someone
381 else for a variety of reasons. If another Busybox user is interested in what
382 you're doing, then it's two (or more) voices instead of one that can petition
383 for inclusion of the patch. You'll also have more people that can test your
384 changes, or even offer suggestions on better approaches you could take.
386 Getting other folks interested follows as a natural course if you've received
387 responses from queries to applet maintainer or positive responses from folks
390 We've made strident efforts to put a useful "collaboration" infrastructure in
391 place in the form of mailing lists, the bug tracking system, and CVS. Please
398 The old saying "You'll catch more flies with honey than you will with vinegar"
399 applies when submitting patches to the mailing list for approval. The way you
400 present your patch is sometimes just as important as the actual patch itself
401 (if not more so). Being rude to the maintainers is not an effective way to
402 convince them that your patch should be included; it will likely have the
407 Committing Changes to CVS
408 -------------------------
410 If you submit several patches that demonstrate that you are a skilled and wise
411 coder, you may be invited to become a committer, thus enabling you to commit
412 changes directly to CVS. This is nice because you don't have to wait for
413 someone else to commit your change for you, you can just do it yourself.
415 But note that this is a priviledge that comes with some responsibilities. You
416 should test your changes before you commit them. You should also talk to an
417 applet maintainer before you make any kind of sweeping changes to somebody
418 else's code. Big changes should still go to the mailing list first. Remember,
419 being wise, polite, and discreet is more important than being clever.
425 Generally, you should feel free to commit a change if:
427 - Your changes are small and don't touch many files
428 - You are fixing a bug
429 - Somebody has told you that it's okay
430 - It's obviously the Right Thing
432 The more of the above are true, the better it is to just commit a change
439 Even if you have commit rights, you should probably still post a patch to the
442 - Your changes are broad and touch many different files
443 - You are adding a feature
444 - Your changes are speculative or experimental (i.e. trying a new algorithm)
445 - You are not the maintainer and your changes make the maintainer cringe
447 The more of the above are true, the better it is to post a patch to the
448 mailing list instead of committing.
455 If all of this seems complicated, don't panic, it's really not that tough. If
456 you're having difficulty following some of the steps outlined in this
457 document don't worry, the folks on the Busybox mailing list are a fairly
458 good-natured bunch and will work with you to help get your patches into shape
459 or help you make contributions.