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

• BitterSuiteExternalTesting

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.