BitterSuite External Language Documentation
The External language is designed to be relatively simple, gaining most of its flexibility by supplying a myriad of environment variables and letting whatever executables are referenced handle the details.
Related Pages
Relevant Options
The language is selected by specifying
(language external)
in an
options.ss
file. There is only a single additional option understood by this language:
- (args arg1 ... argN)
- A series of strings (or other values easily converted into strings such as numbers or symbols) which will be supplied to the relevant
test.exe
file on a test run.
Relevant files
There is one file recognized by the External language:
test.exe
. This file must be an executable, likely most commonly a shell script. As tests are run in a testing account but executables are often created as the course account, extra advance care must be taken with the permissions on these files. They should be
chgrp csXXX-t
and
chmod 750
.
This file receives any relevant information it needs via the
args
option and a large number of environment variables. These environment variables are named by the corresponding entries in hash table (after an application of symbol->string and with both original names and names with _ substituted for any -), and the values are string representations of the value list. As a test, you can have a
test.exe
file dump the environment to standard error (in bash,
env >&2
); however, this should
never be done in production code, as standard error should be used exclusively to indicate a serious error in any
RST code.
The executable itself returns information to
BitterSuite via output to two file descriptors. The percentage earned on a question should be output to file descriptor 3 (in bash,
echo '100' >&3
as an example; note that this can also be the string "defer" if output is being generated), and any relevant explanation for that percentage should be output to file descriptor 4. The value output can be a Scheme rational, so something like
echo '200/3' >&3
is fine.