1 How to Add a New Applet to BusyBox
2 ==================================
4 This document details the steps you must take to add a new applet to BusyBox.
7 Matt Kraai - initial writeup
8 Mark Whitley - the remix
9 Thomas Lundquist - Added stuff for the new directory layout.
14 First, write your applet. Be sure to include copyright information at the
15 top, such as who you stole the code from and so forth. Also include the
16 mini-GPL boilerplate. Be sure to name the main function <applet>_main instead
17 of main. And be sure to put it in <applet>.c. For a new applet mu, here is
18 the code that would go in mu.c:
20 ----begin example code------
22 /* vi: set sw=4 ts=4: */
24 * Mini mu implementation for busybox
27 * Copyright (C) [YEAR] by [YOUR NAME] <YOUR EMAIL>
29 * This program is free software; you can redistribute it and/or modify
30 * it under the terms of the GNU General Public License as published by
31 * the Free Software Foundation; either version 2 of the License, or
32 * (at your option) any later version.
34 * This program is distributed in the hope that it will be useful,
35 * but WITHOUT ANY WARRANTY; without even the implied warranty of
36 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
37 * General Public License for more details.
39 * You should have received a copy of the GNU General Public License
40 * along with this program; if not, write to the Free Software
41 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
48 int mu_main(int argc, char **argv)
53 if ((fd = open("/dev/random", O_RDONLY)) < 0)
54 perror_msg_and_die("/dev/random");
56 if ((n = safe_read(fd, &mu, 1)) < 1)
57 perror_msg_and_die("/dev/random");
62 ----end example code------
68 Before you submit your applet for inclusion in BusyBox, (or better yet, before
69 you _write_ your applet) please read through the style guide in the docs
70 directory and make your program compliant.
76 As you are writing your applet, please be aware of the body of pre-existing
77 useful functions in libbb. Use these instead of reinventing the wheel.
79 Additionally, if you have any useful, general-purpose functions in your
80 program that could be useful in another program, consider putting them in
87 Find the appropriate directory for your new applet.
89 Add the applet to the applet directory Makefile:
91 obj-$(CONFIG_MU) += mu.o
93 Add the applet to the applet directory config.in:
101 Next, add usage information for you applet to include/usage.h.
102 This should look like the following:
104 #define mu_trivial_usage \
106 #define mu_full_usage \
107 "Returns an indeterminate value.\n\n" \
109 "\t-a\t\tfirst function\n" \
110 "\t-b\t\tsecond function\n" \
112 If your program supports flags, the flags should be mentioned on the first
113 line (-[abcde]) and a detailed description of each flag should go in the
114 mu_full_usage section, one flag per line. (Numerous examples of this
115 currently exist in usage.h.)
121 Next, add an entry to include/applets.h. Be *sure* to keep the list
122 in alphabetical order, or else it will break the binary-search lookup
123 algorithm in busybox.c and the Gods of BusyBox smite you. Yea, verily:
125 /* all programs above here are alphabetically "less than" 'mu' */
127 APPLET("mu", mu_main, _BB_DIR_USR_BIN, mu_usage)
129 /* all programs below here are alphabetically "greater than" 'mu' */
132 Finally, add a define for your applet to Config.h:
140 If you're feeling especially nice, you should also document your applet in the
141 docs directory (but nobody ever does that).
143 Adding some text to docs/Configure.help is a nice start.
146 The Grand Announcement
147 ----------------------
149 Then create a diff -urN of the files you added (<applet>.c, usage.c,
150 applets.h, Config.h) and send it to the mailing list:
151 busybox@busybox.net. Sending patches as attachments is preferred, but