SourceForge Logo
shebang-wrapper... workaround sillyness with #!

the #! mechanism has some wierdness and shortcomings which this
wrapper works around... primarily the fact that you can only pass a
single option to the interpreter, and that it ignores the PATH
variable to find the referenced binary.  The wrapper is written in C,
partially for performance, but mostly because of another limitation of
#! which is that on linux (et al?), the interpreter needs to be binary
else you get ENOEXEC, so it's not possible to build this kind of
wrapper with perl for example.

Some interpreters, like perl, will parse apart the single option
passed to it by #!, similar to the way the shell does.  But other
interpreters don't, like sh, and so it can be wrapped with
shebang-wrapper if you need to pass extra, space separated options.

shebang-wrapper takes it's single option and tokenizes it by spaces,
which can be escaped with \ to treat literally. for example a file
called "foo.pl" with the following shebang line:

#!path/to/shebang-wrapper perl -A -B -C\ -D

would act as if you executed:

perl -A -B '-C -D' foo.pl

this wrapper also allows you to use an interpreted-interpreter, if for
some reason you need to do that.  Directly calling an interpreted
script as an interpreter gives you ENOEXEC on linux's execve
call... it wants the interpreter to be a binary.  If you run a script
from a shell, some shells will figure what you're doing pass the right
thing to execve for you... but that won't help if you try to run the
script directly from cron or as a webserver cgi.  This ties in to the
reason this wrapper had to be written in C in the first place.

special options that will not be passed to interpreter:

 first argument is always the name or path of executable to use as the
 interpreter.  if a simple name, wrapper will search for it in the
 PATH (execvp), or else if it's a path (i.e. if it contains "/"),
 wrapper will just use that path.  the following additional special
 arguments will be handled by the wrapper and not passed to the
 interpreter:

 --wrapper-addpath=some/path
   add a path to beginning of PATH before trying to find binary
 --wrapper-env=VAR=value
   add variable VAR initialized to value to the interpreter's
   environment
 --wrapper-debug
   print some debugging messages

TODO: would be nice if shebang-wrapper also interpolated environment
variables, which also something that #! won't do.

command line usage:
shebang-wrapper "<interpreter> [options ...]" interpreted-file

shebang usage:
#!path/to/shebang-wrapper <interpreter> [options ...]