Skip to content

INSTRUCTORS.md

Latest commit

 

History

History
70 lines (52 loc) · 3.52 KB

INSTRUCTORS.md

File metadata and controls

70 lines (52 loc) · 3.52 KB

Creating a new exercise

Hazel supports three kinds of exercises, captured by the Exercise.t sum type in src/web/exercises/Exercise.re. Logic common to all exercise kinds lives in Exercise.re; logic specific to each kind lives in its own <Kind>Exercise*.re / <Kind>ExerciseMode.re / <Kind>Grading.re modules:

Constructor Kind Spec module Editor/View module Template file
Code Programming CodeExercise CodeExerciseMode src/web/exercises/examples/BlankCodeExercise.ml
Derivation Derivations DerivationExercise DerivationExerciseMode src/web/exercises/examples/BlankDerivationExercise.ml
Theorem Proofs TheoremExercise TheoremExerciseMode src/web/exercises/examples/BlankTheoremExercise.ml

Shared grading primitives (score, percentage, score_view, ...) live in src/web/exercises/Grading.re; code-exercise-specific grading (test validation, mutation testing, syntax checks, impl grading) lives in CodeGrading.re. Batch grade report generation is exposed via the Hazel CLI (src/CLI/Grade.re), which dispatches over each exercise kind and is invoked by the grade-json / grade-report subcommands.

Generic workflow

The cycle for creating an exercise of any kind is the same:

  1. Copy the appropriate template file from src/web/exercises/examples/ (or any other subdirectory of your choosing under src/web/exercises) and rename it to match your exercise module name, e.g. Ex_MyNewExercise. Use the .ml extension (for technical reasons). Make sure the module_name field in the file matches your exercise module name (without the extension).

  2. Add your exercise to the exercises list in src/web/exercises/settings/ExerciseSettings_base.re, e.g.

    let exercises: list(Exercise.t) = [
  ...
  Ex_MyNewExercise.exercise,
];

  3. Compile and load Hazel (make serve), select your exercise, and make sure Instructor Mode is on (graduation-cap toggle in the top bar).

  4. When satisfied, click the "Export Exercise Module" button in the File menu. This downloads a replacement for your .ml file that you can drop in, blowing away the stub in the blank template.

  5. Compile and run again; your exercise will load in the state you exported. Keep iterating until the exercise is ready.

Building

make and make release create instructor mode versions of Hazel.

make student and make student-release create student mode versions, which obviously don't let you enter instructor mode.

Notably, student and instructor mode have a different serialization format, so it probably won't work to go between the two without clearing your local storage (in browser dev tools).

Generating Grade Reports (for Gradescope, etc.)

Grade reports are generated by the Hazel CLI (see src/CLI/README.md). Two subcommands are available:

  • ./hazel grade-json <submission.json> --output <out.json> — writes the raw grading data as JSON (one section per exercise, each with name, summary, and overall = [earned, max]).
  • ./hazel grade-report <submission.json> --output <out.txt> — writes a human-readable text report with per-exercise summaries and a total at the bottom.

Omit --output to write to stdout instead.
⚡