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 - Trying to keep it updated.
  10
  11 When doing this you should consider using the latest git HEAD.
  12 This is a good thing if you plan to getting it committed into mainline.
  13
  14 Initial Write
  15 -------------
  16
  17 First, write your applet.  Be sure to include copyright information at the top,
  18 such as who you stole the code from and so forth. Also include the mini-GPL
  19 boilerplate. Be sure to name the main function <applet>_main instead of main.
  20 And be sure to put it in <applet>.c. Usage does not have to be taken care of by
  21 your applet.
  22 Make sure to #include "libbb.h" as the first include file in your applet.
  23
  24 For a new applet mu, here is the code that would go in mu.c:
  25
  26 (busybox.h already includes most usual header files. You do not need
  27 #include <stdio.h> etc...)
  28
  29
  30 ----begin example code------
  31
  32 /* vi: set sw=4 ts=4: */
  33 /*
  34  * Mini mu implementation for busybox
  35  *
  36  * Copyright (C) [YEAR] by [YOUR NAME] <YOUR EMAIL>
  37  *
  38  * Licensed under GPLv2, see file LICENSE in this source tree.
  39  */
  40
  41 #include "libbb.h"
  42 #include "other.h"
  43
  44 int mu_main(int argc, char **argv) MAIN_EXTERNALLY_VISIBLE;
  45 int mu_main(int argc, char **argv)
  46 {
  47         int fd;
  48         ssize_t n;
  49         char mu;
  50
  51         fd = xopen("/dev/random", O_RDONLY);
  52
  53         if ((n = safe_read(fd, &mu, 1)) < 1)
  54                 bb_perror_msg_and_die("/dev/random");
  55
  56         return mu;
  57 }
  58
  59 ----end example code------
  60
  61
  62 Coding Style
  63 ------------
  64
  65 Before you submit your applet for inclusion in BusyBox, (or better yet, before
  66 you _write_ your applet) please read through the style guide in the docs
  67 directory and make your program compliant.
  68
  69
  70 Some Words on libbb
  71 -------------------
  72
  73 As you are writing your applet, please be aware of the body of pre-existing
  74 useful functions in libbb. Use these instead of reinventing the wheel.
  75
  76 Additionally, if you have any useful, general-purpose functions in your
  77 applet that could be useful in other applets, consider putting them in libbb.
  78
  79 And it may be possible that some of the other applets uses functions you
  80 could use. If so, you have to rip the function out of the applet and make
  81 a libbb function out of it.
  82
  83 Adding a libbb function:
  84 ------------------------
  85
  86 Make a new file named <function_name>.c
  87
  88 ----start example code------
  89
  90 #include "libbb.h"
  91 #include "other.h"
  92
  93 int function(char *a)
  94 {
  95         return *a;
  96 }
  97
  98 ----end example code------
  99
 100 Add <function_name>.o in the right alphabetically sorted place
 101 in libbb/Kbuild.src. You should look at the conditional part of
 102 libbb/Kbuild.src as well.
 103
 104 You should also try to find a suitable place in include/libbb.h for
 105 the function declaration. If not, add it somewhere anyway, with or without
 106 ifdefs to include or not.
 107
 108 You can look at libbb/Config.src and try to find out if the function is
 109 tunable and add it there if it is.
 110
 111
 112 Placement / Directory
 113 ---------------------
 114
 115 Find the appropriate directory for your new applet.
 116
 117 Make sure you find the appropriate places in the files, the applets are
 118 sorted alphabetically.
 119
 120 Add the applet to Kbuild.src in the chosen directory:
 121
 122 lib-$(CONFIG_MU)               += mu.o
 123
 124 Add the applet to Config.src in the chosen directory:
 125
 126 config MU
 127         bool "MU"
 128         default n
 129         help
 130           Returns an indeterminate value.
 131
 132
 133 Usage String(s)
 134 ---------------
 135
 136 Next, add usage information for you applet to include/usage.src.h.
 137 This should look like the following:
 138
 139         #define mu_trivial_usage \
 140                 "-[abcde] FILES"
 141         #define mu_full_usage \
 142                 "Returns an indeterminate value.\n\n" \
 143                 "Options:\n" \
 144                 "\t-a\t\tfirst function\n" \
 145                 "\t-b\t\tsecond function\n" \
 146                 ...
 147
 148 If your program supports flags, the flags should be mentioned on the first
 149 line (-[abcde]) and a detailed description of each flag should go in the
 150 mu_full_usage section, one flag per line. (Numerous examples of this
 151 currently exist in usage.src.h.)
 152
 153
 154 Header Files
 155 ------------
 156
 157 Next, add an entry to include/applets.src.h.  Be *sure* to keep the list
 158 in alphabetical order, or else it will break the binary-search lookup
 159 algorithm in busybox.c and the Gods of BusyBox smite you. Yea, verily:
 160
 161 Be sure to read the top of applets.src.h before adding your applet.
 162
 163         /* all programs above here are alphabetically "less than" 'mu' */
 164         IF_MU(APPLET(mu, BB_DIR_USR_BIN, BB_SUID_DROP))
 165         /* all programs below here are alphabetically "greater than" 'mu' */
 166
 167
 168 The Grand Announcement
 169 ----------------------
 170
 171 Then create a diff by adding the new files to git (remember your libbb files)
 172         git add <where you put it>/mu.c
 173 eventually also:
 174         git add libbb/function.c
 175 then
 176         git commit
 177         git format-patch HEAD^
 178 and send it to the mailing list:
 179         busybox@busybox.net
 180         http://busybox.net/mailman/listinfo/busybox
 181
 182 Sending patches as attachments is preferred, but not required.