How to Add a New Applet to BusyBox ================================== This document details the steps you must take to add a new applet to BusyBox. Credits: Matt Kraai - initial writeup Mark Whitley - the remix 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. For a new applet mu, here is the code that would go in mu.c: ----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 * */ #include "busybox.h" int mu_main(int argc, char **argv) { int fd; char mu; if ((fd = open("/dev/random", O_RDONLY)) < 0) perror_msg_and_die("/dev/random"); if ((n = safe_read(fd, &mu, 1)) < 1) perror_msg_and_die("/dev/random"); return mu; } ----end example code------ Coding Style ------------ Before you submit your applet for inclusion in BusyBox, (or better yet, before you _write_ your applet) please read through the style guide in the docs directory and make your program compliant. Some Words on libbb ------------------- 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. Usage String(s) --------------- Next, add usage information for you applet to usage.h. 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" \ 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.) 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: /* all programs above here are alphabetically "less than" 'mu' */ #ifdef BB_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 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 (.c, usage.c, applets.h, Config.h) and send it to the mailing list: busybox@oss.lineo.com. Sending patches as attachments is preferred, but not required.