summaryrefslogtreecommitdiff
path: root/docs/new-applet-HOWTO.txt
diff options
context:
space:
mode:
authorBartosz Golaszewski2014-03-12 22:43:50 +0100
committerDenys Vlasenko2014-03-16 18:47:44 +0100
commit9dbe4d054703ac96355c90bd7794d14d206e10c5 (patch)
tree4cf5830acd7a6fe4fd9dff6dac127a624e29250d /docs/new-applet-HOWTO.txt
parent109ee5d33694a03cda3424b4846584250832ba8e (diff)
downloadbusybox-9dbe4d054703ac96355c90bd7794d14d206e10c5.zip
busybox-9dbe4d054703ac96355c90bd7794d14d206e10c5.tar.gz
docs: update new-applet-HOWTO.txt
This patch adds some information about the gen_build_files.sh script and how it allows to keep the Kbuild, Config.in etc. declarations in .c files. Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com> Signed-off-by: Denys Vlasenko <vda.linux@googlemail.com>
Diffstat (limited to 'docs/new-applet-HOWTO.txt')
-rw-r--r--docs/new-applet-HOWTO.txt97
1 files changed, 62 insertions, 35 deletions
diff --git a/docs/new-applet-HOWTO.txt b/docs/new-applet-HOWTO.txt
index 6a8054d..28970a5 100644
--- a/docs/new-applet-HOWTO.txt
+++ b/docs/new-applet-HOWTO.txt
@@ -16,10 +16,10 @@ 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 "libbb.h" as the first include file in your applet.
+boilerplate and Config.in/Kbuild/usage/applet.h snippets (more on that below
+in this document). Be sure to name the main function <applet>_main instead
+of main. And be sure to put it in <applet>.c. Make sure to #include "libbb.h"
+as the first include file in your applet.
For a new applet mu, here is the code that would go in mu.c:
@@ -41,6 +41,23 @@ For a new applet mu, here is the code that would go in mu.c:
#include "libbb.h"
#include "other.h"
+//config:config MU
+//config: bool "MU"
+//config: default n
+//config: help
+//config: Returns an indeterminate value.
+
+//kbuild:lib-$(CONFIG_MU) += mu.o
+//applet:IF_MU(APPLET(mu, BB_DIR_USR_BIN, BB_SUID_DROP))
+
+//usage:#define mu_trivial_usage
+//usage: "-[abcde] FILES"
+//usage:#define mu_full_usage
+//usage: "Returns an indeterminate value.\n\n"
+//usage: "Options:\n"
+//usage: "\t-a\t\tfirst function\n"
+//usage: "\t-b\t\tsecond function\n"
+
int mu_main(int argc, char **argv) MAIN_EXTERNALLY_VISIBLE;
int mu_main(int argc, char **argv)
{
@@ -90,6 +107,8 @@ Make a new file named <function_name>.c
#include "libbb.h"
#include "other.h"
+//kbuild:lib-y += function.o
+
int function(char *a)
{
return *a;
@@ -97,9 +116,7 @@ int function(char *a)
----end example code------
-Add <function_name>.o in the right alphabetically sorted place
-in libbb/Kbuild.src. You should look at the conditional part of
-libbb/Kbuild.src as well.
+Remember about the kbuild snippet.
You should also try to find a suitable place in include/libbb.h for
the function declaration. If not, add it somewhere anyway, with or without
@@ -109,41 +126,55 @@ You can look at libbb/Config.src and try to find out if the function is
tunable and add it there if it is.
+Kbuild/Config.in/usage/applets.h snippets in .c files
+-----------------------------------------------------
+
+The old way of adding new applets was to put all the information needed by the
+configuration and build system into appropriate files (namely: Kbuild.src and
+Config.src in new applet's directory) and to add the applet declaration and
+usage info text to include/applets.src.h and include/usage.src.h respectively.
+
+Since the scripts/gen_build_files.sh script had been introduced, the preferred
+way is to have all these declarations contained within the applet .c files.
+
+Every line intended to be processed by gen_build_files.sh should start as a
+comment without any preceding whitespaces and be followed by an appropriate
+keyword - kbuild, config, usage or applet - and a colon, just like shown in the
+first example above.
+
+
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 kbuild snippet to the .c file:
-Add the applet to Kbuild.src in the chosen directory:
+//kbuild:lib-$(CONFIG_MU) += mu.o
-lib-$(CONFIG_MU) += mu.o
+Add the config snippet to the .c file:
-Add the applet to Config.src in the chosen directory:
-
-config MU
- bool "MU"
- default n
- help
- Returns an indeterminate value.
+//config:config MU
+//config: bool "MU"
+//config: default n
+//config: help
+//config: Returns an indeterminate value.
Usage String(s)
---------------
-Next, add usage information for you applet to include/usage.src.h.
+Next, add usage information for your applet to the .c file.
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" \
- ...
+//usage:#define mu_trivial_usage
+//usage: "-[abcde] FILES"
+//usage:#define mu_full_usage
+//usage: "Returns an indeterminate value.\n\n"
+//usage: "Options:\n"
+//usage: "\t-a\t\tfirst function\n"
+//usage: "\t-b\t\tsecond function\n"
+//usage: ...
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
@@ -154,15 +185,11 @@ currently exist in usage.src.h.)
Header Files
------------
-Next, add an entry to include/applets.src.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:
-
-Be sure to read the top of applets.src.h before adding your applet.
+Finally add the applet declaration snippet. Be sure to read the top of
+applets.src.h before adding your applet - it contains important info
+on applet macros and conventions.
- /* all programs above here are alphabetically "less than" 'mu' */
- IF_MU(APPLET(mu, BB_DIR_USR_BIN, BB_SUID_DROP))
- /* all programs below here are alphabetically "greater than" 'mu' */
+//applet:IF_MU(APPLET(mu, BB_DIR_USR_BIN, BB_SUID_DROP))
The Grand Announcement