71df2d3589
Embedded scripts require a shell to be present in the BusyBox binary. Allow either ash or hush to be used for this purpose. If both are enabled ash takes precedence. The size of the binary is unchanged in the default configuration: both ash and hush are present but support for embedded scripts isn't compiled into hush. Signed-off-by: Ron Yorston <rmy@pobox.com> Signed-off-by: Denys Vlasenko <vda.linux@googlemail.com>
112 lines
3.9 KiB
Plaintext
112 lines
3.9 KiB
Plaintext
Embedded Shell Scripts in BusyBox
|
|
=================================
|
|
|
|
BusyBox allows applets to be implemented as shell scripts. Since
|
|
this obviously requires a shell to interpret the scripts the feature
|
|
depends on having a shell built into the binary. Either ash or hush
|
|
will do. If both are present ash will be used. Support for embedded
|
|
scripts also has to be enabled.
|
|
|
|
It's unlikely that your applet will be implemented as a pure shell
|
|
script: it will probably need some external commands. If these are
|
|
to be provided by BusyBox you'll need to ensure they're enabled too.
|
|
|
|
There are two ways to include scripts in BusyBox: the quick-and-dirty
|
|
custom script and the full-featured scripted applet.
|
|
|
|
Custom Scripts
|
|
--------------
|
|
|
|
When embedded script support is enabled the BusyBox build process
|
|
assumes that any files in the directory 'embed' at the top level of
|
|
the source tree are scripts to be embedded.
|
|
|
|
The embed directory isn't present in the BusyBox source tree and
|
|
BusyBox itself will never put anything there: it's entirely for the
|
|
use of third parties.
|
|
|
|
Adding a custom script is as simple as running the following sequence
|
|
of commands in the BusyBox source directory:
|
|
|
|
mkdir embed
|
|
echo 'echo foo' >embed/foo
|
|
make defconfig
|
|
make
|
|
|
|
The resulting binary includes the new applet foo!
|
|
|
|
Custom scripts have limited opportunities for configuration: the only
|
|
control developers have is to put them in the embed directory, or not.
|
|
Everything else takes default values. For more control you need the
|
|
additional features provided by scripted applets.
|
|
|
|
Scripted Applets
|
|
----------------
|
|
|
|
Suppose we want to make a shell script version of the sample applet
|
|
from the New Applet HOWTO. First we'd have to write a script (vaguely)
|
|
equivalent to the C code:
|
|
|
|
return $(($RANDOM%256))
|
|
|
|
This should be placed in the file applets_sh/mu in the source tree.
|
|
|
|
Next we need the configuration data. This is very similar to the example
|
|
code for the native applet:
|
|
|
|
//config:config MU
|
|
//config: bool "MU"
|
|
//config: default y
|
|
//config: help
|
|
//config: Returns an indeterminate value.
|
|
|
|
//applet:IF_MU(APPLET_SCRIPTED(mu, scripted, BB_DIR_USR_BIN, BB_SUID_DROP, mu))
|
|
|
|
//usage:#define mu_trivial_usage
|
|
//usage: "[-abcde] FILE..."
|
|
//usage:#define mu_full_usage
|
|
//usage: "Returns an indeterminate value\n"
|
|
//usage: "\n -a First function"
|
|
//usage: "\n -b Second function"
|
|
|
|
The only difference is that the applet is specified as being of type
|
|
APPLET_SCRIPTED. It would also be useful to include details of any
|
|
dependencies the script has. No external commands are used by our mu
|
|
script, but it does depend on optional shell features. We can ensure
|
|
these are selected by adding this to the configuration:
|
|
|
|
//config:config MU_DEPENDENCIES
|
|
//config: bool "Enable dependencies for mu"
|
|
//config: default y
|
|
//config: depends on MU
|
|
//config: select ASH_RANDOM_SUPPORT
|
|
//config: select FEATURE_SH_MATH
|
|
//config: help
|
|
//config: mu is implemented as a shell script. It requires support
|
|
//config: for $RANDOM and arithmetic.
|
|
|
|
The configuration data should be placed in a C file in an appropriate
|
|
subdirectory. There isn't any C code, though! In this case the file
|
|
could be miscutils/mu.c.
|
|
|
|
Scripted applets are just as configurable as applets written in C.
|
|
They can be enabled or disabled using the configuration menu; their
|
|
install directory can be specified and their usage messages are stored
|
|
along with those of all other applets.
|
|
|
|
Additional Notes
|
|
----------------
|
|
|
|
The source for embedded scripts can be displayed by running:
|
|
|
|
busybox --show SCRIPT
|
|
|
|
This can be disabled by turning off FEATURE_SHOW_SCRIPT in the
|
|
configuration, though it won't prevent a determined user from
|
|
extracting the source code.
|
|
|
|
It can be argued that embedded scripts are linked into the BusyBox
|
|
binary and are therefore not subject to the 'mere aggregation'
|
|
exception in the GPL. If this is the case embedded scripts should
|
|
have a licence compatible with BusyBox's GPL v2-only licence.
|