New applet HOWTO. Written by Matt Kraai with some formating and additions by me.

This commit is contained in:
Mark Whitley 2000-12-19 17:35:24 +00:00
parent a1f9775981
commit eac2636513

128
docs/new-applet-HOWTO.txt Normal file
View File

@ -0,0 +1,128 @@
How to Add a New Applet to BusyBox
==================================
This document details the steps you must take to add a new applet to BusyBox.
Credits:
Matt Kraai - initial writeup
Mark Whitley - the remix
Initial Write
-------------
First, write your applet. Be sure to include copyright information at the
top, such as who you stole the code from and so forth. Also include the
mini-GPL boilerplate. Be sure to name the main function <applet>_main instead
of main. And be sure to put it in <applet>.c. For a new applet mu, here is
the code that would go in mu.c:
----begin example code------
/* vi: set sw=4 ts=4: */
/*
* Mini mu implementation for busybox
*
*
* Copyright (C) [YEAR] by [YOUR NAME] <YOUR EMAIL>
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation; either version 2 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
* 02111-1307 USA
*
*/
#include "busybox.h"
int mu_main(int argc, char **argv)
{
int fd;
char mu;
if ((fd = open("/dev/random", O_RDONLY)) < 0)
perror_msg_and_die("/dev/random");
if ((n = safe_read(fd, &mu, 1)) < 1)
perror_msg_and_die("/dev/random");
return mu;
}
----end example code------
As you are writing your applet, please be aware of the body of pre-existing
useful functions in utility.c. Use these instead of reinventing the wheel.
Additionally, if you have any useful, general-purpose functions in your
program that could be useful in another program, consider putting them in
utility.c.
Furthermore, please read through the style guide in the docs directory and
make your program compliant.
Usage String(s)
---------------
Next, add usage information for you applet to usage.c. This should look like
the following:
#if defined BB_MU
const char mu_usage[] =
"mu\n"
#ifndef BB_FEATURE_TRIVIAL_HELP
"\nReturns an indeterminate value.\n"
#endif
;
If your program supports flags, the flags should be mentioned on the first
line (mu -[bcRovma]) and a detailed description of each flag should go in the
BB_FEATURE_TRIVIAL_HELP section, one flag per line. (Numerous examples of this
currently exist in utility.c.)
Header Files
------------
Next, add an entry to applets.h. Be *sure* to keep the list in alphabetical
order, or else it will break the binary-search lookup algorithm in busybox.c
and the Gods of BusyBox smite you. Yea, verily:
/* all programs above here are alphabetically "less than" 'mu' */
#ifdef BB_MU
APPLET("mu", mu_main, _BB_DIR_USR_BIN, mu_usage)
#endif
/* all programs below here are alphabetically "greater than" 'mu' */
Finally, add a define for your applet to Config.h:
#define BB_MU
Documentation
-------------
If you're feeling especially nice, you should also document your applet in the
docs directory (but nobody ever does that).
The Grand Announcement
----------------------
Then create a diff -urN of the files you added (<applet>.c, usage.c,
applets.h, Config.h) and send it to the mailing list:
busybox@opensource.lineo.com. Sending patches as attachments is preferred, but
not required.