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

git-svn-id: svn://busybox.net/trunk/busybox@1471 69ca8d6d-28ef-0310-b511-8ec308f3f277

1 files changed, 128 insertions, 0 deletions

diff --git a/docs/new-applet-HOWTO.txt b/docs/new-applet-HOWTO.txt
new file mode 100644
index 000000000..c27aef828
--- /dev/null
+++ b/docs/new-applet-HOWTO.txt
@@ -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.
+
+