busybox/docs/embedded-scripts.txt
<<
>>
Prefs
   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