Tool Interface

The Tool interface, rather than relying on shared libraries or intricate IPC like most plug-in architectures [23] [3], was designed so as to be easily explained in a couple paragraphs worth of text. No complicated headers are needed, no language requirements are imposed. In fact, it is difficult to imagine a simpler extensibility interface that still runs extensions in a separate process space.

The full requirements for the original tool interface are as follows:

1. Each tool must be executable in the standard UNIX syntax for executables. This implies that the execute bit is set on the file, and the file is either a binary executable or an interpreted script with the proper shebang^5.2 header line.
2. When invoked with the -name option, the tool must print to standard output a long-form name for itself and then exit with return code 2.
3. When invoked with the -help option, the tool must print to standard output a usage message with long-form (GNU-style) arguments. Flags should be specified without an ``='' character. File arguments should be specified as ``-argument=FILE''. All other arguments should have an ``='' character and some value other than ``FILE''.

   For example, Figure 5.3 shows the usage message for the difftest.py tool.

   Figure 5.3: Usage Message for difftest.py

   
   This message will be parsed by Agar, and the configuration dialog shown in Figure 5.4 will be generated, thus obviating any need for the tool developer to have any knowledge of GUI programming, Python, or the wxPython widget set.

   Figure 5.4: A Dynamically Generated Tool Configuration Dialog

   

4. Each tool operates on a single file per invocation. That filename will be passed to the tool as the final command line argument.

5. For success, the tool should return an exit code of 0. For failure, the tool should print relevant error messages to standard output and return an exit code of 1.

When it was realized that binary grading was insufficient, an addendum to the Tool interface was made:

1. Upon termination, a tool wanting to return a non-binary value must output as its first line of output the number of points to be awarded. Only a single decimal place is considered valid (i.e. 10.1 is valid but 10.15 will be truncated).
2. Since the tool is being granted total control over the points awarded, most of the standard tools that utilize this interface also take point values as arguments. For example, the pointlate.py tool, which grants increasing bonus points for submissions up to 3 days early and increasing penalty points for submissions up to 3 days late, has the interface seen in figure 2.

   Figure 5.5: The Early/Late Points Configuration, Demonstrating Common Usage for the Advanced Interface

   
3. Upon termination, a tool using this ``advanced'' interface must return exit code 3.

Every tool in Agar uses only this interface, with the exception of the compile tool. The compile tool (see Figure 5.2.1) has slightly more complicated behavior in that it needs to be able to register an executable for a given submission in the event of a successful compilation. To date, there has been no need for any other special cases, although for the sake of efficiency the ``Success'' and ``Failure'' tests have been hard-coded into the system rather than invoking the overhead of spawning a child process that exits with a given return code.

Figure 5.6: Compilation Dialog