docs/new-applet-HOWTO.txt

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
Thomas Lundquist - Added stuff for the new directory layout.

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. Usage does not have to be taken care of by
your applet.

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)
		bb_perror_msg_and_die("/dev/random");

	if ((n = safe_read(fd, &mu, 1)) < 1)
		bb_perror_msg_and_die("/dev/random");

	return mu;
}

----end example code------


Coding Style
------------

Before you submit your applet for inclusion in BusyBox, (or better yet, before
you _write_ your applet) please read through the style guide in the docs
directory and make your program compliant.


Some Words on libbb
-------------------

As you are writing your applet, please be aware of the body of pre-existing
useful functions in libbb. Use these instead of reinventing the wheel.

Additionally, if you have any useful, general-purpose functions in your
applet that could be useful in other applets, consider putting them in libbb.


Placement / Directory
---------------------

Find the appropriate directory for your new applet.

Make sure you find the appropriate places in the files, the applets are
sorted alphabetically.

Add the applet to Makefile.in in the chosen directory:

obj-$(CONFIG_MU)               += mu.o

Add the applet to Config.in in the chosen directory:

config CONFIG_MU
	bool "MU"
	default n
	help
	  Returns an indeterminate value.


Usage String(s)
---------------

Next, add usage information for you applet to include/usage.h.
This should look like the following:

	#define mu_trivial_usage \
		"-[abcde] FILES"
	#define mu_full_usage \
		"Returns an indeterminate value.\n\n" \
		"Options:\n" \
		"\t-a\t\tfirst function\n" \
		"\t-b\t\tsecond function\n" \
		...

If your program supports flags, the flags should be mentioned on the first
line (-[abcde]) and a detailed description of each flag should go in the
mu_full_usage section, one flag per line. (Numerous examples of this
currently exist in usage.h.)


Header Files
------------

Next, add an entry to include/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 CONFIG_MU
		APPLET("mu", mu_main, _BB_DIR_USR_BIN, mu_usage)
	#endif
	/* all programs below here are alphabetically "greater than" 'mu' */


Documentation
-------------

If you're feeling especially nice, you should also document your applet in the
docs directory (but nobody ever does that).

Adding some text to docs/Configure.help is a nice start.


The Grand Announcement
----------------------

Then create a diff -urN of the files you added and/or modified. Typically:
	<appletdir>/<applet>.c
	include/usage.c
	include/applets.h
	<appletdir>/Makefile.in
	<appletdir>/config.in
and send it to the mailing list:
	busybox@busybox.net
	http://busybox.net/mailman/listinfo/busybox

Sending patches as attachments is preferred, but not required.