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>
author: Bartosz Golaszewski <bartekgola@gmail.com> 2014-03-12 22:43:50 +0100
committer: Denys Vlasenko <vda.linux@googlemail.com> 2014-03-16 18:47:44 +0100
commit: 9dbe4d054703ac96355c90bd7794d14d206e10c5 (patch)
tree: 4cf5830acd7a6fe4fd9dff6dac127a624e29250d /docs
parent: 109ee5d33694a03cda3424b4846584250832ba8e (diff)
download: busybox-w32-9dbe4d054703ac96355c90bd7794d14d206e10c5.tar.gz
busybox-w32-9dbe4d054703ac96355c90bd7794d14d206e10c5.tar.bz2
busybox-w32-9dbe4d054703ac96355c90bd7794d14d206e10c5.zip
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.
+boilerplate and Config.in/Kbuild/usage/applet.h snippets (more on that below
-And be sure to put it in <applet>.c. Usage does not have to be taken care of by
+in this document). Be sure to name the main function <applet>_main instead
-your applet.
+of main. And be sure to put it in <applet>.c. Make sure to #include "libbb.h"
-Make sure to #include "libbb.h" as the first include file in your applet.
+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
+Remember about the kbuild snippet.
-in libbb/Kbuild.src. You should look at the conditional part of
-libbb/Kbuild.src as well.
 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
+Add the kbuild snippet to the .c file:
-sorted alphabetically.
-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:config MU
+//config:       bool "MU"
-config MU
+//config:       default n
-        bool "MU"
+//config:       help
-        default n
+//config:         Returns an indeterminate value.
-        help
-          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 \
+//usage:#define mu_trivial_usage
-                "-[abcde] FILES"
+//usage:        "-[abcde] FILES"
-        #define mu_full_usage \
+//usage:#define mu_full_usage
-                "Returns an indeterminate value.\n\n" \
+//usage:        "Returns an indeterminate value.\n\n"
-                "Options:\n" \
+//usage:        "Options:\n"
-                "\t-a\t\tfirst function\n" \
+//usage:        "\t-a\t\tfirst function\n"
-                "\t-b\t\tsecond 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
+Finally add the applet declaration snippet. Be sure to read the top of
-in alphabetical order, or else it will break the binary-search lookup
+applets.src.h before adding your applet - it contains important info
-algorithm in busybox.c and the Gods of BusyBox smite you. Yea, verily:
+on applet macros and conventions.
-Be sure to read the top of applets.src.h before adding your applet.
-        /* all programs above here are alphabetically "less than" 'mu' */
+//applet:IF_MU(APPLET(mu, BB_DIR_USR_BIN, BB_SUID_DROP))
-        IF_MU(APPLET(mu, BB_DIR_USR_BIN, BB_SUID_DROP))
-        /* all programs below here are alphabetically "greater than" 'mu' */
 The Grand Announcement
author	Bartosz Golaszewski <bartekgola@gmail.com>	2014-03-12 22:43:50 +0100
committer	Denys Vlasenko <vda.linux@googlemail.com>	2014-03-16 18:47:44 +0100
commit	9dbe4d054703ac96355c90bd7794d14d206e10c5 (patch)
tree	4cf5830acd7a6fe4fd9dff6dac127a624e29250d /docs
parent	109ee5d33694a03cda3424b4846584250832ba8e (diff)
download	busybox-w32-9dbe4d054703ac96355c90bd7794d14d206e10c5.tar.gz busybox-w32-9dbe4d054703ac96355c90bd7794d14d206e10c5.tar.bz2 busybox-w32-9dbe4d054703ac96355c90bd7794d14d206e10c5.zip

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
16		16
17	First, write your applet. Be sure to include copyright information at the top,	17	First, write your applet. Be sure to include copyright information at the top,
18	such as who you stole the code from and so forth. Also include the mini-GPL	18	such as who you stole the code from and so forth. Also include the mini-GPL
19	boilerplate. Be sure to name the main function <applet>_main instead of main.	19	boilerplate and Config.in/Kbuild/usage/applet.h snippets (more on that below
20	And be sure to put it in <applet>.c. Usage does not have to be taken care of by	20	in this document). Be sure to name the main function <applet>_main instead
21	your applet.	21	of main. And be sure to put it in <applet>.c. Make sure to #include "libbb.h"
22	Make sure to #include "libbb.h" as the first include file in your applet.	22	as the first include file in your applet.
23		23
24	For a new applet mu, here is the code that would go in mu.c:	24	For a new applet mu, here is the code that would go in mu.c:
25		25
@@ -41,6 +41,23 @@ For a new applet mu, here is the code that would go in mu.c:
41	#include "libbb.h"	41	#include "libbb.h"
42	#include "other.h"	42	#include "other.h"
43		43
		44	//config:config MU
		45	//config: bool "MU"
		46	//config: default n
		47	//config: help
		48	//config: Returns an indeterminate value.
		49
		50	//kbuild:lib-$(CONFIG_MU) += mu.o
		51	//applet:IF_MU(APPLET(mu, BB_DIR_USR_BIN, BB_SUID_DROP))
		52
		53	//usage:#define mu_trivial_usage
		54	//usage: "-[abcde] FILES"
		55	//usage:#define mu_full_usage
		56	//usage: "Returns an indeterminate value.\n\n"
		57	//usage: "Options:\n"
		58	//usage: "\t-a\t\tfirst function\n"
		59	//usage: "\t-b\t\tsecond function\n"
		60
