docs/new-applet-HOWTO.txt

   1 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
  10
  11 Initial Write
  12 -------------
  13
  14 First, write your applet.  Be sure to include copyright information at the
  15 top, such as who you stole the code from and so forth. Also include the
  16 mini-GPL boilerplate. Be sure to name the main function <applet>_main instead
  17 of main.  And be sure to put it in <applet>.c.  For a new applet mu, here is
  18 the code that would go in mu.c:
  19
  20 ----begin example code------
  21
  22 /* vi: set sw=4 ts=4: */
  23 /*
  24  * Mini mu implementation for busybox
  25  *
  26  *
  27  * Copyright (C) [YEAR] by [YOUR NAME] <YOUR EMAIL>
  28  *
  29  * This program is free software; you can redistribute it and/or modify
  30  * it under the terms of the GNU General Public License as published by
  31  * the Free Software Foundation; either version 2 of the License, or
  32  * (at your option) any later version.
  33  *
  34  * This program is distributed in the hope that it will be useful,
  35  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  36  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  37  * General Public License for more details.
  38  *
  39  * You should have received a copy of the GNU General Public License
  40  * along with this program; if not, write to the Free Software
  41  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
  42  * 02111-1307 USA
  43  *
  44  */
  45
  46 #include "busybox.h"
  47
  48 int mu_main(int argc, char **argv)
  49 {
  50         int fd;
  51         char mu;
  52
  53         if ((fd = open("/dev/random", O_RDONLY)) < 0)
  54                 perror_msg_and_die("/dev/random");
  55
  56         if ((n = safe_read(fd, &mu, 1)) < 1)
  57                 perror_msg_and_die("/dev/random");
  58
  59         return mu;
  60 }
  61
  62 ----end example code------
  63
  64
  65 Coding Style
  66 ------------
  67
  68 Before you submit your applet for inclusion in BusyBox, (or better yet, before
  69 you _write_ your applet) please read through the style guide in the docs
  70 directory and make your program compliant.
  71
  72
  73 Some Words on utility.c
  74 -----------------------
  75
  76 As you are writing your applet, please be aware of the body of pre-existing
  77 useful functions in utility.c. Use these instead of reinventing the wheel.
  78
  79 If you use functions from utility.c, you may need to add to the preprocessor
  80 conditionals in that file, to make sure the routines you need are included.
  81 So, since your mu implementation used safe_read(), append "|| defined BB_MU" to
  82 the #if instruction that precedes the safe_read() function in utility.c .
  83
  84 Additionally, if you have any useful, general-purpose functions in your
  85 program that could be useful in another program, consider putting them in
  86 utility.c.
  87
  88
  89 Usage String(s)
  90 ---------------
  91
  92 Next, add usage information for you applet to usage.c. This should look like
  93 the following:
  94
  95         #if defined BB_MU
  96         const char mu_usage[] =
  97                 "mu\n"
  98         #ifndef BB_FEATURE_TRIVIAL_HELP
  99                 "\nReturns an indeterminate value.\n"
 100         #endif
 101                 ;
 102
 103 If your program supports flags, the flags should be mentioned on the first
 104 line (mu -[bcRovma]) and a detailed description of each flag should go in the
 105 BB_FEATURE_TRIVIAL_HELP section, one flag per line. (Numerous examples of this
 106 currently exist in usage.c.)
 107
 108
 109 Header Files
 110 ------------
 111
 112 Next, add an entry to applets.h.  Be *sure* to keep the list in alphabetical
 113 order, or else it will break the binary-search lookup algorithm in busybox.c
 114 and the Gods of BusyBox smite you. Yea, verily:
 115
 116         /* all programs above here are alphabetically "less than" 'mu' */
 117         #ifdef BB_MU
 118                 APPLET("mu", mu_main, _BB_DIR_USR_BIN, mu_usage)
 119         #endif
 120         /* all programs below here are alphabetically "greater than" 'mu' */
 121
 122
 123 Finally, add a define for your applet to Config.h:
 124
 125         #define BB_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
 135 The Grand Announcement
 136 ----------------------
 137
 138 Then create a diff -urN of the files you added (<applet>.c, usage.c,
 139 applets.h, Config.h) and send it to the mailing list:
 140 busybox@opensource.lineo.com. Sending patches as attachments is preferred, but
 141 not required.
 142
 143