busybox/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 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
  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. Usage do not have to be taken care of by your applet.
  18
  19 For a new applet mu, here is the code that would go in mu.c:
  20
  21 ----begin example code------
  22
  23 /* vi: set sw=4 ts=4: */
  24 /*
  25  * Mini mu implementation for busybox
  26  *
  27  *
  28  * Copyright (C) [YEAR] by [YOUR NAME] <YOUR EMAIL>
  29  *
  30  * This program is free software; you can redistribute it and/or modify
  31  * it under the terms of the GNU General Public License as published by
  32  * the Free Software Foundation; either version 2 of the License, or
  33  * (at your option) any later version.
  34  *
  35  * This program is distributed in the hope that it will be useful,
  36  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  37  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  38  * General Public License for more details.
  39  *
  40  * You should have received a copy of the GNU General Public License
  41  * along with this program; if not, write to the Free Software
  42  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
  43  * 02111-1307 USA
  44  *
  45  */
  46
  47 #include "busybox.h"
  48
  49 int mu_main(int argc, char **argv)
  50 {
  51         int fd;
  52         char mu;
  53
  54         if ((fd = open("/dev/random", O_RDONLY)) < 0)
  55                 perror_msg_and_die("/dev/random");
  56
  57         if ((n = safe_read(fd, &mu, 1)) < 1)
  58                 perror_msg_and_die("/dev/random");
  59
  60         return mu;
  61 }
  62
  63 ----end example code------
  64
  65
  66 Coding Style
  67 ------------
  68
  69 Before you submit your applet for inclusion in BusyBox, (or better yet, before
  70 you _write_ your applet) please read through the style guide in the docs
  71 directory and make your program compliant.
  72
  73
  74 Some Words on libbb
  75 -------------------
  76
  77 As you are writing your applet, please be aware of the body of pre-existing
  78 useful functions in libbb. Use these instead of reinventing the wheel.
  79
  80 Additionally, if you have any useful, general-purpose functions in your
  81 program that could be useful in another program, consider putting them in
  82 libbb.
  83
  84
  85 Placement / Directory
  86 ---------------------
  87
  88 Find the appropriate directory for your new applet.
  89
  90 Make sure you find the appropriate places in the files, the applets are
  91 sorted alphabetically.
  92
  93 Add the applet to Makefile.in in the chosen applet directory:
  94
  95 obj-$(CONFIG_MU)               += mu.o
  96
  97 Add the applet to Config.in in the chosen applet directory:
  98
  99 config CONFIG_MU
 100         bool "MU"
 101         default n
 102         help
 103           Returns an indeterminate value.
 104
 105
 106 Usage String(s)
 107 ---------------
 108
 109 Next, add usage information for you applet to include/usage.h.
 110 This should look like the following:
 111
 112         #define mu_trivial_usage \
 113                 "-[abcde] FILES"
 114         #define mu_full_usage \
 115                 "Returns an indeterminate value.\n\n" \
 116                 "Options:\n" \
 117                 "\t-a\t\tfirst function\n" \
 118                 "\t-b\t\tsecond function\n" \
 119
 120 If your program supports flags, the flags should be mentioned on the first
 121 line (-[abcde]) and a detailed description of each flag should go in the
 122 mu_full_usage section, one flag per line. (Numerous examples of this
 123 currently exist in usage.h.)
 124
 125
 126 Header Files
 127 ------------
 128
 129 Next, add an entry to include/applets.h.  Be *sure* to keep the list
 130 in alphabetical order, or else it will break the binary-search lookup
 131 algorithm in busybox.c and the Gods of BusyBox smite you. Yea, verily:
 132
 133         /* all programs above here are alphabetically "less than" 'mu' */
 134         #ifdef CONFIG_MU
 135                 APPLET("mu", mu_main, _BB_DIR_USR_BIN, mu_usage)
 136         #endif
 137         /* all programs below here are alphabetically "greater than" 'mu' */
 138
 139
 140 Finally, add a define for your applet to include/config.h
 141
 142         #undef CONFIG_MU
 143
 144
 145 Documentation
 146 -------------
 147
 148 If you're feeling especially nice, you should also document your applet in the
 149 docs directory (but nobody ever does that).
 150
 151 Adding some text to docs/Configure.help is a nice start.
 152
 153
 154 The Grand Announcement
 155 ----------------------
 156
 157 Then create a diff -urN of the files you added (<appletdir/><applet>.c,
 158 include/usage.c, include/applets.h, include/config.h, <appletdir>/Makefile.in, <appletdir>/config.in)
 159 and send it to the mailing list:
 160 busybox@busybox.net.
 161
 162 Sending patches as attachments is preferred, but not required.
 163