44	int mu_main(int argc, char **argv) MAIN_EXTERNALLY_VISIBLE;	61	int mu_main(int argc, char **argv) MAIN_EXTERNALLY_VISIBLE;
45	int mu_main(int argc, char **argv)	62	int mu_main(int argc, char **argv)
46	{	63	{
@@ -90,6 +107,8 @@ Make a new file named <function_name>.c
90	#include "libbb.h"	107	#include "libbb.h"
91	#include "other.h"	108	#include "other.h"
92		109
		110	//kbuild:lib-y += function.o
		111
93	int function(char *a)	112	int function(char *a)
94	{	113	{
95	return *a;	114	return *a;
@@ -97,9 +116,7 @@ int function(char *a)
97		116
98	----end example code------	117	----end example code------
99		118
100	Add <function_name>.o in the right alphabetically sorted place	119	Remember about the kbuild snippet.
101	in libbb/Kbuild.src. You should look at the conditional part of
102	libbb/Kbuild.src as well.
103		120
104	You should also try to find a suitable place in include/libbb.h for	121	You should also try to find a suitable place in include/libbb.h for
105	the function declaration. If not, add it somewhere anyway, with or without	122	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
109	tunable and add it there if it is.	126	tunable and add it there if it is.
110		127
111		128
		129	Kbuild/Config.in/usage/applets.h snippets in .c files
		130	-----------------------------------------------------
		131
		132	The old way of adding new applets was to put all the information needed by the
		133	configuration and build system into appropriate files (namely: Kbuild.src and
		134	Config.src in new applet's directory) and to add the applet declaration and
		135	usage info text to include/applets.src.h and include/usage.src.h respectively.
		136
		137	Since the scripts/gen_build_files.sh script had been introduced, the preferred
		138	way is to have all these declarations contained within the applet .c files.
		139
		140	Every line intended to be processed by gen_build_files.sh should start as a
		141	comment without any preceding whitespaces and be followed by an appropriate
		142	keyword - kbuild, config, usage or applet - and a colon, just like shown in the
		143	first example above.
		144
		145
112	Placement / Directory	146	Placement / Directory
113	---------------------	147	---------------------
114		148
115	Find the appropriate directory for your new applet.	149	Find the appropriate directory for your new applet.
116		150
117	Make sure you find the appropriate places in the files, the applets are	151	Add the kbuild snippet to the .c file:
118	sorted alphabetically.
119		152
120	Add the applet to Kbuild.src in the chosen directory:	153	//kbuild:lib-$(CONFIG_MU) += mu.o
121		154
122	lib-$(CONFIG_MU) += mu.o	155	Add the config snippet to the .c file:
123		156
124	Add the applet to Config.src in the chosen directory:	157	//config:config MU
125		158	//config: bool "MU"
126	config MU	159	//config: default n
127	bool "MU"	160	//config: help
128	default n	161	//config: Returns an indeterminate value.
129	help
130	Returns an indeterminate value.
131		162
132		163
133	Usage String(s)	164	Usage String(s)
134	---------------	165	---------------
135		166
136	Next, add usage information for you applet to include/usage.src.h.	167	Next, add usage information for your applet to the .c file.
137	This should look like the following:	168	This should look like the following:
138		169
139	#define mu_trivial_usage \	170	//usage:#define mu_trivial_usage
140	"-[abcde] FILES"	171	//usage: "-[abcde] FILES"
141	#define mu_full_usage \	172	//usage:#define mu_full_usage
142	"Returns an indeterminate value.\n\n" \	173	//usage: "Returns an indeterminate value.\n\n"
143	"Options:\n" \	174	//usage: "Options:\n"
144	"\t-a\t\tfirst function\n" \	175	//usage: "\t-a\t\tfirst function\n"
145	"\t-b\t\tsecond function\n" \	176	//usage: "\t-b\t\tsecond function\n"
146	...	177	//usage: ...
147		178
148	If your program supports flags, the flags should be mentioned on the first	179	If your program supports flags, the flags should be mentioned on the first
149	line (-[abcde]) and a detailed description of each flag should go in the	180	line (-[abcde]) and a detailed description of each flag should go in the
@@ -154,15 +185,11 @@ currently exist in usage.src.h.)
154	Header Files	185	Header Files
155	------------	186	------------
156		187
157	Next, add an entry to include/applets.src.h. Be sure to keep the list	188	Finally add the applet declaration snippet. Be sure to read the top of
158	in alphabetical order, or else it will break the binary-search lookup	189	applets.src.h before adding your applet - it contains important info
159	algorithm in busybox.c and the Gods of BusyBox smite you. Yea, verily:	190	on applet macros and conventions.
160
161	Be sure to read the top of applets.src.h before adding your applet.
162		191
163	/* all programs above here are alphabetically "less than" 'mu' */	192	//applet:IF_MU(APPLET(mu, BB_DIR_USR_BIN, BB_SUID_DROP))
164	IF_MU(APPLET(mu, BB_DIR_USR_BIN, BB_SUID_DROP))
165	/* all programs below here are alphabetically "greater than" 'mu' */
166		193
167		194
168	The Grand Announcement	195	The Grand Announcement