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 9Thomas Lundquist - Trying to keep it updated. 10 11When doing this you should consider using the latest svn trunk. 12This is a good thing if you plan to getting it commited into mainline. 13 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. 22Make sure to #include "libbb.h" as the first include file in your applet so 23the bb_config.h and appropriate platform specific files are included properly. 24 25For a new applet mu, here is the code that would go in mu.c: 26 27(busybox.h already includes most usual header files. You do not need 28#include <stdio.h> etc...) 29 30 31----begin example code------ 32 33/* vi: set sw=4 ts=4: */ 34/* 35 * Mini mu implementation for busybox 36 * 37 * Copyright (C) [YEAR] by [YOUR NAME] <YOUR EMAIL> 38 * 39 * Licensed under GPLv2 or later, see file LICENSE in this tarball for details. 40 */ 41 42#include "libbb.h" 43#include "other.h" 44 45int mu_main(int argc, char **argv); 46int mu_main(int argc, char **argv) 47{ 48 int fd; 49 char mu; 50 51 fd = xopen("/dev/random", O_RDONLY); 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 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. 82 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 101in libbb/Kbuild. You should look at the conditional part of 102libbb/Kbuild aswell. 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 108You can look at libbb/Config.in and try to find out if the function is 109tuneable and add it there if it is. 110 111 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 120Add the applet to Kbuild in the chosen directory: 121 122lib-$(CONFIG_MU) += mu.o 123 124Add the applet to Config.in in the chosen directory: 125 126config CONFIG_MU 127 bool "MU" 128 default n 129 help 130 Returns an indeterminate value. 131 132 133Usage String(s) 134--------------- 135 136Next, add usage information for you applet to include/usage.h. 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 151currently exist in usage.h.) 152 153 154Header Files 155------------ 156 157Next, add an entry to include/applets.h. Be *sure* to keep the list 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 161Be sure to read the top of applets.h before adding your applet. 162 163 /* all programs above here are alphabetically "less than" 'mu' */ 164 USE_MU(APPLET(mu, _BB_DIR_USR_BIN, _BB_SUID_NEVER)) 165 /* all programs below here are alphabetically "greater than" 'mu' */ 166 167 168The Grand Announcement 169---------------------- 170 171Then create a diff by adding the new files with svn (remember your libbb files) 172 svn add <where you put it>/mu.c 173eventually also: 174 svn add libbb/function.c 175then 176 svn diff 177and send it to the mailing list: 178 busybox@busybox.net 179 http://busybox.net/mailman/listinfo/busybox 180 181Sending patches as attachments is preferred, but not required. 182