diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/embedded-scripts.txt | 116 |
1 files changed, 116 insertions, 0 deletions
diff --git a/docs/embedded-scripts.txt b/docs/embedded-scripts.txt new file mode 100644 index 000000000..1b0c5b591 --- /dev/null +++ b/docs/embedded-scripts.txt @@ -0,0 +1,116 @@ +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 (specifically, ash) built into the binary. +Support for embedded scripts also has to be enabled. + +To embed scripts in BusyBox you must enable these configuration options: + + ASH + ASH_EMBEDDED_SCRIPTS + +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. We can assume that ash is available. +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 ash +//config: support 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. |