README.txt
Stan Warford
May, 2020

Pep9Term Documentation
======================
Version 9.3.0
The Pep9Term application is designed to facilitate the batch grading of
homework assignments in courses that use the text Computer Systems, 5th ed.
The application uses the assembler from the GUI version and produces trace
tag warnings as well as fatal error messages.


Here is the result of running 'pep9term --help'
------------------------------------------------------------------------
Name:
pep9term -- Translate and run Pep/9 assembly language and microcode programs.

Usage:
pep9term [--help] [--version] [--about] 
pep9term asm [--help] [-e error_file] -s source_file -o object_file 
pep9term run [--help] [-i charin_file] [-o charout_file] [--echo-output] [-m max_steps] -s object_file 
pep9term cpuasm [--help] [-e error_file] [--d2] -s microcode_file 
pep9term cpurun [--help] [-e error_file] [--d2] [-p precondition_file] -s microcode_file 


Options:
  -h,--help                   Show this help information.
  -v,--version                Display program version number.
  --about                     Display information about licensing, Qt, and developers.

Subcommands:
  asm                         Assemble a Pep/9 assembler source code program to object code.
  run                         Run a Pep/9 object code program.
  cpuasm                      Check a Pep/9 microcode program for syntax errors.
  cpurun                      Run a Pep/9 microcode program.
------------------------------------------------------------------------


Here is the result of running 'pep9term asm --help'
------------------------------------------------------------------------
Name:
pep9term asm -- Assemble a Pep/9 assembler source code program to object code.

Usage:
pep9term asm [--help] [-e error_file] -s source_file -o object_file 

The source_file must be a .pep file. The object_file must be a .pepo file. If there are assembly errors, an error log file named <source_file>_errLog.txt is created with the error messages. <source_file> is the name of source_file without the .pep extension. If there are no errors, the error log file is not created.

Options:
  -h,--help                   Show this help information.
  -e error_file               Override the name of the default error log file.
  -s source_file              Input Pep/9 source program for assembler.
  -o object_file              Output object code generated from source.
------------------------------------------------------------------------


Here is the result of running 'pep9term run --help'
------------------------------------------------------------------------
Name:
pep9term run -- Run a Pep/9 object code program.

Usage:
pep9term run [--help] [-i charin_file] [-o charout_file] [--echo-output] [-m max_steps] -s object_file 

The object_file must be a .pepo file. If the program takes input, -i is required. If the program produces output, -o is required. As a guard against endless loops the program will abort after max_steps assembly instructions execute. The default value of max_steps is 25000.

Options:
  -h,--help                   Show this help information.
  -i charin_file              File buffered behind the charIn input port.
  -o charout_file             File to which the charOut output port is streamed.
  --echo-output               Echo data written to charOut to std::out.
  -m max_steps                Override the default value of max_steps.
  -s object_file              Input Pep/9 object code program for simulator.
------------------------------------------------------------------------


Here is the result of running 'pep9term cpuasm --help'
------------------------------------------------------------------------
Name:
pep9term cpuasm -- Check a Pep/9 microcode program for syntax errors.

Usage:
pep9term cpuasm [--help] [-e error_file] [--d2] -s microcode_file 

The microcode_file must be a .pepcpu file. If there are micro-assembly errors, an error log file named <microcode_file>_errLog.txt is created with the error messages. <microcode_file> is the name of microcode_file without the .pepcpu extension. If there are no errors, the error log file is not created. Supports 1- and 2-byte data buses with the 1-byte data bus as the default. Supports the extended control section detailed in Pep9Micro.

Options:
  -h,--help                   Show this help information.
  -e error_file               Override the name of the default error log file.
  --d2                        Assemble the microcode program with a 2-byte data bus.
  -s microcode_file           Input Pep/9 microcode source program for microassembler.
------------------------------------------------------------------------


Here is the result of running 'pep9term cpurun --help'
------------------------------------------------------------------------
Name:
pep9term cpurun --  Run a Pep/9 microcode program.

Usage:
pep9term cpurun [--help] [-e error_file] [--d2] [-p precondition_file] -s microcode_file 

The microcode_file must be a .pepcpu file. If there are micro-assembly errors or UnitPost errors, an error log file named <microcode_file>_errLog.txt is created with the error messages. <microcode_file> is the name of source_file without the .pepcpu extension. If there are no errors the error log file is not created. Supports 1- and 2-byte data buses with the 1-byte data bus as the default. If -p is specified, then all UnitPre and UnitPost statements in microcode_file are ignored. The UnitPre and UnitPost statments from precondition_file will be used instead. The precondition_file must be a .pepcpu file.

