{"id":50071841,"url":"https://github.com/jeffersonmourak/circ-compiler","last_synced_at":"2026-05-22T03:14:03.916Z","repository":{"id":357493470,"uuid":"1227221508","full_name":"jeffersonmourak/circ-compiler","owner":"jeffersonmourak","description":"A small language for building and simulating logic circuits - for people learning how computers work. In the spirit of Nand2Tetris and Petzold's Code.","archived":false,"fork":false,"pushed_at":"2026-05-21T03:09:27.000Z","size":4319,"stargazers_count":11,"open_issues_count":1,"forks_count":4,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-21T05:32:48.005Z","etag":null,"topics":["circuit-compiler","circuit-design","circuit-simulator","cli","compiler","digital-logic","electronics","hdl","logic-gates","peg-parser","simulation","wasm","wasm-runtime","webassembly","zig"],"latest_commit_sha":null,"homepage":"https://circ-lang.org/","language":"Zig","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jeffersonmourak.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-02T11:33:33.000Z","updated_at":"2026-05-21T03:06:24.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/jeffersonmourak/circ-compiler","commit_stats":null,"previous_names":["jeffersonmourak/circ-compiler"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/jeffersonmourak/circ-compiler","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeffersonmourak%2Fcirc-compiler","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeffersonmourak%2Fcirc-compiler/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeffersonmourak%2Fcirc-compiler/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeffersonmourak%2Fcirc-compiler/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jeffersonmourak","download_url":"https://codeload.github.com/jeffersonmourak/circ-compiler/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeffersonmourak%2Fcirc-compiler/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33326844,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-21T12:23:38.849Z","status":"online","status_checked_at":"2026-05-22T02:00:06.671Z","response_time":265,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["circuit-compiler","circuit-design","circuit-simulator","cli","compiler","digital-logic","electronics","hdl","logic-gates","peg-parser","simulation","wasm","wasm-runtime","webassembly","zig"],"created_at":"2026-05-22T03:14:00.472Z","updated_at":"2026-05-22T03:14:03.909Z","avatar_url":"https://github.com/jeffersonmourak.png","language":"Zig","funding_links":[],"categories":[],"sub_categories":[],"readme":"# circ-compiler\n\n`circ-compiler` compiles `.circ` digital-logic source files into self-contained WebAssembly modules. Each compiled `.wasm` embeds the simulation engine plus circuit-specific construction code and exposes a fixed pull-based runtime API (`init`, `run`, `setPin`, `getOutputState`, …) usable from any host that supports WebAssembly. The compiler is written in Zig and ships as a single CLI: `circ-compile`.\n\n## What it does\n\nGiven a `.circ` source like:\n\n```text\ninput a\nnot inv(in=a)\noutput out(in=inv.out)\n```\n\n`circ-compile inverter.circ -o inverter.wasm` produces a `.wasm` whose exported `setPin` / `run` / `getOutputState` functions simulate that exact circuit. Multi-file projects work the same way — the root file imports siblings and the compiler flattens every sub-circuit into a single ordered topology before serializing it into the `.wasm`:\n\n```text\n// half_adder.circ\ninput a, b\nxor s(a=a, b=b)\nand c(a=a, b=b)\noutput sum(in=s.out)\noutput carry(in=c.out)\n\n// root.circ\nimport half_adder \"half_adder.circ\"\ninput a, b\nhalf_adder ha(a=a, b=b)\noutput sum(in=ha.sum)\noutput carry(in=ha.carry)\n```\n\nBuilt-in macros (`or`, `nand`, `nor`, `xor`, `xnor`) are auto-imported from a virtual `\u003cbuiltin\u003e/` filesystem and compose like any user sub-circuit. See `DOCS/circuit-format.md` for the full surface.\n\n## Install\n\nPrerequisites:\n\n- [Zig](https://ziglang.org/) 0.15.x.\n- [Go](https://go.dev/) 1.21+ — used to compile the langlang-generated parser into a CGo c-archive that links into the Zig binary. Every build runs `go build` once to (re)produce `lib/parser/parser.a`.\n- Optional: [langlang](https://github.com/clarete/langlang) `v0.0.12` — only needed if you want to regenerate `lib/parser/parser.go` from `lib/grammar/proto-circ.peg`. The generated source is vendored in the repo, so contributors who don't touch the grammar do not need langlang installed. Install with `go install github.com/clarete/langlang/go/cmd/langlang@v0.0.12`.\n\nBuild the CLI:\n\n```sh\nzig build circ-compile\n```\n\nThe binary lands at `zig-out/bin/circ-compile`. Run the test suite with:\n\n```sh\nzig build test\n```\n\n(Set `CIRC_SKIP_PERF=1` to skip the smoke perf test in noisy CI environments.)\n\n## Usage\n\n`circ-compile` has five mutually exclusive modes:\n\n| Invocation                                       | Produces                                                                                       |\n|--------------------------------------------------|------------------------------------------------------------------------------------------------|\n| `circ-compile input.circ -o out.wasm`            | A self-contained `.wasm` artifact (default mode).                                              |\n| `circ-compile input.circ --emit-zig -o out.zig`  | The generated standalone Zig source for the experimental emit pipeline.                        |\n| `circ-compile input.circ --inspect`              | Pretty-printed parse tree, resolved IR, and diagnostics on stdout.                             |\n| `circ-compile input.circ --preview`              | ASCII schematic of the resolved circuit on stdout (no artifact written).                       |\n| `circ-compile input.circ --truth-table`          | Markdown truth table enumerating every input vector against the simulated circuit, on stdout.  |\n\nIn default compile mode, `circ-compile` runs the parser, resolver, validator, and topology serializers in-process and splices the resulting `circ.topology.v0.min` and `circ.topology.v0.full` blobs into a vendored prebuilt runtime `.wasm` (embedded in the CLI via `@embedFile`). No `zig` toolchain or subprocess is required at user runtime.\n\nAdditional flags:\n\n- `--warnings-as-errors` (alias `-Werror`) — promote warnings to hard errors (suppresses emission).\n- `--expand-macros` — only valid with `--preview`; renders builtin macros (`xor`, `nand`, …) as their expanded primitive sub-circuits.\n- `--color=auto|always|never` — only valid with `--preview`; controls ANSI styling of the schematic. Default is `auto` (on when stdout is a TTY; the `NO_COLOR` env var also disables colour).\n- `--format=markdown|csv|json` — only valid with `--truth-table`; selects the output format. Default is `markdown`. CSV uses `0`/`1`/`?` cells; JSON encodes undefined cells as `null` so consumers can branch on type.\n- `--strict` — only valid with `--truth-table`; promotes any `?` (undefined) output cell into a hard exit-1 with one diagnostic line per offending row on stderr. The table itself still renders. Useful as a CI gate — a regression that introduces a dangling output now fails the build instead of silently producing `?` rows.\n\nHard errors block emission — partial or \"best-effort\" artifacts are never produced. Diagnostics use stable codes (`E001`–`E013`, `W001`–`W003`) so downstream tooling can match on them.\n\n## Documentation\n\n- `DOCS/getting-started.md` — write, compile, and run your first circuit (start here).\n- `DOCS/circuit-format.md` — the `.circ` language reference.\n- `DOCS/wasm-api.md` — runtime API exposed by the compiled `.wasm`.\n- `DOCS/simulation-engine.md` — the engine the compiler targets.\n- `DOCS/architecture.md` and `DOCS/decisions/` — design rationale for contributors.\n\n## License\n\n[GNU General Public License v3.0](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjeffersonmourak%2Fcirc-compiler","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjeffersonmourak%2Fcirc-compiler","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjeffersonmourak%2Fcirc-compiler/lists"}