{"id":50335319,"url":"https://github.com/bdombro/shebangsy","last_synced_at":"2026-05-29T13:01:47.600Z","repository":{"id":352405098,"uuid":"1213704787","full_name":"bdombro/shebangsy","owner":"bdombro","description":"A #!shebang for single-file apps in C++, Go, Mojo, Nim, Python 3, Rust, and Swift","archived":false,"fork":false,"pushed_at":"2026-04-19T12:07:26.000Z","size":1750,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-19T13:26:02.615Z","etag":null,"topics":["cpp","go","mojo","nim","python","rust","shebang","swift"],"latest_commit_sha":null,"homepage":"","language":"Nim","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/bdombro.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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":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-04-17T17:09:46.000Z","updated_at":"2026-04-19T12:07:29.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/bdombro/shebangsy","commit_stats":null,"previous_names":["bdombro/shebangsy"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/bdombro/shebangsy","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bdombro%2Fshebangsy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bdombro%2Fshebangsy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bdombro%2Fshebangsy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bdombro%2Fshebangsy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bdombro","download_url":"https://codeload.github.com/bdombro/shebangsy/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bdombro%2Fshebangsy/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33652986,"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-05-29T02:00:06.066Z","response_time":107,"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":["cpp","go","mojo","nim","python","rust","shebang","swift"],"created_at":"2026-05-29T13:01:46.619Z","updated_at":"2026-05-29T13:01:47.568Z","avatar_url":"https://github.com/bdombro.png","language":"Nim","funding_links":[],"categories":[],"sub_categories":[],"readme":"```\n   /$$ /$$   /$$                    \n  / $$/ $$  | $$                    \n /$$$$$$$$$$| $$  /$$$$$$$ /$$   /$$\n|   $$  $$_/| $$ /$$_____/| $$  | $$\n /$$$$$$$$$$|__/|  $$$$$$ | $$  | $$\n|_  $$  $$_/     \\____  $$| $$  | $$\n  | $$| $$   /$$ /$$$$$$$/|  $$$$$$$\n  |__/|__/  |__/|_______/  \\____  $$\n                           /$$  | $$\n                          |  $$$$$$/\n                           \\______/ \n```\n\u003c!-- Big money NE - https://patorjk.com/software/taag/#p=testall\u0026f=Bulbhead\u0026t=shebangsy\u0026x=none\u0026v=4\u0026h=4\u0026w=80\u0026we=false\u003e --\u003e\n\n# Shebangsy\n\n**Shebangsy** (also written `#!sy`) runs single-file scripts in **C++, Go, Mojo, Nim, Python 3, Rust, and Swift**. You add a shebang, mark the file executable, and run it like any other program. Dependencies and build flags live in small `#!` directives at the top of the file, so you can pin versions without maintaining a separate project tree for every script.\n\nOn a warm cache hit, overhead versus a pre-built binary is on the order of **~10 ms**—enough for interactive use, including shell completions.\n\n**Platforms:** macOS and Linux (POSIX). Windows is not supported.\n\n## Quick start\n\n1. Put **`shebangsy` on your `PATH`** (see [Install](#install)).\n2. Start the file with `#!/usr/bin/env -S shebangsy \u003clanguage\u003e`.\n3. Run `chmod +x` on the script and execute it.\n\nExample: save as `gonum-hello.go`, then run it.\n\n```go\n#!/usr/bin/env -S shebangsy go\n#!requires: gonum.org/v1/gonum\n\npackage main\n\nimport (\n\t\"fmt\"\n\t\"gonum.org/v1/gonum/mat\"\n)\n\nfunc main() {\n\tu := mat.NewVecDense(3, []float64{1, 2, 3})\n\tv := mat.NewVecDense(3, []float64{4, 5, 6})\n\tfmt.Println(\"u · v =\", mat.Dot(u, v))\n}\n```\n\n```sh\nchmod +x gonum-hello.go\n./gonum-hello.go   # first run: compile, then execute\n./gonum-hello.go   # warm cache: run cached binary\n```\n\nMore samples live under [`examples/`](./examples).\n\n## How it works\n\nThe first time you run a script, shebangsy compiles (or materializes) it into a cache under `~/.cache/shebangsy`. Later runs compare the source file’s **size and modification time** to that cache entry. When both still match the cached entry, the cached artifact runs immediately; any change to size or mtime (including `touch` without editing) invalidates the entry and shebangsy rebuilds. Directive lines (`#!requires:`, `#!flags:`) are stripped before the compiler sees the source.\n\n## Command line\n\nWithout a shebang, you can invoke the same pipeline explicitly:\n\n```text\nshebangsy \u003clanguage\u003e \u003cscript\u003e [...script args]\n```\n\n## Install\n\n**Releases:** prebuilt binaries are on the [releases](https://github.com/bdombro/shebangsy/releases) page. You can copy them to your path (e.g. `~/.local/bin`).\n\n```sh\ncurl -sSL https://api.github.com/repos/bdombro/shebangsy/releases/latest | grep -Eo 'https://[^\"]*aarch64-apple-darwin[^\"]*\\.zip' | head -1 | xargs curl -sSL -o shebangsy.zip\nunzip -o shebangsy.zip \u0026\u0026 chmod +x shebangsy\nmv shebangsy ~/.local/bin/\nrm shebangsy.zip\n```\n\nFrom a clone of this repository:\n\n```sh\njust install\n# or: ./scripts/install.sh\n```\n\nThat builds with Nimble and installs **`shebangsy`** to **`~/.nimble/bin`**. Ensure that directory is on your **`PATH`** before running.\n\nPre-built archives (macOS host and Linux glibc) are produced under **`dist/`** when you run:\n\n```sh\njust build-cross\n# or: ./scripts/build-cross.sh\n```\n\nThe install script also clears existing cache files under `~/.cache/shebangsy` after a successful install.\n\n## Cache\n\nArtifacts and shared workspaces live under **`~/.cache/shebangsy`**. You normally do not need to touch this directory; changing the script’s size or mtime invalidates its entry.\n\n**When to clear manually:** For example, after changing Swift dependency versions in a shared SwiftPM workspace, or if you want a completely clean slate, remove the cache directory:\n\n```sh\nrm -rf ~/.cache/shebangsy\n```\n\nThere is no separate `cache-clear` subcommand; deleting that path is the supported reset.\n\n## Benchmark\n\n### Results\n\nMean end-to-end time for small “hello” style programs, averaged over benchmark runs. The chart compares shebangsy to running a compiled `bin` in the same language and to other runners where applicable.\n\nIn short, shebangsy is in the same ballpark as alternatives, with roughly **~10 ms** overhead versus a direct binary on warm paths.\n\n```mermaid\n---\nconfig:\n  themeVariables:\n    xyChart:\n      backgroundColor: \"#e8eaed\"\n      plotColorPalette: \"#1d4ed8, #1d4ed8, #15803d, #15803d, #15803d, #15803d, #a16207, #a16207, #7c3aed, #7c3aed, #b91c1c, #b91c1c, #b91c1c, #0e7490, #0e7490, #4338ca, #4338ca, #4338ca\"\n      titleColor: \"#111318\"\n      xAxisLabelColor: \"#2d3139\"\n      yAxisLabelColor: \"#2d3139\"\n      xAxisTitleColor: \"#1a1d24\"\n      yAxisTitleColor: \"#1a1d24\"\n      xAxisLineColor: \"#9aa0ab\"\n      yAxisLineColor: \"#9aa0ab\"\n      xAxisTickColor: \"#5c6370\"\n      yAxisTickColor: \"#5c6370\"\n---\nxychart-beta horizontal\n    title \"Mean time (ms) per app — all time\"\n    x-axis [\"cpp/bin\", \"cpp/shebangsy.cpp\", \"go/bin\", \"go/shebangsy.go\", \"go/gorun.go\", \"go/scriptisto.go\", \"mojo/bin\", \"mojo/shebangsy.mojo\", \"nim/bin\", \"nim/shebangsy.nim\", \"python/bin\", \"python/shebangsy.py\", \"python/uv.py\", \"rust/bin\", \"rust/shebangsy.rs\", \"swift/bin\", \"swift/shebangsy.swift\", \"swift/swift_sh.swift\"]\n    y-axis \"ms\" 0 --\u003e 80\n    bar [5.8, 16.3, 6.6, 18.0, 18.6, 18.8, 10.8, 22.0, 6.1, 17.8, 16.5, 30.3, 54.3, 6.1, 18.1, 7.0, 17.9, 80.0]\n```\n\nSee [`docs/contributing.md`](./docs/contributing.md#running-the-benchmark) for how to run the benchmark and [`benches-report.md`](./benches-report.md) for more charts.\n\n## Documentation\n\n- **[Language reference](docs/language-reference.md)** — `#!requires:`, `#!flags:`, and per-language behavior.\n- **[Contributing](docs/contributing.md)** — build, test, editor tips, architecture, cache model, benchmarks.\n- **[Adding a language](docs/adding-a-language.md)** — registration checklist and backend contract.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbdombro%2Fshebangsy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbdombro%2Fshebangsy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbdombro%2Fshebangsy/lists"}