|Contributing To Busybox
|This document describes what you need to do to contribute to Busybox, where
|you can help, guidelines on testing, and how to submit a well-formed patch
|that is more likely to be accepted.
|The Busybox home page is at: http://busybox.net/
|So you want to contribute to Busybox, eh? Great, wonderful, glad you want to
|help. However, before you dive in, headlong and hotfoot, there are some things
|you need to do:
|Checkout the Latest Code from CVS
|This is a necessary first step. Please do not try to work with the last
|released version, as there is a good chance that somebody has already fixed
|the bug you found. Somebody might have even added the feature you had in mind.
|Don't make your work obsolete before you start!
|For information on how to check out Busybox from CVS, please look at the
|Read the Mailing List
|No one is required to read the entire archives of the mailing list, but you
|should at least read up on what people have been talking about lately. If
|you've recently discovered a problem, chances are somebody else has too. If
|you're the first to discover a problem, post a message and let the rest of us
|Archives can be found here:
|If you have a serious interest in Busybox, i.e., you are using it day-to-day or
|as part of an embedded project, it would be a good idea to join the mailing
|A web-based sign-up form can be found here:
|Coordinate with the Applet Maintainer
|Some (not all) of the applets in Busybox are "owned" by a maintainer who has
|put significant effort into it and is probably more familiar with it than
|others. To find the maintainer of an applet, look at the top of the .c file
|for a name following the word 'Copyright' or 'Written by' or 'Maintainer'.
|Before plunging ahead, it's a good idea to send a message to the mailing list
|that says: "Hey, I was thinking about adding the 'transmogrify' feature to the
|'foo' applet. Would this be useful? Is anyone else working on it?" You might
|want to CC the maintainer (if any) with your question.
|Areas Where You Can Help
|Busybox can always use improvement! If you're looking for ways to help, there
|are a variety of areas where you could help.
|What Busybox Doesn't Need
|Before listing the areas where you _can_ help, it's worthwhile to mention the
|areas where you shouldn't bother. While Busybox strives to be the "Swiss Army
|Knife" of embedded Linux, there are some applets that will not be accepted:
|- Any filesystem manipulation tools: Busybox is filesystem independent and
|we do not want to start adding mkfs/fsck tools for every (or any)
|filesystem under the sun. (fsck_minix.c and mkfs_minix.c are living on
|borrowed time.) There are far too many of these tools out there. Use
|the upstream version. Not everything has to be part of Busybox.
|- Any partitioning tools: Partitioning a device is typically done once and
|only once, and tools which do this generally do not need to reside on the
|target device (esp a flash device). If you need a partitioning tool, grab
|one (such as fdisk, sfdisk, or cfdisk from util-linux) and use that, but
|don't try to merge it into busybox. These are nasty and complex and we
|don't want to maintain them.
|- Any disk, device, or media-specific tools: Use the -utils or -tools package
|that was designed for your device; don't try to shoehorn them into Busybox.
|- Any architecture specific tools: Busybox is (or should be) architecture
|independent. Do not send us tools that cannot be used across multiple
|platforms / arches.
|- Any daemons that are not essential to basic system operation. To date, only
|syslogd and klogd meet this requirement. We do not need a web server, an
|ftp daemon, a dhcp server, a mail transport agent or a dns resolver. If you
|need one of those, you are welcome to ask the folks on the mailing list for
|recommendations, but please don't bloat up Busybox with any of these.
|If you find bugs, please submit a detailed bug report to the busybox mailing
|list at firstname.lastname@example.org. A well-written bug report should include a
|transcript of a shell session that demonstrates the bad behavior and enables
|anyone else to duplicate the bug on their own machine. The following is such
|Subject: /bin/date doesn't work
|When I execute Busybox 'date' it produces unexpected results.
|With GNU date I get the following output:
|Wed Mar 21 14:19:41 MST 2001
|But when I use BusyBox date I get this instead:
|I am using Debian unstable, kernel version 2.4.19-rmk1 on an Netwinder,
|and the latest uClibc from CVS. Thanks for the wonderful program!
|Note the careful description and use of examples showing not only what BusyBox
|does, but also a counter example showing what an equivalent GNU app does. Bug
|reports lacking such detail may never be fixed... Thanks for understanding.
|Chances are, documentation in Busybox is either missing or needs improvement.
|Either way, help is welcome.
|Work is being done to automatically generate documentation from sources,
|especially from the usage.h file. If you want to correct the documentation,
|please make changes to the pre-generation parts, rather than the generated
|documentation. [More to come on this later...]
|It is preferred that modifications to documentation be submitted in patch
|format (more on this below), but we're a little more lenient when it comes to
|docs. You could, for example, just say "after the listing of the mount
|options, the following example would be helpful..."
|Consult Existing Sources
|For a quick listing of "needs work" spots in the sources, cd into the Busybox
|directory and run the following:
|for i in TODO FIXME XXX; do find -name '*.[ch]'|xargs grep $i; done
|This will show all of the trouble spots or 'questionable' code. Pick a spot,
|any spot, these are all invitations for you to contribute.
|Add a New Applet
|If you want to add a new applet to Busybox, we'd love to see it. However,
|before you write any code, please ask beforehand on the mailing list something
|like "Do you think applet 'foo' would be useful in Busybox?" or "Would you
|guys accept applet 'foo' into Busybox if I were to write it?" If the answer is
|"no" by the folks on the mailing list, then you've saved yourself some time.
|Conversely, you could get some positive responses from folks who might be
|interested in helping you implement it, or can recommend the best approach.
|Perhaps most importantly, this is your way of calling "dibs" on something and
|avoiding duplication of effort.
|Also, before you write a line of code, please read the 'new-applet-HOWTO.txt'
|file in the docs/ directory.
|These are dirty jobs, but somebody's gotta do 'em.
|- Converting applets to use getopt() for option processing. Type 'find -name
|'*.c'|grep -L getopt' to get a listing of the applets that currently don't
|use getopt. If a .c file processes no options, it should have a line that
|reads: /* no options, no getopt */ somewhere in the file.
|- Replace any "naked" calls to malloc, calloc, realloc, str[n]dup, fopen with
|the x* equivalents found in libbb/xfuncs.c.
|- Security audits:
|- Synthetic code removal: http://www.perl.com/pub/2000/06/commify.html - This
|is very Perl-specific, but the advice given in here applies equally well to
|- C library function use audits: Verifying that functions are being used
|properly (called with the right args), replacing unsafe library functions
|with safer versions, making sure return codes are being checked, etc.
|- Where appropriate, replace preprocessor defined macros and values with
|- Style guide compliance. See: docs/style-guide.txt
|- Add testcases to tests/testcases.
|- Makefile improvements:
|(I think the recursive problems are pretty much taken care of at this point, non?)
|- "Ten Commandments" compliance: (this is a "maybe", certainly not as
|important as any of the previous items.)
|Other useful links:
|- the comp.lang.c FAQ: http://web.onetelnet.ch/~twolf/tw/c/index.html#Sources
|Submitting Patches To Busybox
|Here are some guidelines on how to submit a patch to Busybox.
|Making A Patch
|If you've got anonymous CVS access set up, making a patch is simple. Just make
|sure you're in the busybox/ directory and type 'cvs diff -bwu > mychanges.patch'.
|You can send the resulting .patch file to the mailing list with a description
|of what it does. (But not before you test it! See the next section for some
|guidelines.) It is preferred that patches be sent as attachments, but it is
|Also, feel free to help test other people's patches and reply to them with
|comments. You can apply a patch by saving it into your busybox/ directory and
|typing 'patch < mychanges.patch'. Then you can recompile, see if it runs, test
|if it works as advertised, and post your findings to the mailing list.
|NOTE: Please do not include extraneous or irrelevant changes in your patches.
|Please do not try to "bundle" two patches together into one. Make single,
|discreet changes on a per-patch basis. Sometimes you need to make a patch that
|touches code in many places, but these kind of patches are rare and should be
|coordinated with a maintainer.
|It's considered good form to test your new feature before you submit a patch
|to the mailing list, and especially before you commit a change to CVS. Here
|are some guidelines on how to test your changes.
|- Always test Busybox applets against GNU counterparts and make sure the
|behavior / output is identical between the two.
|- Try several different permutations and combinations of the features you're
|adding (i.e., different combinations of command-line switches) and make sure
|they all work; make sure one feature does not interfere with another.
|- Make sure you test compiling against the source both with the feature
|turned on and turned off in Config.h and make sure Busybox compiles cleanly
|- Run the multibuild.pl script in the tests directory and make sure
|everything checks out OK. (Do this from within the busybox/ directory by
|Making Sure Your Patch Doesn't Get Lost
|If you don't want your patch to be lost or forgotten, send it to the busybox
|mailing list with a subject line something like this:
|[PATCH] - Adds "transmogrify" feature to "foo"
|In the body, you should have a pseudo-header that looks like the following:
|Version: v1.01pre (or whatever the current version is)
|The remainder of the body should read along these lines:
|This patch adds the "transmogrify" feature to the "foo" applet. I have
|tested this on [arch] system(s) and it works. I have tested it against the
|GNU counterparts and the outputs are identical. I have run the scripts in
|the 'tests' directory and nothing breaks.
|Improving Your Chances of Patch Acceptance
|Even after you send a brilliant patch to the mailing list, sometimes it can go
|unnoticed, un-replied-to, and sometimes (sigh) even lost. This is an
|unfortunate fact of life, but there are steps you can take to help your patch
|get noticed and convince a maintainer that it should be added:
|A patch that includes small, isolated, obvious changes is more likely to be
|accepted than a patch that touches code in lots of different places or makes
|sweeping, dubious changes.
|Back It Up
|Hard facts on why your patch is better than the existing code will go a long
|way toward convincing maintainers that your patch should be included.
|Specifically, patches are more likely to be accepted if they are provably more
|correct, smaller, faster, simpler, or more maintainable than the existing
|Conversely, any patch that is supported with nothing more than "I think this
|would be cool" or "this patch is good because I say it is and I've got a Phd
|in Computer Science" will likely be ignored.
|Follow The Style Guide
|It's considered good form to abide by the established coding style used in a
|project; Busybox is no exception. We have gone so far as to delineate the
|"elements of Busybox style" in the file docs/style-guide.txt. Please follow
|Work With Someone Else
|Working on a patch in isolation is less effective than working with someone
|else for a variety of reasons. If another Busybox user is interested in what
|you're doing, then it's two (or more) voices instead of one that can petition
|for inclusion of the patch. You'll also have more people that can test your
|changes, or even offer suggestions on better approaches you could take.
|Getting other folks interested follows as a natural course if you've received
|responses from queries to applet maintainer or positive responses from folks
|on the mailing list.
|We've made strident efforts to put a useful "collaboration" infrastructure in
|place in the form of mailing lists, the bug tracking system, and CVS. Please
|use these resources.
|Send Patches to the Bug Tracking System
|This was mentioned above in the "Making Sure Your Patch Doesn't Get Lost"
|section, but it is worth mentioning again. A patch sent to the mailing list
|might be unnoticed and forgotten. A patch sent to the bug tracking system will
|be stored and closely connected to the bug it fixes.
|The old saying "You'll catch more flies with honey than you will with vinegar"
|applies when submitting patches to the mailing list for approval. The way you
|present your patch is sometimes just as important as the actual patch itself
|(if not more so). Being rude to the maintainers is not an effective way to
|convince them that your patch should be included; it will likely have the
|Committing Changes to CVS
|If you submit several patches that demonstrate that you are a skilled and wise
|coder, you may be invited to become a committer, thus enabling you to commit
|changes directly to CVS. This is nice because you don't have to wait for
|someone else to commit your change for you, you can just do it yourself.
|But note that this is a privilege that comes with some responsibilities. You
|should test your changes before you commit them. You should also talk to an
|applet maintainer before you make any kind of sweeping changes to somebody
|else's code. Big changes should still go to the mailing list first. Remember,
|being wise, polite, and discreet is more important than being clever.
|When To Commit
|Generally, you should feel free to commit a change if:
|- Your changes are small and don't touch many files
|- You are fixing a bug
|- Somebody has told you that it's okay
|- It's obviously the Right Thing
|The more of the above are true, the better it is to just commit a change
|directly to CVS.
|When Not To Commit
|Even if you have commit rights, you should probably still post a patch to the
|mailing list if:
|- Your changes are broad and touch many different files
|- You are adding a feature
|- Your changes are speculative or experimental (i.e., trying a new algorithm)
|- You are not the maintainer and your changes make the maintainer cringe
|The more of the above are true, the better it is to post a patch to the
|mailing list instead of committing.
|If all of this seems complicated, don't panic, it's really not that tough. If
|you're having difficulty following some of the steps outlined in this
|document don't worry, the folks on the Busybox mailing list are a fairly
|good-natured bunch and will work with you to help get your patches into shape
|or help you make contributions.