{"id":51616875,"url":"https://github.com/mellonis/machine-toolchains","last_synced_at":"2026-07-12T14:30:31.433Z","repository":{"id":370901575,"uuid":"1290400210","full_name":"mellonis/machine-toolchains","owner":"mellonis","description":"cc/as/ld-style toolchain family for tape machines, in Rust. First target: the Post machine — pmt: C-like .pmc compiler with optimizer, assembler/disassembler, linker, bus-accurate sans-I/O VM.","archived":false,"fork":false,"pushed_at":"2026-07-11T19:41:25.000Z","size":1326,"stargazers_count":1,"open_issues_count":16,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-07-11T21:11:16.233Z","etag":null,"topics":["assembler","compiler","disassembler","linker","post-machine","rust","toolchain","turing-machine","virtual-machine"],"latest_commit_sha":null,"homepage":null,"language":"Rust","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/mellonis.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-07-05T23:04:25.000Z","updated_at":"2026-07-11T19:41:35.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/mellonis/machine-toolchains","commit_stats":null,"previous_names":["mellonis/machine-toolchains"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/mellonis/machine-toolchains","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mellonis%2Fmachine-toolchains","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mellonis%2Fmachine-toolchains/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mellonis%2Fmachine-toolchains/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mellonis%2Fmachine-toolchains/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mellonis","download_url":"https://codeload.github.com/mellonis/machine-toolchains/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mellonis%2Fmachine-toolchains/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35394859,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-12T02:00:06.386Z","response_time":87,"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":["assembler","compiler","disassembler","linker","post-machine","rust","toolchain","turing-machine","virtual-machine"],"created_at":"2026-07-12T14:30:30.520Z","updated_at":"2026-07-12T14:30:31.428Z","avatar_url":"https://github.com/mellonis.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# machine-toolchains\n\nA Rust toolchain for a Post machine: a C-like source language (`.pmc`), an\noptimizing compiler, an assembler/disassembler, a linker, and a\nbus-accurate bytecode processor (VM), all driven by one CLI, `pmt`. It\nfinishes work started across four Delphi implementations of a Post machine\nbuilt between 2002 and 2012 — a language without a code generator, a code\ngenerator without that language, and a machine without a compiler — and\nadds the piece none of them attempted: a linker, with separate compilation\nand libraries. See `docs/history.md` for the full lineage, including the\ntwo 2002-era programs (`Sum.pms`/`Ty.pms`) this project still carries as\ngolden tests. `pmt lsp` runs a Language Server Protocol server for `.pmc`\non stdio, wired into any LSP-capable editor, with diagnostics, completions,\ngo-to-definition, quickfixes, semantic tokens, an outline, and formatting\nbacked by the same compiler and linter the CLI uses.\n\n## Build\n\n```\ncargo build --release\n```\n\nProduces the `pmt` binary at `target/release/pmt`.\n\n## Quick start\n\nThe five commands below compile, link, build an input tape, run, and\ndisassemble a port of the historic `Sum.pms` program (unary addition: two\nmarked sections separated by one blank cell, each of length n+1 for the\nnumber n it represents). The commands write `.pmo`, `.pmx`, `.pmx.map`,\nand `.pmt` files into the current directory — consider running them from a\nscratch directory. From the repository root, with `pmt` built as above:\n\n```\n$ target/release/pmt compile crates/post-machine/tests/golden/sum.pmc -o sum.pmo\n$ target/release/pmt link sum.pmo -o sum.pmx\n$ target/release/pmt tape build \"*** **\" -o sum.pmt\n$ target/release/pmt run sum.pmx --tape-block sum.pmt\noutcome: Stopped\nsteps 53, core tacts 142, stall tacts 50 (total 192)\norigin 0, head 0\n|****|\n ^\n$ target/release/pmt dis sum.pmx\n.func main\n        call    std::goToEnd\n        rgt\n        rgt\n        call    std::goToEnd\n        wr      0\n        lft\n        call    std::goToBegin\n        lft\n        wr      1\n        call    std::goToEnd\n        wr      0\n        lft\n        call    std::goToBegin\n        stp\n.func std::goToEnd\nL0018:  rgt\n        jm.s    L0018\n        lft\n        ret\n.func std::goToBegin\nL001E:  lft\n        jm.s    L001E\n        rgt\n        ret\n```\n\nThe input tape reads `*** **` — three marks (representing 2), a blank, two\nmarks (representing 1) — and `run` reports the final tape `****`: four\nmarks, representing 3 = 2 + 1. `compile`/`link` (`-o`) both accept `-v` to\nrender their stage reports; `tape build`/`run --tape-block` build and\nconsume `.pmt` snapshots; `dis` shows the linked `.pmx` with real function\nnames resolved from the `.pmx.map` sidecar that `link` wrote alongside it.\nFull flag reference: `docs/cli.md`.\n\n## Documentation\n\n- `docs/language.md` — the `.pmc` source language: structure, statements,\n  visibility/namespaces/imports, optimization, and the IR artifact.\n- `docs/isa.md` — the PM-1 processor: registers, buses, the opcode table,\n  timing, execution, and the debug API.\n- `docs/formats.md` — the binary/text container formats: `.pmo`, `.pmx`,\n  `.pmt`, `.pma`, the `.pmx.map` sidecar, and IR JSON.\n- `docs/cli.md` — every `pmt` subcommand and flag.\n- `docs/lint.md` — hygiene findings over `.pmc` sources via `pmt lint`,\n  with `--fix`.\n- `docs/fmt.md` — the canonical `.pmc` layout via `pmt fmt`, with\n  `--check` and stdin.\n- `docs/lsp.md` — the `pmt lsp` language server: capabilities, editor\n  wiring, and configuration.\n- `docs/stdlib.md` — the standard library's routine roster and linking\n  semantics.\n- `docs/history.md` — where this design comes from.\n\nThe original design document,\n`docs/superpowers/specs/2026-07-04-post-machine-toolchain-design.md`, is\nfrozen as a historical record — see its banner and `docs/history.md` for\nwhy.\n\n## Workspace layout\n\nA two-crate Cargo workspace:\n\n- `crates/core` (library) — the VM core and buses, tape devices, the\n  `MO`/`MX`/`MT` container formats, the linker, and the\n  assembler/disassembler frameworks. Arch-agnostic by contract: it carries\n  no PM-1-specific knowledge, and its own tests run against a small fake\n  test architecture to prove that.\n- `crates/post-machine` (library + the `pmt` binary) — the PM-1\n  architecture module, the `.pmc` compiler and optimizer, the standard\n  library, and the `pmt` CLI itself. The CLI is a thin renderer: library\n  code never prints, so every stage above is usable directly from Rust\n  (or, one day, from another front end) without going through a\n  subprocess.\n\n## Tests\n\n```\ncargo test --workspace\n```\n\nruns everything: unit tests co-located in both crates, integration tests\nunder each crate's `tests/` directory (format/relaxation round-trips,\ncompiler and linker end-to-end programs, golden ports of the historic\n`Sum.pms`/`Ty.pms`, optimizer equivalence checks), and property tests for\ncontainer round-trips. `cargo clippy --workspace --all-targets -- -D\nwarnings` and `cargo fmt --check` are the other two quality gates this\nworkspace holds itself to.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmellonis%2Fmachine-toolchains","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmellonis%2Fmachine-toolchains","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmellonis%2Fmachine-toolchains/lists"}