diff options
Diffstat (limited to 'release/src/router/busybox/docs/new-applet-HOWTO.txt')
| -rw-r--r-- | release/src/router/busybox/docs/new-applet-HOWTO.txt | 150 |
1 files changed, 97 insertions, 53 deletions
diff --git a/release/src/router/busybox/docs/new-applet-HOWTO.txt b/release/src/router/busybox/docs/new-applet-HOWTO.txt index 1f5c3ebd..6f89cbe1 100644 --- a/release/src/router/busybox/docs/new-applet-HOWTO.txt +++ b/release/src/router/busybox/docs/new-applet-HOWTO.txt @@ -6,16 +6,27 @@ This document details the steps you must take to add a new applet to BusyBox. Credits: Matt Kraai - initial writeup Mark Whitley - the remix +Thomas Lundquist - Trying to keep it updated. +When doing this you should consider using the latest svn trunk. +This is a good thing if you plan to getting it commited into mainline. Initial Write ------------- -First, write your applet. Be sure to include copyright information at the -top, such as who you stole the code from and so forth. Also include the -mini-GPL boilerplate. Be sure to name the main function <applet>_main instead -of main. And be sure to put it in <applet>.c. For a new applet mu, here is -the code that would go in mu.c: +First, write your applet. Be sure to include copyright information at the top, +such as who you stole the code from and so forth. Also include the mini-GPL +boilerplate. Be sure to name the main function <applet>_main instead of main. +And be sure to put it in <applet>.c. Usage does not have to be taken care of by +your applet. +Make sure to #include "libbb.h" as the first include file in your applet so +the bb_config.h and appropriate platform specific files are included properly. + +For a new applet mu, here is the code that would go in mu.c: + +(busybox.h already includes most usual header files. You do not need +#include <stdio.h> etc...) + ----begin example code------ @@ -23,38 +34,25 @@ the code that would go in mu.c: /* * Mini mu implementation for busybox * - * * Copyright (C) [YEAR] by [YOUR NAME] <YOUR EMAIL> * - * This program is free software; you can redistribute it and/or modify - * it under the terms of the GNU General Public License as published by - * the Free Software Foundation; either version 2 of the License, or - * (at your option) any later version. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - * General Public License for more details. - * - * You should have received a copy of the GNU General Public License - * along with this program; if not, write to the Free Software - * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA - * 02111-1307 USA - * + * Licensed under GPLv2 or later, see file LICENSE in this tarball for details. */ -#include "busybox.h" +#include "libbb.h" +#include "other.h" +int mu_main(int argc, char **argv) MAIN_EXTERNALLY_VISIBLE; int mu_main(int argc, char **argv) { int fd; + ssize_t n; char mu; - if ((fd = open("/dev/random", O_RDONLY)) < 0) - perror_msg_and_die("/dev/random"); + fd = xopen("/dev/random", O_RDONLY); if ((n = safe_read(fd, &mu, 1)) < 1) - perror_msg_and_die("/dev/random"); + bb_perror_msg_and_die("/dev/random"); return mu; } @@ -77,15 +75,67 @@ As you are writing your applet, please be aware of the body of pre-existing useful functions in libbb. Use these instead of reinventing the wheel. Additionally, if you have any useful, general-purpose functions in your -program that could be useful in another program, consider putting them in -libbb. +applet that could be useful in other applets, consider putting them in libbb. + +And it may be possible that some of the other applets uses functions you +could use. If so, you have to rip the function out of the applet and make +a libbb function out of it. + +Adding a libbb function: +------------------------ + +Make a new file named <function_name>.c + +----start example code------ + +#include "libbb.h" +#include "other.h" + +int function(char *a) +{ + return *a; +} + +----end example code------ + +Add <function_name>.o in the right alphabetically sorted place +in libbb/Kbuild. You should look at the conditional part of +libbb/Kbuild aswell. + +You should also try to find a suitable place in include/libbb.h for +the function declaration. If not, add it somewhere anyway, with or without +ifdefs to include or not. + +You can look at libbb/Config.in and try to find out if the function is +tuneable and add it there if it is. + + +Placement / Directory +--------------------- + +Find the appropriate directory for your new applet. + +Make sure you find the appropriate places in the files, the applets are +sorted alphabetically. + +Add the applet to Kbuild in the chosen directory: + +lib-$(CONFIG_MU) += mu.o + +Add the applet to Config.in in the chosen directory: + +config MU + bool "MU" + default n + help + Returns an indeterminate value. Usage String(s) --------------- -Next, add usage information for you applet to usage.h. This should look like -the following: +Next, add usage information for you applet to include/usage.h. +This should look like the following: #define mu_trivial_usage \ "-[abcde] FILES" @@ -94,6 +144,7 @@ the following: "Options:\n" \ "\t-a\t\tfirst function\n" \ "\t-b\t\tsecond function\n" \ + ... If your program supports flags, the flags should be mentioned on the first line (-[abcde]) and a detailed description of each flag should go in the @@ -104,35 +155,28 @@ currently exist in usage.h.) Header Files ------------ -Next, add an entry to applets.h. Be *sure* to keep the list in alphabetical -order, or else it will break the binary-search lookup algorithm in busybox.c -and the Gods of BusyBox smite you. Yea, verily: +Next, add an entry to include/applets.h. Be *sure* to keep the list +in alphabetical order, or else it will break the binary-search lookup +algorithm in busybox.c and the Gods of BusyBox smite you. Yea, verily: + +Be sure to read the top of applets.h before adding your applet. /* all programs above here are alphabetically "less than" 'mu' */ - #ifdef BB_MU - APPLET("mu", mu_main, _BB_DIR_USR_BIN, mu_usage) - #endif + USE_MU(APPLET(mu, _BB_DIR_USR_BIN, _BB_SUID_NEVER)) /* all programs below here are alphabetically "greater than" 'mu' */ -Finally, add a define for your applet to Config.h: - - #define BB_MU - - -Documentation -------------- - -If you're feeling especially nice, you should also document your applet in the -docs directory (but nobody ever does that). - - The Grand Announcement ---------------------- -Then create a diff -urN of the files you added (<applet>.c, usage.c, -applets.h, Config.h) and send it to the mailing list: -busybox@opensource.lineo.com. Sending patches as attachments is preferred, but -not required. - - +Then create a diff by adding the new files with svn (remember your libbb files) + svn add <where you put it>/mu.c +eventually also: + svn add libbb/function.c +then + svn diff +and send it to the mailing list: + busybox@busybox.net + http://busybox.net/mailman/listinfo/busybox + +Sending patches as attachments is preferred, but not required. |