summaryrefslogtreecommitdiff
path: root/docs/embedded-scripts.txt
diff options
context:
space:
mode:
authorRon Yorston2018-11-27 10:45:30 +0000
committerDenys Vlasenko2018-11-27 12:33:28 +0100
commit31a04d91c24f6ee180de45e1508dc03dea9f9c11 (patch)
treea4e4d4251fd91c937243d2edfa78fe4ef9a1284f /docs/embedded-scripts.txt
parent403d2574be8f8c41aa46f73dec5f998b2cbf2790 (diff)
downloadbusybox-31a04d91c24f6ee180de45e1508dc03dea9f9c11.zip
busybox-31a04d91c24f6ee180de45e1508dc03dea9f9c11.tar.gz
docs: add embedded-scripts.txt
Signed-off-by: Ron Yorston <rmy@pobox.com> Signed-off-by: Denys Vlasenko <vda.linux@googlemail.com>
Diffstat (limited to 'docs/embedded-scripts.txt')
-rw-r--r--docs/embedded-scripts.txt116
1 files changed, 116 insertions, 0 deletions
diff --git a/docs/embedded-scripts.txt b/docs/embedded-scripts.txt
new file mode 100644
index 0000000..1b0c5b5
--- /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.