Quick Start

The Hardcaml Web IDE runs entirely in your browser - no installation required!

Using the IDE

1. Go to the IDE
2. Select an example from the Circuit file tree on the left
3. Edit the code in the editor tabs (circuit.ml, circuit.mli, test.ml, input.txt)
4. Click Run to compile and simulate

Understanding the Interface

Editor Tabs

• circuit.ml - Your circuit implementation
• circuit.mli - Module interface (defines I/O circuit layout)
• test.ml - Test harness with expect tests
• input.txt - Input data for some examples (optional)

Output Panel

• Waveform - ASCII visualization of signal values over time
• Output - Test results, showing passed/failed tests and compile errors

Circuit Structure

Every Hardcaml circuit follows this pattern:

(* Define input signals *)
module I = struct
  type 'a t = { clock : 'a; clear : 'a; my_input : 'a [@bits 8] }
  [@@deriving hardcaml]
end

(* Define output signals *)
module O = struct
  type 'a t = { my_output : 'a [@bits 8] }
  [@@deriving hardcaml]
end

(* Create the circuit logic *)
let create scope (i : _ I.t) : _ O.t =
  { my_output = (* ... your logic here ... *) }

(* Wrap for hierarchy *)
let hierarchical scope =
  let module Scoped = Hierarchy.In_scope (I) (O) in
  Scoped.hierarchical ~scope ~name:"my_circuit" create

Writing Tests

Tests use Jane Street’s expect test framework:

let%expect_test "my_test" =
  (* Create simulator *)
  let module Sim = Cyclesim.With_interface (Circuit.I) (Circuit.O) in
  let sim = Sim.create (Circuit.hierarchical (Scope.create ())) in
  let waves, sim = Waveform.create sim in
  let inputs = Cyclesim.inputs sim in

  (* Set inputs and run cycles *)
  inputs.my_input := Bits.of_int ~width:8 42;
  Cyclesim.cycle sim;

  (* Display waveform *)
  Waveform.expect waves;
  [%expect {| |}]  (* Fill in after first run *)

Next Steps

• Your First Circuit - Build a circuit step by step
• Nand2Tetris - Learn by building a computer