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 9 10 11Initial Write 12------------- 13 14First, write your applet. Be sure to include copyright information at the 15top, such as who you stole the code from and so forth. Also include the 16mini-GPL boilerplate. Be sure to name the main function <applet>_main instead 17of main. And be sure to put it in <applet>.c. For a new applet mu, here is 18the code that would go in mu.c: 19 20----begin example code------ 21 22/* vi: set sw=4 ts=4: */ 23/* 24 * Mini mu implementation for busybox 25 * 26 * 27 * Copyright (C) [YEAR] by [YOUR NAME] <YOUR EMAIL> 28 * 29 * This program is free software; you can redistribute it and/or modify 30 * it under the terms of the GNU General Public License as published by 31 * the Free Software Foundation; either version 2 of the License, or 32 * (at your option) any later version. 33 * 34 * This program is distributed in the hope that it will be useful, 35 * but WITHOUT ANY WARRANTY; without even the implied warranty of 36 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 37 * General Public License for more details. 38 * 39 * You should have received a copy of the GNU General Public License 40 * along with this program; if not, write to the Free Software 41 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 42 * 02111-1307 USA 43 * 44 */ 45 46#include "busybox.h" 47 48int mu_main(int argc, char **argv) 49{ 50 int fd; 51 char mu; 52 53 if ((fd = open("/dev/random", O_RDONLY)) < 0) 54 perror_msg_and_die("/dev/random"); 55 56 if ((n = safe_read(fd, &mu, 1)) < 1) 57 perror_msg_and_die("/dev/random"); 58 59 return mu; 60} 61 62----end example code------ 63 64 65Coding Style 66------------ 67 68Before you submit your applet for inclusion in BusyBox, (or better yet, before 69you _write_ your applet) please read through the style guide in the docs 70directory and make your program compliant. 71 72 73Some Words on libbb 74------------------- 75 76As you are writing your applet, please be aware of the body of pre-existing 77useful functions in libbb. Use these instead of reinventing the wheel. 78 79Additionally, if you have any useful, general-purpose functions in your 80program that could be useful in another program, consider putting them in 81libbb. 82 83 84Usage String(s) 85--------------- 86 87Next, add usage information for you applet to usage.h. This should look like 88the following: 89 90 #define mu_trivial_usage \ 91 "-[abcde] FILES" 92 #define mu_full_usage \ 93 "Returns an indeterminate value.\n\n" \ 94 "Options:\n" \ 95 "\t-a\t\tfirst function\n" \ 96 "\t-b\t\tsecond function\n" \ 97 98If your program supports flags, the flags should be mentioned on the first 99line (-[abcde]) and a detailed description of each flag should go in the 100mu_full_usage section, one flag per line. (Numerous examples of this 101currently exist in usage.h.) 102 103 104Header Files 105------------ 106 107Next, add an entry to applets.h. Be *sure* to keep the list in alphabetical 108order, or else it will break the binary-search lookup algorithm in busybox.c 109and the Gods of BusyBox smite you. Yea, verily: 110 111 /* all programs above here are alphabetically "less than" 'mu' */ 112 #ifdef BB_MU 113 APPLET("mu", mu_main, _BB_DIR_USR_BIN, mu_usage) 114 #endif 115 /* all programs below here are alphabetically "greater than" 'mu' */ 116 117 118Finally, add a define for your applet to Config.h: 119 120 #define BB_MU 121 122 123Documentation 124------------- 125 126If you're feeling especially nice, you should also document your applet in the 127docs directory (but nobody ever does that). 128 129 130The Grand Announcement 131---------------------- 132 133Then create a diff -urN of the files you added (<applet>.c, usage.c, 134applets.h, Config.h) and send it to the mailing list: 135busybox@opensource.lineo.com. Sending patches as attachments is preferred, but 136not required. 137 138 139