Options:
  -h,--help                   Show this help information.
  -e error_file               Override the name of the default error log file.
  --d2                        Assemble and run the microcode program with a 2-byte data bus.
  -p precondition_file        Input Pep/9 microcode source program for microassembler.
  -s microcode_file           Input Pep/9 microcode source program for microassembler.
------------------------------------------------------------------------


Example grading System
======================
As an example of how to construct a grading system the following is an annotation
of the bash script files from a system I use at Pepperdine University.

At the beginning of the semester, I assign to each student a two-digit ID number
starting at 01. I reserve number 99 for my solution code. Every source file that a
student submits must be prefixed with her two-digit ID. For example, Assignment 24
requires students to submit the solution for Problems 6.33 in a source file named
'Prob0633.pep' and the solution for Problem 6.39 in a source file named 'Prob0639.pep'.
The student whose assigned two-digit number is 13 would hand in her files named
'13Prob0633.pep' and '13Prob0639.pep'.

Seven bash files are included in this documentation:

onecompile.sh
onetest.sh
oneprintout.sh

allcompile.sh
alltest.sh
allprintout.sh

txt2pdf.sh

The 'one' files are for grading the assignment from a single student.

The 'all' files are for grading the assignment for the entire class.

The txt2pdf.sh file is for producing a PDF file of the tests that can be
annotated with PDF markup and returned to the student. I keep this script
in my bin file, as it is used for all the assignments. It requires the
installation of the open-source utility 'enscript'. See

https://brewinstall.org/install-enscript-on-mac-with-brew/

for installation on MacOS.

To grade the assignment for a single student whose two-digit ID is 13, execute
in this order:

./onecompile.sh 13
./onetest.sh 13
./oneprintout.sh 13

The 'all' files simply perform the same execution for everyone in the class.

Execution of ./onecompile.sh 13
===============================
This script will produce four intermediate text files:

13Prob0633.pepo
   The object file for Problem 6.33 for student 13.
cs330-13-A24-test33.txt
   The corresponding source and listing.
13Prob0639.pepo
   The object file for Problem 6.39 for student 13.
cs330-13-A24-test39.txt
   The corresponding source and listing.

If the source does not assemble, the error message is streamed to a temporary
error log, and then included in place of the listing. Obviously, there is
no .pepo object file in that case.

Execution of ./onetest.sh 13
============================
This script will detect whether there is a .pepo object file for each problem.
If there is a 13Prob0633.pepo file, it will run it through some test cases
and append the expected output and the test output to cs330-13-A24-test33.txt,
and then delete the 13Prob0633.pepo file. It does the same for Problem 6.39.

Execution of ./oneprintout.sh 13
================================
This script packages the two text files cs330-13-A24-test33.txt and
cs330-13-A24-test39.txt into a single PDF file named cs330-13-A24-graded.pdf.
It then deletes the two text files.

Following are annotations of the 'one' script files.

Annotation of ./onecompile.sh
=============================
Lines 9-10
   Remove <CR> from line endings in Windows text files for Unix standard.
Line 11
   /Applications/pep9term.app/Contents/MacOS/pep9term asm -s $1\Prob0633.pep -o $1\Prob0633.pepo
   Execute pep9term in asm mode.
   $1 is the student's two-digit ID number.
   The pep9term app is stored in my global Applications directory.
   The executable is inside the .app application.
Lines 12-14
   Concatenate the listing to the text file.
Line 15
   Concatenate new page character.
Line 16
   Check for error log. If so, concatenate.
Line 24
   Check for listing file. If so, concatenate.
Line 33
   Set permissions of text file to all access.

Annotation of ./onetest.sh
==========================
Lines 7-11
   Concatenate expected output for first test.
Line 11
   Create input file for first test.
Line 12
   /Applications/pep9term.app/Contents/MacOS/pep9term run -s $1\Prob0633.pepo -i $1\input.txt -o $1\output.txt
   Execute pep9term in run mode.
   $1 is the student's two-digit ID number.
Line 13
   Catenate output from run.
Line 14
   Catenate two newline characters.
Line 15
   Delete input and output files.

Annotation of ./oneprintout.sh
==============================
Line 8
   Create a new file starting with the results of the first problem.
Line 16
   Concatenate the results of the second problem.
Line 22
   Create the PDF file from the text file.
Line 23
   Delete the text file.
Line 24
   Set permissions of PDF file to all access.

Also included with this documentation is the final PDF file for student 13.

