diff options
| -rw-r--r-- | docs/new-applet-HOWTO.txt | 128 |
1 files changed, 128 insertions, 0 deletions
diff --git a/docs/new-applet-HOWTO.txt b/docs/new-applet-HOWTO.txt new file mode 100644 index 000000000..c27aef828 --- /dev/null +++ b/docs/new-applet-HOWTO.txt @@ -0,0 +1,128 @@ +How to Add a New Applet to BusyBox +================================== + +This document details the steps you must take to add a new applet to BusyBox. + +Credits: +Matt Kraai - initial writeup +Mark Whitley - the remix + + +Initial Write +------------- + +First, write your applet. Be sure to include copyright information at the +top, such as who you stole the code from and so forth. Also include the +mini-GPL boilerplate. Be sure to name the main function <applet>_main instead +of main. And be sure to put it in <applet>.c. For a new applet mu, here is +the code that would go in mu.c: + +----begin example code------ + +/* vi: set sw=4 ts=4: */ +/* + * Mini mu implementation for busybox + * + * + * Copyright (C) [YEAR] by [YOUR NAME] <YOUR EMAIL> + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; either version 2 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program; if not, write to the Free Software + * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA + * 02111-1307 USA + * + */ + +#include "busybox.h" + +int mu_main(int argc, char **argv) +{ + int fd; + char mu; + + if ((fd = open("/dev/random", O_RDONLY)) < 0) + perror_msg_and_die("/dev/random"); + + if ((n = safe_read(fd, &mu, 1)) < 1) + perror_msg_and_die("/dev/random"); + + return mu; +} + +----end example code------ + +As you are writing your applet, please be aware of the body of pre-existing +useful functions in utility.c. Use these instead of reinventing the wheel. +Additionally, if you have any useful, general-purpose functions in your +program that could be useful in another program, consider putting them in +utility.c. + +Furthermore, please read through the style guide in the docs directory and +make your program compliant. + + +Usage String(s) +--------------- + +Next, add usage information for you applet to usage.c. This should look like +the following: + + #if defined BB_MU + const char mu_usage[] = + "mu\n" + #ifndef BB_FEATURE_TRIVIAL_HELP + "\nReturns an indeterminate value.\n" + #endif + ; + +If your program supports flags, the flags should be mentioned on the first +line (mu -[bcRovma]) and a detailed description of each flag should go in the +BB_FEATURE_TRIVIAL_HELP section, one flag per line. (Numerous examples of this +currently exist in utility.c.) + + +Header Files +------------ + +Next, add an entry to applets.h. Be *sure* to keep the list in alphabetical +order, or else it will break the binary-search lookup algorithm in busybox.c +and the Gods of BusyBox smite you. Yea, verily: + + /* all programs above here are alphabetically "less than" 'mu' */ + #ifdef BB_MU + APPLET("mu", mu_main, _BB_DIR_USR_BIN, mu_usage) + #endif + /* all programs below here are alphabetically "greater than" 'mu' */ + + +Finally, add a define for your applet to Config.h: + + #define BB_MU + + +Documentation +------------- + +If you're feeling especially nice, you should also document your applet in the +docs directory (but nobody ever does that). + + +The Grand Announcement +---------------------- + +Then create a diff -urN of the files you added (<applet>.c, usage.c, +applets.h, Config.h) and send it to the mailing list: +busybox@opensource.lineo.com. Sending patches as attachments is preferred, but +not required. + + |