busybox/docs/new-applet-HOWTO.txt
<<
>>
Prefs
   1How to Add a New Applet to BusyBox
   2==================================
   3
   4This document details the steps you must take to add a new applet to BusyBox.
   5
   6Credits:
   7Matt Kraai - initial writeup
   8Mark Whitley - the remix
   9Thomas Lundquist - trying to keep it updated
  10
  11When doing this you should consider using the latest git HEAD.
  12This is a good thing if you plan to getting it committed into mainline.
  13
  14Initial Write
  15-------------
  16
  17First, write your applet.  Be sure to include copyright information at the top,
  18such as who you stole the code from and so forth. Also include the mini-GPL
  19boilerplate and Config.in/Kbuild/usage/applet.h snippets (more on that below
  20in this document). Be sure to name the main function <applet>_main instead
  21of main. And be sure to put it in <applet>.c. Make sure to #include "libbb.h"
  22as the first include file in your applet.
  23
  24For a new applet mu, here is the code that would go in mu.c:
  25
  26(libbb.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//config:config MU
  45//config:       bool "MU"
  46//config:       default y
  47//config:       help
  48//config:         Returns an indeterminate value.
  49
  50//kbuild:lib-$(CONFIG_MU) += mu.o
  51//applet:IF_MU(APPLET(mu, BB_DIR_USR_BIN, BB_SUID_DROP))
  52
  53//usage:#define mu_trivial_usage
  54//usage:        "[-abcde] FILE..."
  55//usage:#define mu_full_usage
  56//usage:        "Returns an indeterminate value\n"
  57//usage:     "\n        -a      First function"
  58//usage:     "\n        -b      Second function"
  59
  60int mu_main(int argc, char **argv) MAIN_EXTERNALLY_VISIBLE;
  61int mu_main(int argc, char **argv)
  62{
  63        int fd;
  64        ssize_t n;
  65        char mu;
  66
  67        fd = xopen("/dev/random", O_RDONLY);
  68
  69        if ((n = safe_read(fd, &mu, 1)) < 1)
  70                bb_perror_msg_and_die("/dev/random");
  71
  72        return mu;
  73}
  74
  75----end example code------
  76
  77
  78Coding Style
  79------------
  80
  81Before you submit your applet for inclusion in BusyBox, (or better yet, before
  82you _write_ your applet) please read through the style guide in the docs
  83directory and make your program compliant.
  84
  85
  86Some Words on libbb
  87-------------------
  88
  89As you are writing your applet, please be aware of the body of pre-existing
  90useful functions in libbb. Use these instead of reinventing the wheel.
  91
  92Additionally, if you have any useful, general-purpose functions in your
  93applet that could be useful in other applets, consider putting them in libbb.
  94
  95And it may be possible that some of the other applets uses functions you
  96could use. If so, you have to rip the function out of the applet and make
  97a libbb function out of it.
  98
  99Adding a libbb function:
 100------------------------
 101
 102Make a new file named <function_name>.c
 103
 104----start example code------
 105
 106#include "libbb.h"
 107#include "other.h"
 108
 109//kbuild:lib-y += function.o
 110
 111int function(char *a)
 112{
 113        return *a;
 114}
 115
 116----end example code------
 117
 118Remember about the kbuild snippet.
 119
 120You should also try to find a suitable place in include/libbb.h for
 121the function declaration. If not, add it somewhere anyway, with or without
 122ifdefs to include or not.
 123
 124You can look at libbb/Config.src and try to find out if the function is
 125tunable and add it there if it is.
 126
 127
 128Kbuild/Config.in/usage/applets.h snippets in .c files
 129-----------------------------------------------------
 130
 131The old way of adding new applets was to put all the information needed by the
 132configuration and build system into appropriate files (namely: Kbuild.src and
 133Config.src in new applet's directory) and to add the applet declaration and
 134usage info text to include/applets.src.h and include/usage.src.h respectively.
 135
 136Since the scripts/gen_build_files.sh script had been introduced, the preferred
 137way is to have all these declarations contained within the applet .c files.
 138
 139Every line intended to be processed by gen_build_files.sh should start as a
 140comment without any preceding whitespaces and be followed by an appropriate
 141keyword - kbuild, config, usage or applet - and a colon, just like shown in the
 142first example above.
 143
 144
 145Placement / Directory
 146---------------------
 147
 148Find the appropriate directory for your new applet.
 149
 150Add the config snippet to the .c file:
 151
 152//config:config MU
 153//config:       bool "MU"
 154//config:       default y
 155//config:       help
 156//config:       Returns an indeterminate value.
 157
 158Add the kbuild snippet to the .c file:
 159
 160//kbuild:lib-$(CONFIG_MU) += mu.o
 161
 162
 163Usage String(s)
 164---------------
 165
 166Next, add usage information for your applet to the .c file.
 167This should look like the following:
 168
 169//usage:#define mu_trivial_usage
 170//usage:        "[-abcde] FILE..."
 171//usage:#define mu_full_usage "\n\n"
 172//usage:        "Returns an indeterminate value"
 173//usage:     "\n"
 174//usage:     "\n        -a      First function"
 175//usage:     "\n        -b      Second function"
 176//usage:        ...
 177
 178If your program supports flags, the flags should be mentioned on the first
 179line ([-abcde]) and a detailed description of each flag should go in the
 180mu_full_usage section, one flag per line.
 181
 182
 183Header Files
 184------------
 185
 186Finally add the applet declaration snippet. Be sure to read the top of
 187applets.src.h before adding your applet - it contains important info
 188on applet macros and conventions.
 189
 190//applet:IF_MU(APPLET(mu, BB_DIR_USR_BIN, BB_SUID_DROP))
 191
 192
 193The Grand Announcement
 194----------------------
 195
 196Then create a diff by adding the new files to git (remember your libbb files)
 197        git add <where you put it>/mu.c
 198eventually also:
 199        git add libbb/function.c
 200then
 201        git commit
 202        git format-patch HEAD^
 203and send it to the mailing list:
 204        busybox@busybox.net
 205        http://busybox.net/mailman/listinfo/busybox
 206
 207Sending patches as attachments is preferred, but not required.
 208