1How to Add a New Applet to BusyBox
2==================================
3
4This document details the steps you must take to add a new applet to BusyBox.
5
6Credits:
7Matt Kraai - initial writeup
8Mark Whitley - the remix
9
10
11Initial Write
12-------------
13
14First, write your applet.  Be sure to include copyright information at the
15top, such as who you stole the code from and so forth. Also include the
16mini-GPL boilerplate. Be sure to name the main function <applet>_main instead
17of main.  And be sure to put it in <applet>.c.  For a new applet mu, here is
18the code that would go in mu.c:
19
20----begin example code------
21
22/* vi: set sw=4 ts=4: */
23/*
24 * Mini mu implementation for busybox
25 *
26 *
27 * Copyright (C) [YEAR] by [YOUR NAME] <YOUR EMAIL>
28 *
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.
33 *
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.
38 *
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
42 * 02111-1307 USA
43 *
44 */
45
46#include "busybox.h"
47
48int mu_main(int argc, char **argv)
49{
50	int fd;
51	char mu;
52
53	if ((fd = open("/dev/random", O_RDONLY)) < 0)
54		perror_msg_and_die("/dev/random");
55
56	if ((n = safe_read(fd, &mu, 1)) < 1)
57		perror_msg_and_die("/dev/random");
58
59	return mu;
60}
61
62----end example code------
63
64
65Coding Style
66------------
67
68Before you submit your applet for inclusion in BusyBox, (or better yet, before
69you _write_ your applet) please read through the style guide in the docs
70directory and make your program compliant.
71
72
73Some Words on libbb
74-------------------
75
76As you are writing your applet, please be aware of the body of pre-existing
77useful functions in libbb. Use these instead of reinventing the wheel.
78
79Additionally, if you have any useful, general-purpose functions in your
80program that could be useful in another program, consider putting them in
81libbb.
82
83
84Usage String(s)
85---------------
86
87Next, add usage information for you applet to usage.h. This should look like
88the following:
89
90	#define mu_trivial_usage \
91		"-[abcde] FILES"
92	#define mu_full_usage \
93		"Returns an indeterminate value.\n\n" \
94		"Options:\n" \
95		"\t-a\t\tfirst function\n" \
96		"\t-b\t\tsecond function\n" \
97
98If your program supports flags, the flags should be mentioned on the first
99line (-[abcde]) and a detailed description of each flag should go in the
100mu_full_usage section, one flag per line. (Numerous examples of this
101currently exist in usage.h.)
102
103
104Header Files
105------------
106
107Next, add an entry to applets.h.  Be *sure* to keep the list in alphabetical
108order, or else it will break the binary-search lookup algorithm in busybox.c
109and the Gods of BusyBox smite you. Yea, verily:
110
111	/* all programs above here are alphabetically "less than" 'mu' */
112	#ifdef BB_MU
113		APPLET("mu", mu_main, _BB_DIR_USR_BIN, mu_usage)
114	#endif
115	/* all programs below here are alphabetically "greater than" 'mu' */
116
117
118Finally, add a define for your applet to Config.h:
119
120	#define BB_MU
121
122
123Documentation
124-------------
125
126If you're feeling especially nice, you should also document your applet in the
127docs directory (but nobody ever does that).
128
129
130The Grand Announcement
131----------------------
132
133Then create a diff -urN of the files you added (<applet>.c, usage.c,
134applets.h, Config.h) and send it to the mailing list:
135busybox@opensource.lineo.com. Sending patches as attachments is preferred, but
136not required.
137
138
139