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 - Trying to keep it updated.
11 When doing this you should consider using the latest git HEAD.
12 This is a good thing if you plan to getting it committed into mainline.
17 First, write your applet. Be sure to include copyright information at the top,
18 such as who you stole the code from and so forth. Also include the mini-GPL
19 boilerplate. Be sure to name the main function <applet>_main instead of main.
20 And be sure to put it in <applet>.c. Usage does not have to be taken care of by
22 Make sure to #include "libbb.h" as the first include file in your applet so
23 the bb_config.h and appropriate platform specific files are included properly.
25 For a new applet mu, here is the code that would go in mu.c:
27 (busybox.h already includes most usual header files. You do not need
28 #include <stdio.h> etc...)
31 ----begin example code------
33 /* vi: set sw=4 ts=4: */
35 * Mini mu implementation for busybox
37 * Copyright (C) [YEAR] by [YOUR NAME] <YOUR EMAIL>
39 * Licensed under GPLv2, see file LICENSE in this tarball for details.
45 int mu_main(int argc, char **argv) MAIN_EXTERNALLY_VISIBLE;
46 int mu_main(int argc, char **argv)
52 fd = xopen("/dev/random", O_RDONLY);
54 if ((n = safe_read(fd, &mu, 1)) < 1)
55 bb_perror_msg_and_die("/dev/random");
60 ----end example code------
66 Before you submit your applet for inclusion in BusyBox, (or better yet, before
67 you _write_ your applet) please read through the style guide in the docs
68 directory and make your program compliant.
74 As you are writing your applet, please be aware of the body of pre-existing
75 useful functions in libbb. Use these instead of reinventing the wheel.
77 Additionally, if you have any useful, general-purpose functions in your
78 applet that could be useful in other applets, consider putting them in libbb.
80 And it may be possible that some of the other applets uses functions you
81 could use. If so, you have to rip the function out of the applet and make
82 a libbb function out of it.
84 Adding a libbb function:
85 ------------------------
87 Make a new file named <function_name>.c
89 ----start example code------
99 ----end example code------
101 Add <function_name>.o in the right alphabetically sorted place
102 in libbb/Kbuild. You should look at the conditional part of
105 You should also try to find a suitable place in include/libbb.h for
106 the function declaration. If not, add it somewhere anyway, with or without
107 ifdefs to include or not.
109 You can look at libbb/Config.in and try to find out if the function is
110 tunable and add it there if it is.
113 Placement / Directory
114 ---------------------
116 Find the appropriate directory for your new applet.
118 Make sure you find the appropriate places in the files, the applets are
119 sorted alphabetically.
121 Add the applet to Kbuild in the chosen directory:
123 lib-$(CONFIG_MU) += mu.o
125 Add the applet to Config.in in the chosen directory:
131 Returns an indeterminate value.
137 Next, add usage information for you applet to include/usage.h.
138 This should look like the following:
140 #define mu_trivial_usage \
142 #define mu_full_usage \
143 "Returns an indeterminate value.\n\n" \
145 "\t-a\t\tfirst function\n" \
146 "\t-b\t\tsecond function\n" \
149 If your program supports flags, the flags should be mentioned on the first
150 line (-[abcde]) and a detailed description of each flag should go in the
151 mu_full_usage section, one flag per line. (Numerous examples of this
152 currently exist in usage.h.)
158 Next, add an entry to include/applets.h. Be *sure* to keep the list
159 in alphabetical order, or else it will break the binary-search lookup
160 algorithm in busybox.c and the Gods of BusyBox smite you. Yea, verily:
162 Be sure to read the top of applets.h before adding your applet.
164 /* all programs above here are alphabetically "less than" 'mu' */
165 IF_MU(APPLET(mu, _BB_DIR_USR_BIN, _BB_SUID_DROP))
166 /* all programs below here are alphabetically "greater than" 'mu' */
169 The Grand Announcement
170 ----------------------
172 Then create a diff by adding the new files to git (remember your libbb files)
173 git add <where you put it>/mu.c
175 git add libbb/function.c
178 git format-patch HEAD^
179 and send it to the mailing list:
181 http://busybox.net/mailman/listinfo/busybox
183 Sending patches as attachments is preferred, but not required.