← Commit list

9dbe4d054

Bartosz Golaszewski

2014-03-16

SUCCESS Duration: 150s

Subject

docs: update new-applet-HOWTO.txt

Binary

No binary (build failed)

Architecture & Compiler Flags

Architecture: x86_64-linux-gnu Compiler: gcc (Ubuntu 11.4.0-1ubuntu1~22.04.3) 11.4.0

—

Build Log

(log yok)

Commit Diff GitHub →

docs/new-applet-HOWTO.txt +62 -35

docs/new-applet-HOWTO.txt+62 -35

@@ -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