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