{"id":50809031,"url":"https://github.com/antomfdez/brokm","last_synced_at":"2026-06-13T03:11:56.650Z","repository":{"id":362637137,"uuid":"1259291343","full_name":"antomfdez/brokm","owner":"antomfdez","description":"brokm — a small, fast, embeddable HolyC-flavored general-purpose language (bytecode VM + mark-sweep GC)","archived":false,"fork":false,"pushed_at":"2026-06-05T06:09:25.000Z","size":101,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-05T08:06:29.015Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/antomfdez.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"docs/ROADMAP.md","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-06-04T11:12:52.000Z","updated_at":"2026-06-05T06:09:29.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/antomfdez/brokm","commit_stats":null,"previous_names":["antomfdez/brokm"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/antomfdez/brokm","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/antomfdez%2Fbrokm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/antomfdez%2Fbrokm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/antomfdez%2Fbrokm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/antomfdez%2Fbrokm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/antomfdez","download_url":"https://codeload.github.com/antomfdez/brokm/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/antomfdez%2Fbrokm/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34270485,"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-06-13T02:00:06.617Z","response_time":62,"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":[],"created_at":"2026-06-13T03:11:55.284Z","updated_at":"2026-06-13T03:11:56.634Z","avatar_url":"https://github.com/antomfdez.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# brokm\n\n**brokm** — short for *\"broken minded\"* — is a small, fast, embeddable general-purpose\nlanguage with a clean [HolyC](https://en.wikipedia.org/wiki/TempleOS#HolyC)-flavored syntax.\nIt is built primarily for its author's own use, with four design goals: **small, fast, robust,\nand easy to embed**.\n\nThis is **v1.0** — the first stable release: a working bytecode VM with a precise, **generational** mark-sweep garbage\ncollector, aggregate types (arrays + classes/structs **with methods**), an opt-in\n**manual-memory** mode for low-level work, a **static type checker** that validates the HolyC type\nannotations before any code runs, **typed bytecode** that specializes the int hot path, a\n**baseline JIT** that compiles hot functions to native code (**arm64 + x86-64**, with a full\ninterpreter fallback), an **AOT compiler** (`brokm build`) that turns a program into a\nstandalone native executable, a **standard library** — native builtins (file I/O, strings,\nmath, maps, **scripting**: `Args`/`Env`/`Shell`/`Input`/`Time`/…) plus\n[**`lib/std/` modules written in brokm**](lib/std/) (`#include \"std/std.bk\"`), a **C embedding\nAPI** with **multi-instance VMs** (create any number of independent runtimes, register natives,\nexchange values, call brokm from C), and **multi-file programs** via `#include` — enough that a\n[compiler written in brokm](examples/realcc.bk) emits the VM's real bytecode and **compiles its\nown source** (`make test-bootstrap`, byte-identical to the C compiler — see\n[docs/ROADMAP.md](docs/ROADMAP.md)).\n\n```holyc\n// hello.bk — top-level code runs; a bare string statement prints.\n\"Hello World\\n\";\n\nI64 Fib(I64 n)\n{\n  if (n \u003c 2) return n;\n  return Fib(n - 1) + Fib(n - 2);\n}\n\nI64 i = 0;\nfor (i = 0; i \u003c= 10; ++i)\n  \"Fib(%d) = %d\\n\", i, Fib(i);\n```\n\n## Build \u0026 run\n\nRequires a C99 compiler and `make` (no external dependencies).\n\n```sh\nmake              # builds ./brokm  (-std=c99 -Wall -Wextra, 0 warnings)\n./brokm file.bk   # run a program (JIT-compiled when hot)\n./brokm run file.bk            # same, explicit subcommand\n./brokm build file.bk -o app   # AOT-compile to a standalone native executable\n./brokm build file.bk --emit=c # emit the generated C instead of an executable\n./brokm build file.bk --freestanding # AOT-build with the reduced runtime profile\n./brokm           # start the REPL\nmake test         # run the golden test suite\nmake test-aot     # run the suite AOT-compiled to native executables\nmake test-freestanding # focused checks for the freestanding AOT profile\nmake test-gc      # run the suite with the GC firing on every allocation\nmake bench        # benchmark interpreter vs JIT vs AOT (Fib)\nmake debug        # ASan/UBSan + bytecode/exec tracing build\n```\n\n`brokm build` translates the compiled bytecode to C and drives the system C\ncompiler (options: `-o \u003cout\u003e`, `--emit=c`, `--keep-c`, `--freestanding`,\n`--cc \u003ccompiler\u003e`, `--cflags \u003cflags\u003e` for extra compiler/linker flags such as\n`--target=...` or `-static`, `-O0`..`-O3`, `--verbose`, `--quiet`). The build needs the brokm source tree to\nlink the runtime: it looks next to the `brokm` executable, or wherever\n`BROKM_HOME` points.\n\n## Install \u0026 update\n\nEverything lives in one place — `~/.brokm` is a clone of this repository\nholding the binary, the standard library (`lib/`), and the runtime sources\n`brokm build` links against. One script installs *and* updates:\n\n```sh\nsh install.sh     # clone (or pull) ~/.brokm and build; re-run any time to update\n```\n\nThen add to your shell profile (the script prints these):\n\n```sh\nexport BROKM_HOME=\"$HOME/.brokm\"\nexport PATH=\"$BROKM_HOME:$PATH\"\n```\n\nUninstall with `rm -rf ~/.brokm`. Set `BROKM_HOME` before running the script\nto install somewhere else.\n\n## Scripting \u0026 the standard library\n\nThe native builtins cover scripting basics: `Args()` (command-line arguments),\n`Env`, `Exit`, `Shell` (exit status), `ShellStr` (captured stdout), `Input`\n(read a line), `Time`/`TimeMs`, `Sleep`, `ReadFile`/`WriteFile`/`AppendFile`,\n`FileExists`. On top of them, [`lib/std/`](lib/std/) is a standard library\n**written in brokm**, split into focused modules — `str`, `arr`, `io`, `path`,\n`os` — that any script can pull in by name (resolved via `$BROKM_HOME/lib`,\nfalling back to `~/.brokm/lib`):\n\n```holyc\n#include \"std/std.bk\"   // or just \"std/str.bk\", etc.\n\nU0[] lines = ReadLines(\"/etc/hosts\");\n\"%d hosts lines\\n\", Len(lines);\n\nU0[] parts = StrSplit(EnvOr(\"PATH\", \"\"), \":\");\n\"%s\\n\", StrJoin(ArrSortStr(parts), \"\\n\");\n\nif (Len(Args()) \u003e 0 \u0026\u0026 Args()[0] == \"--touch\")\n  AppendLine(\"log.txt\", \"ran at \" + ToStr(Time()));\n```\n\nbrokm has one flat namespace, so each module prefixes its public names\n(`Str*`, `Arr*`, `Path*`…). See [docs/CODEMAP.md](docs/CODEMAP.md) for the\nfull listing.\n\n## Language at a glance\n\n- **Types** (HolyC-style): `U0 U8 U16 U32 U64 I8 I16 I32 I64 F64 Bool`; default integer is `I64`.\n- **Type-first declarations**: `I64 x = 5;`  `F64 r = 3.14;`\n- **Top-level code executes** — no `main()` required.\n- **Functions**: `I64 Add(I64 a, I64 b) { return a + b; }`\n- **Printing**: a bare string statement prints, with printf-style args:\n  `\"x = %d\\n\", x;` — or call `Print(...)`.\n- **Arrays**: dynamic, heap-allocated — `I64[] a = [1, 2, 3]; a[0] = 9;` with `Len`/`Append`.\n- **Classes/structs**: `class Point { I64 x; I64 y; }`, `Point p = Point(3, 4); p.x = 9;`\n  (reference semantics).\n- **Methods**: declare `I64 Area() { return this.w * this.h; }` in the class body and call\n  `r.Area()`; the receiver is `this`.\n- **Manual memory**: `U0 b = MAlloc(32); PokeI64(b, 0, 42); Free(b);` — raw, GC-invisible\n  buffers with typed peek/poke, plus `GcDisable`/`GcEnable`.\n- **Maps**: string-keyed hash maps — `U0 m = MapNew(); MapSet(m, \"k\", 1); MapGet(m, \"k\");`\n  with `MapHas`/`MapDelete`/`MapLen`/`MapKeys`.\n- **Control flow**: `if/else`, `while`, `for`, `do/while`, `switch/case/default`,\n  `break`, `continue`, `return`.\n- **Multi-file**: `#include \"lib.bk\"` — textual, include-once, resolved relative to the file,\n  then `$BROKM_HOME/lib`, then `~/.brokm/lib` (where the standard library lives).\n- **Operators**: `+ - * / %`, comparisons, `\u0026\u0026 || !`, bitwise `\u0026 | ^ ~ \u003c\u003c \u003e\u003e`,\n  assignment + compound (`+=` …), `++ --`.\n\nFull reference: [docs/SYNTAX.md](docs/SYNTAX.md).\nInternals: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).\n\n## Embedding\n\n```c\n#include \"brokm.h\"\n\nstatic BrokmValue HostAdd(int argc, const BrokmValue *args) {\n  return brokm_int(brokm_as_int(args[0]) + brokm_as_int(args[1]));\n}\n\nint main(void) {\n  BrokmVM *vm = brokm_new();                       /* an independent runtime */\n  brokm_register(vm, \"HostAdd\", HostAdd);          /* expose a C native */\n  brokm_eval(vm, \"I64 Triple(I64 n) { return HostAdd(n, HostAdd(n, n)); }\");\n\n  BrokmValue args[1] = { brokm_int(7) }, result;\n  brokm_call(vm, \"Triple\", 1, args, \u0026result);      /* call brokm from C */\n  /* result == 21; also: brokm_get_global / brokm_set_global, string exchange */\n\n  brokm_free(vm);\n  return 0;\n}\n```\n\nThe API is **instance-based** (v0.11): a host may create any number of independent VMs — each\nwith its own heap, globals, interned strings, and GC — and use or destroy them in any order.\nIt lets a host **register native functions** (per VM), **exchange values** (ints, floats, bools,\nstrings), **read/set globals**, and **call brokm functions from C**. See\n[`examples/embed.c`](examples/embed.c) for a complete program, including two VMs running side by\nside (`make embed \u0026\u0026 ./embed-demo`).\n\n## Editor support\n\nSyntax highlighting for `.bk` files ships under [`editors/`](editors/):\n\n- **Neovim / Vim** — drop-in regex syntax (`editors/nvim/`), no build step.\n- **Sublime Text** — a `.sublime-syntax` (`editors/sublime/`), no build step.\n- **Zed** — a Tree-sitter extension (`editors/zed/`).\n- **Tree-sitter grammar** (`editors/tree-sitter-brokm/`) powers Zed and the\n  `nvim-treesitter` option; it parses every `.bk` file in this repo with no errors.\n\nInstall instructions for each editor are in [`editors/README.md`](editors/README.md).\n\n## broked — an editor written in brokm\n\n[**broked**](https://github.com/antomfdez/broked) is a vim-style terminal code\neditor written entirely in brokm: modal editing (normal, insert, visual,\ncommand), operators (`dw`, `cw`, `d$`, …), counts, registers, undo, search,\nan ex command line, line numbers, and syntax highlighting for `.bk` files.\nbrokm has no raw-tty natives, so its terminal layer is built from the\nscripting stdlib alone — `Shell`/`ShellStr` driving `stty` and `dd`, with\n`ShellStr`'s stdout flush doubling as the frame flush — and `brokm build`\nturns it into a standalone native executable. It comes with a headless test\nsuite that drives the key dispatcher with no terminal attached.\n\n```sh\nbrokm broked.bk file.bk            # run from source\nbrokm build broked.bk -o broked    # or AOT-compile the editor itself\n```\n\n## Status\n\nbrokm runs real programs (arithmetic, variables, control flow, functions, recursion, strings,\n**dynamic arrays**, **classes/structs**, **manual memory**, printing) on a stack bytecode VM,\nwith a precise **generational** mark-sweep collector (minor + major, young→old promotion) whose\nwrite barrier is exercised by array and field mutation and verified red/green. A **static type\nchecker** validates the type annotations between parse and compile — catching arity, argument,\nfield, and class-type errors before execution — using gradual typing so existing programs are\nunaffected. The compiler emits **typed bytecode**: int-specialized arithmetic and comparison\nopcodes on the hot path, with a runtime guard that deopts to the generic handler so gradual\ntyping stays correct. A **baseline JIT** (macOS + Linux, **arm64 + x86-64**) compiles hot functions to\nnative code in `mmap`'d executable pages — profile-gated, with inlined integer\narithmetic/comparisons, branches, and recursion, deopt guards for correctness, and a full\ninterpreter fallback for ineligible functions and every other platform. It runs the recursive\n`Fib` benchmark ~2.5× faster than the interpreter on each architecture (`make bench`). A **standard\nlibrary** of native builtins covers file I/O (`ReadFile`/`WriteFile`/`PrintErr`), strings\n(`CharAt`/`Chr`/`Substr`/`IndexOf`/`ToInt`/`ToStr`), and math\n(`Abs`/`Min`/`Max`/`Sqrt`/`Pow`/`Floor`/`Ceil`) — enough that `examples/lexer.bk` tokenizes and\n`examples/calc.bk` parses + evaluates brokm-flavored source written in brokm, the first steps\ntoward self-hosting. **String-keyed maps** (`MapNew`/`MapGet`/`MapSet`/…) add the symbol-table\nprimitive a self-hosted compiler needs, with their mutations exercising the write barrier\nred/green. Classes carry **methods** (`obj.m(args)` with an implicit `this`, dispatched through a\nnew `OP_INVOKE`), so a compiler's data types can hold behavior. A **C embedding API** lets a host\nregister native functions, exchange scalar and string values, read/set globals, and call brokm\nfunctions from C (`examples/embed.c`). **`#include`** splits a program across files — textual,\ninclude-once, resolved relative to each file. Putting it together, **`examples/realcc.bk` is a\ncompiler written in brokm** (lexer → parser → code generator) that emits the C VM's **real\nbytecode** and runs it directly — and it now **compiles its own complete source**: the\nself-compiled compiler produces byte-identical output to the C compiler (`make test-bootstrap`).\n**Multi-instance VMs** (v0.11) made the runtime instance-based: any number of independent VMs per\nprocess, each with its own heap, globals, and collector. **Portability + CI** (v0.11.1) brought\nthe full matrix — including both JIT backends — to **Linux**, verified by a GitHub Actions matrix\n(macOS arm64 + Linux x86-64, warnings as errors) on every push. The **AOT compiler** (v0.12)\nturns bytecode into C on the same helper ABI the interpreter and JIT share, producing standalone\nnative executables. The **scripting stdlib** (v0.13) added OS/process natives and the\n`lib/std/` modules written in brokm itself, installed and updated as one unit by `install.sh`.\n**Optimized AOT** (v0.14) made the emitted C cache the VM stack top in a C local and call\nAOT-compiled callees directly — AOT binaries now beat the JIT on `make bench` — and AOT\nexecutables link only the runtime core (no parser/typechecker/compiler inside). Next up: a\n`--freestanding` runtime profile, the path toward booting a kernel written in brokm — with a\nruntime in brokm as the long-term star. See the roadmap.\n\n## License\n\nTBD by the author.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fantomfdez%2Fbrokm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fantomfdez%2Fbrokm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fantomfdez%2Fbrokm/lists"}