source: branches/3.2/mindi-busybox/docs/new-applet-HOWTO.txt @ 3232

Last change on this file since 3232 was 3232, checked in by Bruno Cornec, 7 years ago
  • Update mindi-busybox to 1.21.1
File size: 4.7 KB
RevLine 
[821]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
[1765]9Thomas Lundquist - Trying to keep it updated.
[821]10
[2725]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.
[1765]13
[821]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. Be sure to name the main function <applet>_main instead of main.
20And be sure to put it in <applet>.c. Usage does not have to be taken care of by
21your applet.
[2725]22Make sure to #include "libbb.h" as the first include file in your applet.
[821]23
24For a new applet mu, here is the code that would go in mu.c:
25
[1765]26(busybox.h already includes most usual header files. You do not need
27#include <stdio.h> etc...)
28
29
[821]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 *
[2725]38 * Licensed under GPLv2, see file LICENSE in this source tree.
[821]39 */
40
[1765]41#include "libbb.h"
42#include "other.h"
[821]43
[2725]44int mu_main(int argc, char **argv) MAIN_EXTERNALLY_VISIBLE;
[821]45int mu_main(int argc, char **argv)
46{
47    int fd;
[2725]48    ssize_t n;
[821]49    char mu;
50
[1765]51    fd = xopen("/dev/random", O_RDONLY);
[821]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
62Coding Style
63------------
64
65Before you submit your applet for inclusion in BusyBox, (or better yet, before
66you _write_ your applet) please read through the style guide in the docs
67directory and make your program compliant.
68
69
70Some Words on libbb
71-------------------
72
73As you are writing your applet, please be aware of the body of pre-existing
74useful functions in libbb. Use these instead of reinventing the wheel.
75
76Additionally, if you have any useful, general-purpose functions in your
77applet that could be useful in other applets, consider putting them in libbb.
78
[1765]79And it may be possible that some of the other applets uses functions you
80could use. If so, you have to rip the function out of the applet and make
81a libbb function out of it.
[821]82
[1765]83Adding a libbb function:
84------------------------
85
86Make a new file named <function_name>.c
87
88----start example code------
89
90#include "libbb.h"
91#include "other.h"
92
93int function(char *a)
94{
95    return *a;
96}
97
98----end example code------
99
100Add <function_name>.o in the right alphabetically sorted place
[2725]101in libbb/Kbuild.src. You should look at the conditional part of
102libbb/Kbuild.src as well.
[1765]103
104You should also try to find a suitable place in include/libbb.h for
105the function declaration. If not, add it somewhere anyway, with or without
106ifdefs to include or not.
107
[2725]108You can look at libbb/Config.src and try to find out if the function is
109tunable and add it there if it is.
[1765]110
111
[821]112Placement / Directory
113---------------------
114
115Find the appropriate directory for your new applet.
116
117Make sure you find the appropriate places in the files, the applets are
118sorted alphabetically.
119
[2725]120Add the applet to Kbuild.src in the chosen directory:
[821]121
[1765]122lib-$(CONFIG_MU)               += mu.o
[821]123
[2725]124Add the applet to Config.src in the chosen directory:
[821]125
[2725]126config MU
[821]127    bool "MU"
128    default n
129    help
130      Returns an indeterminate value.
131
132
133Usage String(s)
134---------------
135
[2725]136Next, add usage information for you applet to include/usage.src.h.
[821]137This 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
148If your program supports flags, the flags should be mentioned on the first
149line (-[abcde]) and a detailed description of each flag should go in the
150mu_full_usage section, one flag per line. (Numerous examples of this
[2725]151currently exist in usage.src.h.)
[821]152
153
154Header Files
155------------
156
[2725]157Next, add an entry to include/applets.src.h.  Be *sure* to keep the list
[821]158in alphabetical order, or else it will break the binary-search lookup
159algorithm in busybox.c and the Gods of BusyBox smite you. Yea, verily:
160
[2725]161Be sure to read the top of applets.src.h before adding your applet.
[1765]162
[821]163    /* all programs above here are alphabetically "less than" 'mu' */
[3232]164    IF_MU(APPLET(mu, BB_DIR_USR_BIN, BB_SUID_DROP))
[821]165    /* all programs below here are alphabetically "greater than" 'mu' */
166
167
168The Grand Announcement
169----------------------
170
[2725]171Then create a diff by adding the new files to git (remember your libbb files)
172    git add <where you put it>/mu.c
[1765]173eventually also:
[2725]174    git add libbb/function.c
[1765]175then
[2725]176    git commit
177    git format-patch HEAD^
[821]178and send it to the mailing list:
179    busybox@busybox.net
180    http://busybox.net/mailman/listinfo/busybox
181
182Sending patches as attachments is preferred, but not required.
Note: See TracBrowser for help on using the repository browser.