{"id":51019718,"url":"https://github.com/pyrex41/shen-julia","last_synced_at":"2026-06-21T15:30:31.356Z","repository":{"id":365999031,"uuid":"1262933587","full_name":"pyrex41/shen-julia","owner":"pyrex41","description":null,"archived":false,"fork":false,"pushed_at":"2026-06-19T20:04:16.000Z","size":1681,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-19T21:13:07.546Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Julia","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pyrex41.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","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-06-08T13:10:26.000Z","updated_at":"2026-06-19T20:01:03.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/pyrex41/shen-julia","commit_stats":null,"previous_names":["pyrex41/shen-julia"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/pyrex41/shen-julia","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pyrex41%2Fshen-julia","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pyrex41%2Fshen-julia/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pyrex41%2Fshen-julia/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pyrex41%2Fshen-julia/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pyrex41","download_url":"https://codeload.github.com/pyrex41/shen-julia/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pyrex41%2Fshen-julia/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34616509,"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-21T02:00:05.568Z","response_time":54,"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-21T15:30:29.343Z","updated_at":"2026-06-21T15:30:31.348Z","avatar_url":"https://github.com/pyrex41.png","language":"Julia","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Shen/Julia\n\nA [Julia](https://julialang.org) port of the **Shen 41.2** language kernel.\n\nShen programs compile to native Julia methods (one `K_\u003cname\u003e` method per Shen\nfunction), so once warmed up this port runs compute-bound code **6–16× faster\nthan the reference SBCL port** (`shen-cl`) and passes the full official kernel\ntest suite **134/134**.\n\n\u003e **Heads-up about startup:** Julia compiles to native code *on first use*, so a\n\u003e from-source start spends ~10 s booting the kernel and the *first* call into the\n\u003e reader/evaluator pays a one-time JIT cost. The fix is a **sysimage** (a\n\u003e prebuilt, fully-native snapshot) — see [Startup time \u0026 sysimages](#startup-time--sysimages).\n\u003e With a sysimage, startup is ~0.5–1.5 s.\n\n---\n\n## Requirements\n\n- **Julia 1.12** (the prebuilt release sysimages are pinned to this version — a\n  sysimage built for one Julia minor version will not load on another). From\n  source, Julia ≥ 1.10 works.\n- No other dependencies; `Project.toml`/`Manifest.toml` pin everything.\n\n## Install\n\n```bash\ngit clone git@github.com:pyrex41/shen-julia.git\ncd shen-julia\njulia --project=. -e 'import Pkg; Pkg.instantiate()'   # one-time dep install\n```\n\nThe launcher is `bin/shen` (a thin shell wrapper around `julia`). Put `bin/` on\nyour `PATH` or call it directly.\n\n## Quick start\n\n```bash\n# Evaluate an expression (prints the value)\n./bin/shen eval -e \"(+ 40 2)\"                 # =\u003e 42\n\n# Load a file, then evaluate against it\n./bin/shen eval -l myprog.shen -e \"(main)\"\n\n# Run a program quietly (no defun echo)\n./bin/shen script myprog.shen\n\n# Interactive REPL (Ctrl-D / EOF exits cleanly)\n./bin/shen\n\n# Version banner (contains 41.2)\n./bin/shen --version\n```\n\nThe CLI mirrors the *standard* Shen launcher (`shen.x.launcher.main`), so the\n`eval` / `script` / `--version` flags behave the same as on `shen-go`,\n`shen-rust`, and `ShenScript`.\n\nFrom Julia directly:\n\n```julia\nusing ShenJulia\nboot!(false)\nrun_kl_string(\"(define square X -\u003e (* X X))\")\nrun_kl_string(\"(square 12)\")   # =\u003e 144\n```\n\n---\n\n## Startup time \u0026 sysimages\n\nThis is the one thing to understand about a Julia-hosted language.\n\n| Path | Boot | First `eval`/`script` | When it's used |\n|------|-----:|----------------------:|----------------|\n| **From source** (no sysimage) | ~10 s | + one-time JIT of reader/evaluator | `SHEN_JULIA_NO_SYSIMAGE=1`, or no `.sys` present |\n| **With sysimage** | ~0.5–1.5 s | negligible | default when `ShenJulia.sys` exists |\n\nWhy: the kernel’s ~1130 functions are **baked ahead of time** into the package\n(`src/kernel_generated.jl`) so Julia’s precompilation turns them into real native\nmethods — there is no per-startup `Core.eval` of the kernel. What a plain start\n*can’t* avoid is Julia loading the package image and JIT-compiling the\nreader/printer/evaluator on their first call. A **sysimage** captures all of that\nas a native snapshot, so startup is dominated by process spin-up.\n\n`bin/shen` automatically uses `./ShenJulia.sys` if it is present. Controls:\n\n```bash\nSHEN_JULIA_SYSIMAGE=/path/to/ShenJulia.sys ./bin/shen ...   # explicit image\nSHEN_JULIA_NO_SYSIMAGE=1 ./bin/shen ...                      # force the slow source path\n```\n\n### Get a sysimage\n\n**Option A — download a prebuilt one** (recommended). Release assets are named\n`ShenJulia-\u003cos\u003e-\u003carch\u003e-julia\u003cver\u003e.sys`. Download the one matching your platform\n**and Julia version**, then drop it in the repo root as `ShenJulia.sys`:\n\n```bash\n# example for macOS arm64 on Julia 1.12\ncurl -L -o ShenJulia.sys \\\n  https://github.com/pyrex41/shen-julia/releases/latest/download/ShenJulia-macos-aarch64-julia1.12.sys\n./bin/shen --version    # now boots in ~1s\n```\n\n\u003e A sysimage is tied to the **OS, CPU architecture, and Julia minor version** it\n\u003e was built for. If the download doesn’t match yours, build locally (Option B).\n\u003e A mismatched image fails to load (or, for a too-aggressive CPU target, can\n\u003e crash with an illegal-instruction error) — that’s the cue to rebuild.\n\n**Option B — build locally** (a few minutes, significant RAM, one-time):\n\n```bash\njulia --project=. bin/build_sysimage.jl\n# writes ./ShenJulia.sys, tuned natively for THIS machine\n```\n\n---\n\n## Baking *your* program into a fast-start sysimage\n\nIf you have a Shen program you run often and want it to start in ~1 s with its\nown functions already native-compiled, bake a program-specific sysimage:\n\n```bash\njulia --project=. bin/build_app_sysimage.jl myprog.shen myprog.sys\n```\n\nThis loads `myprog.shen` at build time, exercises it, and snapshots the result.\nRun your program against it:\n\n```bash\nSHEN_JULIA_SYSIMAGE=myprog.sys ./bin/shen script myprog.shen\n# or call a specific entry point:\nSHEN_JULIA_SYSIMAGE=myprog.sys ./bin/shen eval -l myprog.shen -e \"(main)\"\n```\n\nFor most programs the **base** `ShenJulia.sys` is already enough: boot is ~1 s and\nloading your `.shen` on top is fast. Reach for a program-specific image only when\nyou want the program’s *own* functions precompiled too (tightest startup, e.g. a\nCLI tool invoked repeatedly).\n\nFor an even more self-contained artifact (a tree-shaken kernel slice + your\nprogram, optionally as its own sysimage), see the Ratatoskr builder\n`bin/ratatoskr-build.jl`.\n\n---\n\n## Status\n\n- **Kernel:** Shen **41.2** (`(version)` reports `\"41.2\"`).\n- **Tests:** official `tests/kerneltests.shen` passes **134/134** via\n  `julia --project=. bin/run_canonical.jl` (loads `harness.shen` +\n  `kerneltests.shen` exactly as upstream does).\n- **Performance** (vs `shen-cl`/SBCL, the reference; per-trial median):\n\n  | benchmark | shen-julia | shen-cl |\n  |-----------|-----------:|--------:|\n  | tak / fib / ack (compute) | 2.2 / 2.4 / 8.2 ms | 33 / 39 / 53 ms |\n  | iota 100k | ~16 ms | 16.5 ms |\n  | map / sum (allocation-heavy) | 1.25–1.78× cl | — |\n\n  Compute-bound code is several times faster than SBCL; the only place SBCL still\n  wins is allocation-heavy list code, because SBCL tags fixnums as immediates\n  while Julia heap-boxes integers stored in `Any`.\n\n## Building from source / for developers\n\nThe kernel is **baked ahead of time** — after changing any `klambda/*.kl` file or\nthe compiler’s codegen you must regenerate it:\n\n```bash\njulia --project=. bin/gen_kernel.jl    # regenerate src/kernel_generated.jl + kernel_*.jls\n# then bump the \"[baked-kernel guard vN]\" marker in src/Prims.jl (Julia does not\n# track the generated file as a precompile dependency), then rebuild the sysimage:\njulia --project=. bin/build_sysimage.jl\n```\n\nRepository layout:\n\n| Path | Role |\n|------|------|\n| `src/ShenJulia.jl` | Main module, `boot!`, `run_kl_string`, REPL |\n| `src/Runtime.jl` | Symbols, `NIL`/`Cons`/`AbsVector`, streams, KL reader |\n| `src/Compiler.jl` | KL → Julia codegen; `INLINE_PRIM` hot-path inlines |\n| `src/Prims.jl` | Host primitives, `APP`/`PARTIAL`, `eval_kl`, baked-kernel include |\n| `src/Boot.jl` | Kernel load (baked fast path + source fallback), `shen.initialise` |\n| `src/kernel_generated.jl` | **auto-generated** baked 41.2 kernel (do not edit) |\n| `bin/shen`, `bin/shen.jl` | CLI launcher |\n| `bin/gen_kernel.jl` | Ahead-of-time kernel generator |\n| `bin/build_sysimage.jl` | Base sysimage builder (honours `SHEN_SYSIMAGE_CPU_TARGET`) |\n| `bin/build_app_sysimage.jl` | Bake a user `.shen` into its own sysimage |\n| `bin/ratatoskr-build.jl` | Ratatoskr stage-2 standalone-artifact builder |\n| `bin/run_canonical.jl` | Run the official kerneltests harness (134/134) |\n| `klambda/` | Vendored Shen 41.2 kernel sources |\n| `tests/` | Official Shen test suite + sample programs |\n\n---\n\n## About Shen\n\nShen is [Mark Tarver’s](http://www.marktarver.com/) functional programming\nlanguage. This repository is a **port of its kernel**, intended for developers\nworking on Shen itself and for running Shen programs on the Julia runtime. For a\ngeneral-purpose environment, beginners should start at the\n[main website](https://shenlanguage.org) and the\n[mailing list](https://groups.google.com/forum/#!forum/qilang); other complete\nimplementations include the SBCL port and\n[Shen/Scheme](https://github.com/tizoc/shen-scheme).\n\nLanguage documentation: [shendoc](http://shenlanguage.org/shendoc.htm).\n\n神\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpyrex41%2Fshen-julia","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpyrex41%2Fshen-julia","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpyrex41%2Fshen-julia/lists"}