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 and Config.in/Kbuild/usage/applet.h snippets (more on that below
20 in this document). Be sure to name the main function <applet>_main instead
21 of main. And be sure to put it in <applet>.c. Make sure to #include "libbb.h"
22 as the first include file in your applet.
24 For a new applet mu, here is the code that would go in mu.c:
26 (busybox.h already includes most usual header files. You do not need
27 #include <stdio.h> etc...)
30 ----begin example code------
32 /* vi: set sw=4 ts=4: */
34 * Mini mu implementation for busybox
36 * Copyright (C) [YEAR] by [YOUR NAME] <YOUR EMAIL>
38 * Licensed under GPLv2, see file LICENSE in this source tree.
48 //config: Returns an indeterminate value.
50 //kbuild:lib-$(CONFIG_MU) += mu.o
51 //applet:IF_MU(APPLET(mu, BB_DIR_USR_BIN, BB_SUID_DROP))
53 //usage:#define mu_trivial_usage
54 //usage: "-[abcde] FILES"
55 //usage:#define mu_full_usage
56 //usage: "Returns an indeterminate value.\n\n"
58 //usage: "\t-a\t\tfirst function\n"
59 //usage: "\t-b\t\tsecond function\n"
61 int mu_main(int argc, char **argv) MAIN_EXTERNALLY_VISIBLE;
62 int mu_main(int argc, char **argv)
68 fd = xopen("/dev/random", O_RDONLY);
70 if ((n = safe_read(fd, &mu, 1)) < 1)
71 bb_perror_msg_and_die("/dev/random");
76 ----end example code------
82 Before you submit your applet for inclusion in BusyBox, (or better yet, before
83 you _write_ your applet) please read through the style guide in the docs
84 directory and make your program compliant.
90 As you are writing your applet, please be aware of the body of pre-existing
91 useful functions in libbb. Use these instead of reinventing the wheel.
93 Additionally, if you have any useful, general-purpose functions in your
94 applet that could be useful in other applets, consider putting them in libbb.
96 And it may be possible that some of the other applets uses functions you
97 could use. If so, you have to rip the function out of the applet and make
98 a libbb function out of it.
100 Adding a libbb function:
101 ------------------------
103 Make a new file named <function_name>.c
105 ----start example code------
110 //kbuild:lib-y += function.o
112 int function(char *a)
117 ----end example code------
119 Remember about the kbuild snippet.
121 You should also try to find a suitable place in include/libbb.h for
122 the function declaration. If not, add it somewhere anyway, with or without
123 ifdefs to include or not.
125 You can look at libbb/Config.src and try to find out if the function is
126 tunable and add it there if it is.
129 Kbuild/Config.in/usage/applets.h snippets in .c files
130 -----------------------------------------------------
132 The old way of adding new applets was to put all the information needed by the
133 configuration and build system into appropriate files (namely: Kbuild.src and
134 Config.src in new applet's directory) and to add the applet declaration and
135 usage info text to include/applets.src.h and include/usage.src.h respectively.
137 Since the scripts/gen_build_files.sh script had been introduced, the preferred
138 way is to have all these declarations contained within the applet .c files.
140 Every line intended to be processed by gen_build_files.sh should start as a
141 comment without any preceding whitespaces and be followed by an appropriate
142 keyword - kbuild, config, usage or applet - and a colon, just like shown in the
146 Placement / Directory
147 ---------------------
149 Find the appropriate directory for your new applet.
151 Add the kbuild snippet to the .c file:
153 //kbuild:lib-$(CONFIG_MU) += mu.o
155 Add the config snippet to the .c file:
161 //config: Returns an indeterminate value.
167 Next, add usage information for your applet to the .c file.
168 This should look like the following:
170 //usage:#define mu_trivial_usage
171 //usage: "-[abcde] FILES"
172 //usage:#define mu_full_usage
173 //usage: "Returns an indeterminate value.\n\n"
174 //usage: "Options:\n"
175 //usage: "\t-a\t\tfirst function\n"
176 //usage: "\t-b\t\tsecond function\n"
179 If your program supports flags, the flags should be mentioned on the first
180 line (-[abcde]) and a detailed description of each flag should go in the
181 mu_full_usage section, one flag per line. (Numerous examples of this
182 currently exist in usage.src.h.)
188 Finally add the applet declaration snippet. Be sure to read the top of
189 applets.src.h before adding your applet - it contains important info
190 on applet macros and conventions.
192 //applet:IF_MU(APPLET(mu, BB_DIR_USR_BIN, BB_SUID_DROP))
195 The Grand Announcement
196 ----------------------
198 Then create a diff by adding the new files to git (remember your libbb files)
199 git add <where you put it>/mu.c
201 git add libbb/function.c
204 git format-patch HEAD^
205 and send it to the mailing list:
207 http://busybox.net/mailman/listinfo/busybox
209 Sending patches as attachments is preferred, but not required.