X-Git-Url: https://git.librecmc.org/?a=blobdiff_plain;f=docs%2Fnew-applet-HOWTO.txt;h=078e77bce2bcec0aa5ae1912241daf4c24d57e36;hb=e32b6503e75d5bcbf8ffff69cafb09523ff2b482;hp=2fc95d36df4834a360ee43f01f9b1d3b6ebd8b64;hpb=c7bda1ce659294d6e22c06e087f6f265983c7578;p=oweals%2Fbusybox.git diff --git a/docs/new-applet-HOWTO.txt b/docs/new-applet-HOWTO.txt index 2fc95d36d..078e77bce 100644 --- a/docs/new-applet-HOWTO.txt +++ b/docs/new-applet-HOWTO.txt @@ -6,56 +6,68 @@ 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 - Added stuff for the new directory layout. +Thomas Lundquist - trying to keep it updated + +When doing this you should consider using the latest git HEAD. +This is a good thing if you plan to getting it committed 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 _main instead -of main. And be sure to put it in .c. Usage do not have to be taken care of by your applet. +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 and Config.in/Kbuild/usage/applet.h snippets (more on that below +in this document). Be sure to name the main function _main instead +of main. And be sure to put it in .c. Make sure to #include "libbb.h" +as the first include file in your applet. For a new applet mu, here is the code that would go in mu.c: +(libbb.h already includes most usual header files. You do not need +#include etc...) + + ----begin example code------ /* vi: set sw=4 ts=4: */ /* * Mini mu implementation for busybox * - * * Copyright (C) [YEAR] by [YOUR NAME] * - * 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, see file LICENSE in this source tree. */ -#include "busybox.h" +#include "libbb.h" +#include "other.h" + +//config:config MU +//config: bool "MU" +//config: default y +//config: help +//config: Returns an indeterminate value. + +//kbuild:lib-$(CONFIG_MU) += mu.o +//applet:IF_MU(APPLET(mu, BB_DIR_USR_BIN, BB_SUID_DROP)) + +//usage:#define mu_trivial_usage +//usage: "[-abcde] FILE..." +//usage:#define mu_full_usage +//usage: "Returns an indeterminate value\n" +//usage: "\n -a First function" +//usage: "\n -b Second function" +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; } @@ -78,8 +90,56 @@ 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 .c + +----start example code------ + +#include "libbb.h" +#include "other.h" + +//kbuild:lib-y += function.o + +int function(char *a) +{ + return *a; +} + +----end example code------ + +Remember about the kbuild snippet. + +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.src and try to find out if the function is +tunable and add it there if it is. + + +Kbuild/Config.in/usage/applets.h snippets in .c files +----------------------------------------------------- + +The old way of adding new applets was to put all the information needed by the +configuration and build system into appropriate files (namely: Kbuild.src and +Config.src in new applet's directory) and to add the applet declaration and +usage info text to include/applets.src.h and include/usage.src.h respectively. + +Since the scripts/gen_build_files.sh script had been introduced, the preferred +way is to have all these declarations contained within the applet .c files. + +Every line intended to be processed by gen_build_files.sh should start as a +comment without any preceding whitespaces and be followed by an appropriate +keyword - kbuild, config, usage or applet - and a colon, just like shown in the +first example above. Placement / Directory @@ -87,77 +147,60 @@ 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 Makefile.in in the chosen applet directory: +Add the kbuild snippet to the .c file: -obj-$(CONFIG_MU) += mu.o +//kbuild:lib-$(CONFIG_MU) += mu.o -Add the applet to Config.in in the chosen applet directory: +Add the config snippet to the .c file: -config CONFIG_MU - bool "MU" - default n - help - Returns an indeterminate value. +//config:config MU +//config: bool "MU" +//config: default y +//config: help +//config: Returns an indeterminate value. Usage String(s) --------------- -Next, add usage information for you applet to include/usage.h. +Next, add usage information for your applet to the .c file. This should look like the following: - #define mu_trivial_usage \ - "-[abcde] FILES" - #define mu_full_usage \ - "Returns an indeterminate value.\n\n" \ - "Options:\n" \ - "\t-a\t\tfirst function\n" \ - "\t-b\t\tsecond function\n" \ +//usage:#define mu_trivial_usage +//usage: "[-abcde] FILE..." +//usage:#define mu_full_usage +//usage: "Returns an indeterminate value\n" +//usage: "\n -a First function" +//usage: "\n -b Second function" +//usage: ... 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 -mu_full_usage section, one flag per line. (Numerous examples of this -currently exist in usage.h.) +line ([-abcde]) and a detailed description of each flag should go in the +mu_full_usage section, one flag per line. Header Files ------------ -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: +Finally add the applet declaration snippet. Be sure to read the top of +applets.src.h before adding your applet - it contains important info +on applet macros and conventions. - /* all programs above here are alphabetically "less than" 'mu' */ - #ifdef CONFIG_MU - APPLET("mu", mu_main, _BB_DIR_USR_BIN, mu_usage) - #endif - /* all programs below here are alphabetically "greater than" 'mu' */ - - -Finally, add a define for your applet to include/config.h - - #undef CONFIG_MU - - -Documentation -------------- - -If you're feeling especially nice, you should also document your applet in the -docs directory (but nobody ever does that). - -Adding some text to docs/Configure.help is a nice start. +//applet:IF_MU(APPLET(mu, BB_DIR_USR_BIN, BB_SUID_DROP)) The Grand Announcement ---------------------- -Then create a diff -urN of the files you added (.c, -include/usage.c, include/applets.h, include/config.h, /Makefile.in, /config.in) +Then create a diff by adding the new files to git (remember your libbb files) + git add /mu.c +eventually also: + git add libbb/function.c +then + git commit + git format-patch HEAD^ and send it to the mailing list: -busybox@busybox.net. + busybox@busybox.net + http://busybox.net/mailman/listinfo/busybox Sending patches as attachments is preferred, but not required. -