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 top,
  15 such as who you stole the code from and so forth. Also include the mini-GPL
  16 boilerplate. Be sure to name the main function <applet>_main instead of main.
  17 And be sure to put it in <applet>.c. Usage does not have to be taken care of by
  18 your applet.
  19
  20 For a new applet mu, here is the code that would go in mu.c:
  21
  22 ----begin example code------
  23
  24 /* vi: set sw=4 ts=4: */
  25 /*
  26  * Mini mu implementation for busybox
  27  *
  28  *
  29  * Copyright (C) [YEAR] by [YOUR NAME] <YOUR EMAIL>
  30  *
  31  * Licensed under GPLv2 or later, see file LICENSE in this tarball for details.
  32  */
  33
  34 #include "busybox.h"
  35
  36 int mu_main(int argc, char **argv)
  37 {
  38         int fd;
  39         char mu;
  40
  41         fd = bb_xopen("/dev/random", O_RDONLY);
  42
  43         if ((n = safe_read(fd, &mu, 1)) < 1)
  44                 bb_perror_msg_and_die("/dev/random");
  45
  46         return mu;
  47 }
  48
  49 ----end example code------
  50
  51
  52 Coding Style
  53 ------------
  54
  55 Before you submit your applet for inclusion in BusyBox, (or better yet, before
  56 you _write_ your applet) please read through the style guide in the docs
  57 directory and make your program compliant.
  58
  59
  60 Some Words on libbb
  61 -------------------
  62
  63 As you are writing your applet, please be aware of the body of pre-existing
  64 useful functions in libbb. Use these instead of reinventing the wheel.
  65
  66 Additionally, if you have any useful, general-purpose functions in your
  67 applet that could be useful in other applets, consider putting them in libbb.
  68
  69
  70 Placement / Directory
  71 ---------------------
  72
  73 Find the appropriate directory for your new applet.
  74
  75 Make sure you find the appropriate places in the files, the applets are
  76 sorted alphabetically.
  77
  78 Add the applet to Makefile.in in the chosen directory:
  79
  80 obj-$(CONFIG_MU)               += mu.o
  81
  82 Add the applet to Config.in in the chosen directory:
  83
  84 config CONFIG_MU
  85         bool "MU"
  86         default n
  87         help
  88           Returns an indeterminate value.
  89
  90
  91 Usage String(s)
  92 ---------------
  93
  94 Next, add usage information for you applet to include/usage.h.
  95 This should look like the following:
  96
  97         #define mu_trivial_usage \
  98                 "-[abcde] FILES"
  99         #define mu_full_usage \
 100                 "Returns an indeterminate value.\n\n" \
 101                 "Options:\n" \
 102                 "\t-a\t\tfirst function\n" \
 103                 "\t-b\t\tsecond function\n" \
 104                 ...
 105
 106 If your program supports flags, the flags should be mentioned on the first
 107 line (-[abcde]) and a detailed description of each flag should go in the
 108 mu_full_usage section, one flag per line. (Numerous examples of this
 109 currently exist in usage.h.)
 110
 111
 112 Header Files
 113 ------------
 114
 115 Next, add an entry to include/applets.h.  Be *sure* to keep the list
 116 in alphabetical order, or else it will break the binary-search lookup
 117 algorithm in busybox.c and the Gods of BusyBox smite you. Yea, verily:
 118
 119         /* all programs above here are alphabetically "less than" 'mu' */
 120         #ifdef CONFIG_MU
 121                 APPLET("mu", mu_main, _BB_DIR_USR_BIN, mu_usage)
 122         #endif
 123         /* all programs below here are alphabetically "greater than" 'mu' */
 124
 125
 126 Documentation
 127 -------------
 128
 129 If you're feeling especially nice, you should also document your applet in the
 130 docs directory (but nobody ever does that).
 131
 132 Adding some text to docs/Configure.help is a nice start.
 133
 134
 135 The Grand Announcement
 136 ----------------------
 137
 138 Then create a diff -urN of the files you added and/or modified. Typically:
 139         <appletdir>/<applet>.c
 140         include/usage.c
 141         include/applets.h
 142         <appletdir>/Makefile.in
 143         <appletdir>/config.in
 144 and send it to the mailing list:
 145         busybox@busybox.net
 146         http://busybox.net/mailman/listinfo/busybox
 147
 148 Sending patches as attachments is preferred, but not required.