Mark Whitley | eac2636 | 2000-12-19 17:35:24 +0000 | [diff] [blame] | 1 | How to Add a New Applet to BusyBox |
| 2 | ================================== |
| 3 | |
| 4 | This document details the steps you must take to add a new applet to BusyBox. |
| 5 | |
| 6 | Credits: |
| 7 | Matt Kraai - initial writeup |
| 8 | Mark Whitley - the remix |
| 9 | |
| 10 | |
| 11 | Initial Write |
| 12 | ------------- |
| 13 | |
| 14 | First, write your applet. Be sure to include copyright information at the |
| 15 | top, such as who you stole the code from and so forth. Also include the |
| 16 | mini-GPL boilerplate. Be sure to name the main function <applet>_main instead |
| 17 | of main. And be sure to put it in <applet>.c. For a new applet mu, here is |
| 18 | the 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 | |
| 48 | int 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 | |
Mark Whitley | 8a6b619 | 2000-12-19 17:54:38 +0000 | [diff] [blame] | 64 | |
| 65 | Coding Style |
| 66 | ------------ |
| 67 | |
| 68 | Before you submit your applet for inclusion in BusyBox, (or better yet, before |
| 69 | you _write_ your applet) please read through the style guide in the docs |
| 70 | directory and make your program compliant. |
| 71 | |
| 72 | |
Glenn L McGrath | 2e6d3cf | 2001-06-24 12:36:54 +0000 | [diff] [blame] | 73 | Some Words on libbb |
| 74 | ------------------- |
Mark Whitley | 8a6b619 | 2000-12-19 17:54:38 +0000 | [diff] [blame] | 75 | |
Mark Whitley | eac2636 | 2000-12-19 17:35:24 +0000 | [diff] [blame] | 76 | As you are writing your applet, please be aware of the body of pre-existing |
Glenn L McGrath | 2e6d3cf | 2001-06-24 12:36:54 +0000 | [diff] [blame] | 77 | useful functions in libbb. Use these instead of reinventing the wheel. |
Mark Whitley | 8a6b619 | 2000-12-19 17:54:38 +0000 | [diff] [blame] | 78 | |
Mark Whitley | eac2636 | 2000-12-19 17:35:24 +0000 | [diff] [blame] | 79 | Additionally, if you have any useful, general-purpose functions in your |
| 80 | program that could be useful in another program, consider putting them in |
Glenn L McGrath | 2e6d3cf | 2001-06-24 12:36:54 +0000 | [diff] [blame] | 81 | libbb. |
Mark Whitley | eac2636 | 2000-12-19 17:35:24 +0000 | [diff] [blame] | 82 | |
Mark Whitley | eac2636 | 2000-12-19 17:35:24 +0000 | [diff] [blame] | 83 | |
| 84 | Usage String(s) |
| 85 | --------------- |
| 86 | |
Glenn L McGrath | 2e6d3cf | 2001-06-24 12:36:54 +0000 | [diff] [blame] | 87 | Next, add usage information for you applet to usage.h. This should look like |
Mark Whitley | eac2636 | 2000-12-19 17:35:24 +0000 | [diff] [blame] | 88 | the following: |
| 89 | |
Glenn L McGrath | 2e6d3cf | 2001-06-24 12:36:54 +0000 | [diff] [blame] | 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" \ |
Mark Whitley | eac2636 | 2000-12-19 17:35:24 +0000 | [diff] [blame] | 97 | |
| 98 | If your program supports flags, the flags should be mentioned on the first |
Glenn L McGrath | 2e6d3cf | 2001-06-24 12:36:54 +0000 | [diff] [blame] | 99 | line (-[abcde]) and a detailed description of each flag should go in the |
| 100 | mu_full_usage section, one flag per line. (Numerous examples of this |
| 101 | currently exist in usage.h.) |
Mark Whitley | eac2636 | 2000-12-19 17:35:24 +0000 | [diff] [blame] | 102 | |
| 103 | |
| 104 | Header Files |
| 105 | ------------ |
| 106 | |
| 107 | Next, add an entry to applets.h. Be *sure* to keep the list in alphabetical |
| 108 | order, or else it will break the binary-search lookup algorithm in busybox.c |
| 109 | and the Gods of BusyBox smite you. Yea, verily: |
| 110 | |
| 111 | /* all programs above here are alphabetically "less than" 'mu' */ |
Eric Andersen | bdfd0d7 | 2001-10-24 05:00:29 +0000 | [diff] [blame] | 112 | #ifdef CONFIG_MU |
Mark Whitley | eac2636 | 2000-12-19 17:35:24 +0000 | [diff] [blame] | 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 | |
| 118 | Finally, add a define for your applet to Config.h: |
| 119 | |
Eric Andersen | bdfd0d7 | 2001-10-24 05:00:29 +0000 | [diff] [blame] | 120 | #define CONFIG_MU |
Mark Whitley | eac2636 | 2000-12-19 17:35:24 +0000 | [diff] [blame] | 121 | |
| 122 | |
| 123 | Documentation |
| 124 | ------------- |
| 125 | |
| 126 | If you're feeling especially nice, you should also document your applet in the |
| 127 | docs directory (but nobody ever does that). |
| 128 | |
| 129 | |
| 130 | The Grand Announcement |
| 131 | ---------------------- |
| 132 | |
| 133 | Then create a diff -urN of the files you added (<applet>.c, usage.c, |
| 134 | applets.h, Config.h) and send it to the mailing list: |
Eric Andersen | 2423b12 | 2001-12-08 01:56:15 +0000 | [diff] [blame^] | 135 | busybox@busybox.net. Sending patches as attachments is preferred, but |
Mark Whitley | eac2636 | 2000-12-19 17:35:24 +0000 | [diff] [blame] | 136 | not required. |
| 137 | |
| 138 | |