| 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 |
| Thomas Lundquist - Added stuff for the new directory layout. |
| |
| 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. Usage does not have to be taken care of by |
| your applet. |
| Make sure to #include "busybox.h" as the first include file in your applet so |
| the bb_config.h and appropriate platform specific files are included properly. |
| |
| 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> |
| * |
| * Licensed under GPLv2 or later, see file LICENSE in this tarball for details. |
| */ |
| |
| #include "busybox.h" |
| #include <other.h> |
| |
| int mu_main(int argc, char **argv) |
| { |
| int fd; |
| char mu; |
| |
| fd = bb_xopen("/dev/random", O_RDONLY); |
| |
| if ((n = safe_read(fd, &mu, 1)) < 1) |
| bb_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 |
| applet that could be useful in other applets, consider putting them in libbb. |
| |
| |
| Placement / Directory |
| --------------------- |
| |
| Find the appropriate directory for your new applet. |
| |
| Make sure you find the appropriate places in the files, the applets are |
| sorted alphabetically. |
| |
| Add the applet to Makefile.in in the chosen directory: |
| |
| obj-$(CONFIG_MU) += mu.o |
| |
| Add the applet to Config.in in the chosen directory: |
| |
| config CONFIG_MU |
| bool "MU" |
| default n |
| help |
| Returns an indeterminate value. |
| |
| |
| Usage String(s) |
| --------------- |
| |
| Next, add usage information for you applet to include/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 include/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 CONFIG_MU |
| APPLET("mu", mu_main, _BB_DIR_USR_BIN, mu_usage) |
| #endif |
| /* all programs below here are alphabetically "greater than" 'mu' */ |
| |
| |
| Documentation |
| ------------- |
| |
| If you're feeling especially nice, you should also document your applet in the |
| docs directory (but nobody ever does that). |
| |
| Adding some text to docs/Configure.help is a nice start. |
| |
| |
| The Grand Announcement |
| ---------------------- |
| |
| Then create a diff -urN of the files you added and/or modified. Typically: |
| <appletdir>/<applet>.c |
| include/usage.c |
| include/applets.h |
| <appletdir>/Makefile.in |
| <appletdir>/config.in |
| and send it to the mailing list: |
| busybox@busybox.net |
| http://busybox.net/mailman/listinfo/busybox |
| |
| Sending patches as attachments is preferred, but not required. |