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

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

Revision 532 - (hide annotations) (download)
Sat Sep 1 22:45:15 2007 UTC (16 years, 8 months ago) by niro
File MIME type: text/plain
File size: 3983 byte(s)

-import if magellan mkinitrd; it is a fork of redhats mkinitrd-5.0.8 with all magellan patches and features; deprecates magellan-src/mkinitrd

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			Thomas Lundquist - Added stuff for the new directory layout.
10
11			Initial Write
12			-------------
13
14			First, write your applet. Be sure to include copyright information at the top,
15			such as who you stole the code from and so forth. Also include the mini-GPL
16			boilerplate. Be sure to name the main function <applet>_main instead of main.
17			And be sure to put it in <applet>.c. Usage does not have to be taken care of by
18			your applet.
19			Make sure to #include "busybox.h" as the first include file in your applet so
20			the bb_config.h and appropriate platform specific files are included properly.
21
22			For a new applet mu, here is the code that would go in mu.c:
23
24			----begin example code------
25
26			/* vi: set sw=4 ts=4: */
27			/*
28			* Mini mu implementation for busybox
29			*
30			* Copyright (C) [YEAR] by [YOUR NAME] <YOUR EMAIL>
31			*
32			* Licensed under GPLv2 or later, see file LICENSE in this tarball for details.
33			*/
34
35			#include "busybox.h"
36			#include <other.h>
37
38			int mu_main(int argc, char **argv)
39			{
40			int fd;
41			char mu;
42
43			fd = xopen("/dev/random", O_RDONLY);
44
45			if ((n = safe_read(fd, &mu, 1)) < 1)
46			bb_perror_msg_and_die("/dev/random");
47
48			return mu;
49			}
50
51			----end example code------
52
53
54			Coding Style
55			------------
56
57			Before you submit your applet for inclusion in BusyBox, (or better yet, before
58			you _write_ your applet) please read through the style guide in the docs
59			directory and make your program compliant.
60
61
62			Some Words on libbb
63			-------------------
64
65			As you are writing your applet, please be aware of the body of pre-existing
66			useful functions in libbb. Use these instead of reinventing the wheel.
67
68			Additionally, if you have any useful, general-purpose functions in your
69			applet that could be useful in other applets, consider putting them in libbb.
70
71
72			Placement / Directory
73			---------------------
74
75			Find the appropriate directory for your new applet.
76
77			Make sure you find the appropriate places in the files, the applets are
78			sorted alphabetically.
79
80			Add the applet to Makefile.in in the chosen directory:
81
82			obj-$(CONFIG_MU) += mu.o
83
84			Add the applet to Config.in in the chosen directory:
85
86			config CONFIG_MU
87			bool "MU"
88			default n
89			help
90			Returns an indeterminate value.
91
92
93			Usage String(s)
94			---------------
95
96			Next, add usage information for you applet to include/usage.h.
97			This should look like the following:
98
99			#define mu_trivial_usage \
100			"-[abcde] FILES"
101			#define mu_full_usage \
102			"Returns an indeterminate value.\n\n" \
103			"Options:\n" \
104			"\t-a\t\tfirst function\n" \
105			"\t-b\t\tsecond function\n" \
106			...
107
108			If your program supports flags, the flags should be mentioned on the first
109			line (-[abcde]) and a detailed description of each flag should go in the
110			mu_full_usage section, one flag per line. (Numerous examples of this
111			currently exist in usage.h.)
112
113
114			Header Files
115			------------
116
117			Next, add an entry to include/applets.h. Be sure to keep the list
118			in alphabetical order, or else it will break the binary-search lookup
119			algorithm in busybox.c and the Gods of BusyBox smite you. Yea, verily:
120
121			/* all programs above here are alphabetically "less than" 'mu' */
122			#ifdef CONFIG_MU
123			APPLET("mu", mu_main, _BB_DIR_USR_BIN, mu_usage)
124			#endif
125			/* all programs below here are alphabetically "greater than" 'mu' */
126
127
128			Documentation
129			-------------
130
131			If you're feeling especially nice, you should also document your applet in the
132			docs directory (but nobody ever does that).
133
134			Adding some text to docs/Configure.help is a nice start.
135
136
137			The Grand Announcement
138			----------------------
139
140			Then create a diff -urN of the files you added and/or modified. Typically:
141			<appletdir>/<applet>.c
142			include/usage.c
143			include/applets.h
144			<appletdir>/Makefile.in
145			<appletdir>/config.in
146			and send it to the mailing list:
147			busybox@busybox.net
148			http://busybox.net/mailman/listinfo/busybox
149
150			Sending patches as attachments is preferred, but not required.