| 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 <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: |
| |
| ----begin example code------ |
| |
| /* vi: set sw=4 ts=4: */ |
| /* |
| * 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 |
| * |
| */ |
| |
| #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 utility.c |
| ----------------------- |
| |
| As you are writing your applet, please be aware of the body of pre-existing |
| useful functions in utility.c. Use these instead of reinventing the wheel. |
| |
| If you use functions from utility.c, you may need to add to the preprocessor |
| conditionals in that file, to make sure the routines you need are included. |
| So, since your mu implementation used safe_read(), append "|| defined BB_MU" to |
| the #if instruction that precedes the safe_read() function in utility.c . |
| |
| Additionally, if you have any useful, general-purpose functions in your |
| program that could be useful in another program, consider putting them in |
| utility.c. |
| |
| |
| Usage String(s) |
| --------------- |
| |
| Next, add usage information for you applet to usage.c. This should look like |
| the following: |
| |
| #if defined BB_MU |
| const char mu_usage[] = |
| "mu\n" |
| #ifndef BB_FEATURE_TRIVIAL_HELP |
| "\nReturns an indeterminate value.\n" |
| #endif |
| ; |
| |
| If your program supports flags, the flags should be mentioned on the first |
| line (mu -[bcRovma]) and a detailed description of each flag should go in the |
| BB_FEATURE_TRIVIAL_HELP section, one flag per line. (Numerous examples of this |
| currently exist in usage.c.) |
| |
| |
| 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 (<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. |
| |
| |