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>

1 files changed, 62 insertions, 35 deletions

diff --git a/docs/new-applet-HOWTO.txt b/docs/new-applet-HOWTO.txt
index 6a8054d0e..28970a50a 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