/[magellan-source]/trunk/mkinitrd-magellan/busybox/docs/new-applet-HOWTO.txt

Annotation of /trunk/mkinitrd-magellan/busybox/docs/new-applet-HOWTO.txt

Revision 984 - (hide annotations) (download)
Sun May 30 11:32:42 2010 UTC (14 years ago) by niro
File MIME type: text/plain
File size: 4900 byte(s)

-updated to busybox-1.16.1 and enabled blkid/uuid support in default config

1	niro	532	How to Add a New Applet to BusyBox
2			==================================
3
4			This document details the steps you must take to add a new applet to BusyBox.
5
6			Credits:
7			Matt Kraai - initial writeup
8			Mark Whitley - the remix
9	niro	816	Thomas Lundquist - Trying to keep it updated.
10	niro	532
11	niro	816	When doing this you should consider using the latest svn trunk.
12	niro	984	This is a good thing if you plan to getting it committed into mainline.
13	niro	816
14	niro	532	Initial Write
15			-------------
16
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
21			your applet.
22	niro	816	Make sure to #include "libbb.h" as the first include file in your applet so
23	niro	532	the bb_config.h and appropriate platform specific files are included properly.
24
25			For a new applet mu, here is the code that would go in mu.c:
26
27	niro	816	(busybox.h already includes most usual header files. You do not need
28			#include <stdio.h> etc...)
29
30
31	niro	532	----begin example code------
32
33			/* vi: set sw=4 ts=4: */
34			/*
35			* Mini mu implementation for busybox
36			*
37			* Copyright (C) [YEAR] by [YOUR NAME] <YOUR EMAIL>
38			*
39			* Licensed under GPLv2 or later, see file LICENSE in this tarball for details.
40			*/
41
42	niro	816	#include "libbb.h"
43			#include "other.h"
44	niro	532
45	niro	816	int mu_main(int argc, char **argv) MAIN_EXTERNALLY_VISIBLE;
46	niro	532	int mu_main(int argc, char **argv)
47			{
48			int fd;
49	niro	816	ssize_t n;
50	niro	532	char mu;
51
52			fd = xopen("/dev/random", O_RDONLY);
53
54			if ((n = safe_read(fd, &mu, 1)) < 1)
55			bb_perror_msg_and_die("/dev/random");
56
57			return mu;
58			}
59
60			----end example code------
61
62
63			Coding Style
64			------------
65
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.
69
70
71			Some Words on libbb
72			-------------------
73
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.
76
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.
79
80	niro	816	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.
83	niro	532
84	niro	816	Adding a libbb function:
85			------------------------
86
87			Make a new file named <function_name>.c
88
89			----start example code------
90
91			#include "libbb.h"
92			#include "other.h"
93
94			int function(char *a)
95			{
96			return *a;
97			}
98
99			----end example code------
100
101			Add <function_name>.o in the right alphabetically sorted place
102			in libbb/Kbuild. You should look at the conditional part of
103			libbb/Kbuild aswell.
104
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.
108
109			You can look at libbb/Config.in and try to find out if the function is
110	niro	984	tunable and add it there if it is.
111	niro	816
112
113	niro	532	Placement / Directory
114			---------------------
115
116			Find the appropriate directory for your new applet.
117
118			Make sure you find the appropriate places in the files, the applets are
119			sorted alphabetically.
120
121	niro	816	Add the applet to Kbuild in the chosen directory:
122	niro	532
123	niro	816	lib-$(CONFIG_MU) += mu.o
124	niro	532
125			Add the applet to Config.in in the chosen directory:
126
127	niro	816	config MU
128	niro	532	bool "MU"
129			default n
130			help
131			Returns an indeterminate value.
132
133
134			Usage String(s)
135			---------------
136
137			Next, add usage information for you applet to include/usage.h.
138			This should look like the following:
139
140			#define mu_trivial_usage \
141			"-[abcde] FILES"
142			#define mu_full_usage \
143			"Returns an indeterminate value.\n\n" \
144			"Options:\n" \
145			"\t-a\t\tfirst function\n" \
146			"\t-b\t\tsecond function\n" \
147			...
148
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.)
153
154
155			Header Files
156			------------
157
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:
161
162	niro	816	Be sure to read the top of applets.h before adding your applet.
163
164	niro	532	/* all programs above here are alphabetically "less than" 'mu' */
165	niro	984	IF_MU(APPLET(mu, _BB_DIR_USR_BIN, _BB_SUID_DROP))
166	niro	532	/* all programs below here are alphabetically "greater than" 'mu' */
167
168
169			The Grand Announcement
170			----------------------
171
172	niro	816	Then create a diff by adding the new files with svn (remember your libbb files)
173			svn add <where you put it>/mu.c
174			eventually also:
175			svn add libbb/function.c
176			then
177			svn diff
178	niro	532	and send it to the mailing list:
179			busybox@busybox.net
180			http://busybox.net/mailman/listinfo/busybox
181
182			Sending patches as attachments is preferred, but not required.