> **Documentation index**
>
> Fetch the complete documentation index at: https://circ-lang.org/llms.txt
> Use this file to discover all available pages before exploring further.


# circ

> Logic circuits, written down. A small language for building and simulating logic circuits, made for people learning how computers work.

## Hero example: half-adder

Two inputs, an XOR macro for the sum, an AND for the carry.

### Source

```circ
// half_adder.circ
import xor "<builtin>/xor.circ"
input a, b
xor s(a=a, b=b)
and c(a=a, b=b)
output sum(in=s.out)
output carry(in=c.out)
```

[Edit this in the playground](https://circ-lang.org/playground#pick=example:half-adder)

## Six primitives. Five macros. One import.

A program is a list of declarations: name input pins, place gates, and connect their ports. Combine circuits with imports to build larger ones. If you know the early Nand2Tetris hardware chapters, these building blocks will look familiar.

- Primitives: `and`, `not`, `led`, `wire`, `rom`, `ram`.
- Macros: `or`, `nand`, `nor`, `xor`, `xnor` — expand to primitives.
- Signals: 1–64 bits, `input[4] a`, `a[0..2]`, `{a, b}`.
- Files: `import adder "adder.circ"` — one circuit each.

1. **Write a .circ file.** Use any text editor, or write in the playground to check your wiring as you type.
2. **Compile it.** Run circ-compile to produce a self-contained WebAssembly module. Use --preview to print a schematic in your terminal.
3. **Run the circuit.** Set input pins and read outputs from JavaScript. Run the module in a browser, in Node, or in the playground.

## Source on the left. Schematic on the right.

This half-adder uses XOR for the sum and AND for the carry. Run circ-compile with --preview to print its schematic in your terminal.

```circ
// half_adder.circ
import xor "<builtin>/xor.circ"
input a, b
xor s(a=a, b=b)
and c(a=a, b=b)
output sum(in=s.out)
output carry(in=c.out)
```

```
╭───╮     ╭───╮
│ a ├○●──▶┤   │         ╭───────╮
╰───╯ │   │AND├○───────▶┤ carry │
      │╭─▶┤   │         ╰───────╯
╭───╮ ││  ╰───╯
│ b ├○┼╯
╰───╯ ││  ╭───────╮
      ╰┼─▶┤       │     ╭─────╮
       │  │[xor:s]├○───▶┤ sum │
       ╰─▶┤       │     ╰─────╯
          ╰───────╯
```

[Open it in the playground](https://circ-lang.org/playground#pick=example:half-adder)

## From the gallery

[two-bit-adder](https://circ-lang.org/gallery.md): Adds two 2-bit numbers and produces a sum and carry.

[four-bit-adder](https://circ-lang.org/gallery.md): Adds two 4-bit numbers, passing the carry from one bit to the next.

[rom-lookup](https://circ-lang.org/gallery.md): Stores the squares of 0 through 15. Set an address to read its square.

[All examples](https://circ-lang.org/gallery.md)

## Install

Run it on your own machine.

Linux · macOS · Windows · GPL v3

Download `circ-compile` for Linux, macOS, or Windows: https://circ-lang.org/download.md