emo/busybox
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: update new-applet-HOWTO.txt

Browse Source 
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>
This commit is contained in:
Bartosz Golaszewski 2014-03-12 22:43:50 +01:00 committed by Denys Vlasenko
parent 109ee5d336
commit 9dbe4d0547
1 changed files with 62 additions and 35 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

97
docs/new-applet-HOWTO.txt
View File

@ -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:
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.
Be sure to read the top of applets.src.h before adding your applet.
/* 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