1Embedded Shell Scripts in BusyBox
2=================================
3
4BusyBox allows applets to be implemented as shell scripts.  Since
5this obviously requires a shell to interpret the scripts the feature
6depends on having a shell built into the binary.  Either ash or hush
7will do.  If both are present ash will be used.  Support for embedded
8scripts also has to be enabled.
9
10It's unlikely that your applet will be implemented as a pure shell
11script:  it will probably need some external commands.  If these are
12to be provided by BusyBox you'll need to ensure they're enabled too.
13
14There are two ways to include scripts in BusyBox:  the quick-and-dirty
15custom script and the full-featured scripted applet.
16
17Custom Scripts
18--------------
19
20When embedded script support is enabled the BusyBox build process
21assumes that any files in the directory 'embed' at the top level of
22the source tree are scripts to be embedded.
23
24The embed directory isn't present in the BusyBox source tree and
25BusyBox itself will never put anything there:  it's entirely for the
26use of third parties.
27
28Adding a custom script is as simple as running the following sequence
29of commands in the BusyBox source directory:
30
31   mkdir embed
32   echo 'echo foo' >embed/foo
33   make defconfig
34   make
35
36The resulting binary includes the new applet foo!
37
38Custom scripts have limited opportunities for configuration:  the only
39control developers have is to put them in the embed directory, or not.
40Everything else takes default values.  For more control you need the
41additional features provided by scripted applets.
42
43Scripted Applets
44----------------
45
46Suppose we want to make a shell script version of the sample applet
47from the New Applet HOWTO.  First we'd have to write a script (vaguely)
48equivalent to the C code:
49
50   return $(($RANDOM%256))
51
52This should be placed in the file applets_sh/mu in the source tree.
53
54Next we need the configuration data.  This is very similar to the example
55code for the native applet:
56
57//config:config MU
58//config:	bool "MU"
59//config:	default y
60//config:	help
61//config:	Returns an indeterminate value.
62
63//applet:IF_MU(APPLET_SCRIPTED(mu, scripted, BB_DIR_USR_BIN, BB_SUID_DROP, mu))
64
65//usage:#define mu_trivial_usage
66//usage:	"[-abcde] FILE..."
67//usage:#define mu_full_usage
68//usage:	"Returns an indeterminate value\n"
69//usage:     "\n	-a	First function"
70//usage:     "\n	-b	Second function"
71
72The only difference is that the applet is specified as being of type
73APPLET_SCRIPTED.  It would also be useful to include details of any
74dependencies the script has.  No external commands are used by our mu
75script, but it does depend on optional shell features.  We can ensure
76these are selected by adding this to the configuration:
77
78//config:config MU_DEPENDENCIES
79//config:	bool "Enable dependencies for mu"
80//config:	default y
81//config:	depends on MU
82//config:	select ASH_RANDOM_SUPPORT
83//config:	select FEATURE_SH_MATH
84//config:	help
85//config:	mu is implemented as a shell script. It requires support
86//config:	for $RANDOM and arithmetic.
87
88The configuration data should be placed in a C file in an appropriate
89subdirectory.  There isn't any C code, though!  In this case the file
90could be miscutils/mu.c.
91
92Scripted applets are just as configurable as applets written in C.
93They can be enabled or disabled using the configuration menu; their
94install directory can be specified and their usage messages are stored
95along with those of all other applets.
96
97Additional Notes
98----------------
99
100The source for embedded scripts can be displayed by running:
101
102   busybox --show SCRIPT
103
104This can be disabled by turning off FEATURE_SHOW_SCRIPT in the
105configuration, though it won't prevent a determined user from
106extracting the source code.
107
108It can be argued that embedded scripts are linked into the BusyBox
109binary and are therefore not subject to the 'mere aggregation'
110exception in the GPL.  If this is the case embedded scripts should
111have a licence compatible with BusyBox's GPL v2-only licence.
112