{"id":13472530,"url":"https://github.com/sunfishcode/mustang","last_synced_at":"2025-05-14T05:10:40.141Z","repository":{"id":37397187,"uuid":"403170516","full_name":"sunfishcode/mustang","owner":"sunfishcode","description":"Rust programs written entirely in Rust","archived":false,"fork":false,"pushed_at":"2025-04-30T22:49:51.000Z","size":996,"stargazers_count":871,"open_issues_count":2,"forks_count":23,"subscribers_count":14,"default_branch":"main","last_synced_at":"2025-05-08T00:09:22.249Z","etag":null,"topics":["rust"],"latest_commit_sha":null,"homepage":"","language":"Rust","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/sunfishcode.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE-APACHE","code_of_conduct":"CODE_OF_CONDUCT.md","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}},"created_at":"2021-09-04T22:53:17.000Z","updated_at":"2025-04-30T22:49:54.000Z","dependencies_parsed_at":"2023-10-02T18:56:20.532Z","dependency_job_id":"44e5628e-207f-449b-a459-66f1b4329c48","html_url":"https://github.com/sunfishcode/mustang","commit_stats":{"total_commits":552,"total_committers":11,"mean_commits":50.18181818181818,"dds":0.08152173913043481,"last_synced_commit":"5b3fc96c54e4c49cf1f0ba2dfd9f1ef17357403d"},"previous_names":[],"tags_count":133,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sunfishcode%2Fmustang","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sunfishcode%2Fmustang/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sunfishcode%2Fmustang/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sunfishcode%2Fmustang/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sunfishcode","download_url":"https://codeload.github.com/sunfishcode/mustang/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254076850,"owners_count":22010611,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["rust"],"created_at":"2024-07-31T16:00:55.460Z","updated_at":"2025-05-14T05:10:40.092Z","avatar_url":"https://github.com/sunfishcode.png","language":"Rust","funding_links":[],"categories":["Rust"],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003ch1\u003eMustang\u003c/h1\u003e\n\n  \u003cp\u003e\n    \u003cstrong\u003eRust programs written entirely in Rust\u003c/strong\u003e\n  \u003c/p\u003e\n\n  \u003cp\u003e\n    \u003ca href=\"https://github.com/sunfishcode/mustang/actions?query=workflow%3ACI\"\u003e\u003cimg src=\"https://github.com/sunfishcode/mustang/workflows/CI/badge.svg\" alt=\"Github Actions CI Status\" /\u003e\u003c/a\u003e\n    \u003ca href=\"https://bytecodealliance.zulipchat.com/#narrow/stream/206238-general\"\u003e\u003cimg src=\"https://img.shields.io/badge/zulip-join_chat-brightgreen.svg\" alt=\"zulip chat\" /\u003e\u003c/a\u003e\n    \u003ca href=\"https://crates.io/crates/mustang\"\u003e\u003cimg src=\"https://img.shields.io/crates/v/mustang.svg\" alt=\"crates.io page\" /\u003e\u003c/a\u003e\n    \u003ca href=\"https://docs.rs/mustang\"\u003e\u003cimg src=\"https://docs.rs/mustang/badge.svg\" alt=\"docs.rs docs\" /\u003e\u003c/a\u003e\n  \u003c/p\u003e\n\u003c/div\u003e\n\nMustang is a system for building programs built entirely in Rust, meaning they\ndo not depend on any part of libc or crt1.o, and do not link in any C code.\n\nWhy? For fun! And to exercise some components that have other purposes (such as\n[`rustix`], [`origin`], [`c-scape`], and [`c-gull`]) but which happen to also be\npart of what's needed to do what Mustang is doing. And in the future, possibly\nalso for experimenting with new kinds of platform ABIs.\n\nMustang currently runs on Rust Nightly on Linux on x86-64, x86, aarch64, and\nriscv64. It aims to support all Linux versions [supported by Rust], though\nat this time it's only tested on relatively recent versions. It's complete\nenough to run:\n\n - [ripgrep](https://github.com/sunfishcode/ripgrep/tree/mustang)\n - [coreutils](https://github.com/sunfishcode/coreutils/tree/mustang),\n   including the \"unix\" feature set\n - [async-std](https://github.com/sunfishcode/tide/tree/mustang)\n - [tokio](https://github.com/sunfishcode/tokio/tree/mustang)\n - [bat](https://github.com/sunfishcode/bat/tree/mustang), including git\n   support with libgit2\n - [cargo-watch](https://github.com/sunfishcode/cargo-watch/tree/mustang)\n\nMustang isn't about making anything safer, for the foreseeable future. The\nmajor libc implementations are extraordinarily well tested and mature. Mustang\nfor its part is experimental and has lots of `unsafe`.\n\n[`origin`]: https://github.com/sunfishcode/origin/\n[Rust-idiomatic]: https://docs.rs/origin/latest/origin/\n[`c-scape`]: https://github.com/sunfishcode/c-ward/tree/main/c-scape\n[`c-gull`]: https://github.com/sunfishcode/c-ward/tree/main/c-gull\n[`mustang`]: https://github.com/sunfishcode/mustang/tree/main/mustang\n[supported by Rust]: https://doc.rust-lang.org/nightly/rustc/platform-support.html\n\n## Usage\n\nTo use it, first install rust-src, which is needed by `-Z build-std`:\n\n```console\n$ rustup component add rust-src --toolchain nightly\n```\n\nThen, set the `RUST_TARGET_PATH` environment variable to a path to the\n`mustang/target-specs` directory, so that you can name `mustang` targets with\n`--target=…`. For example, within a mustang repo:\n\n```console\n$ export RUST_TARGET_PATH=\"$PWD/mustang/target-specs\"\n```\n\nThen, in your own crate, add a dependency on `mustang`:\n\n```toml\n[dependencies]\nmustang = \"\u003ccurrent version\u003e\"\n```\n\nAnd add a `mustang::can_run_this!();` to your top-level module (eg. main.rs).\nThis does nothing in non-`mustang`-target builds, but in `mustang`-target\nbuilds arranges for `mustang`'s libraries to be linked in.\n\n```rust,no_run\nmustang::can_run_this!();\n```\n\nThen, compile with Rust nightly, using `-Z build-std` and\n`--target=\u003cmustang-target\u003e`. For example:\n\n```console\n$ cargo +nightly run --quiet -Z build-std --target=x86_64-mustang-linux-gnu --example hello\nHello, world!\n$\n```\n\nThat's a Rust program built entirely from Rust saying \"Hello, world!\"!\n\nFor more detail, mustang has an `env_logger` feature, which you can enable, and set\n`RUST_LOG` to see various pieces of mustang in action:\n```console\n$ RUST_LOG=trace cargo +nightly run --quiet -Z build-std --target=x86_64-mustang-linux-gnu --example hello --features log,env_logger\n[2021-06-28T06:28:31Z TRACE origin::program] Program started\n[2021-06-28T06:28:31Z TRACE origin::threads] Main Thread[916066] initialized\n[2021-06-28T06:28:31Z TRACE origin::program] Calling `.init_array`-registered function `0x5555558fb480(1, 0x7fffffffdb98, 0x7fffffffdba8)`\n[2021-06-28T06:28:31Z TRACE origin::program] Calling `main(1, 0x7fffffffdb98, 0x7fffffffdba8)`\nHello, world!\n[2021-06-28T06:28:31Z TRACE origin::program] `main` returned `0`\n[2021-06-28T06:28:31Z TRACE origin::program] Program exiting\n$\n```\n\nA simple way to check for uses of libc functions is to use `nm -u`, since\nthe above commands are configured to link libc dynamically. If `mustang` has\neverything covered, there should be no output:\n\n```console\n$ nm -u target/x86_64-mustang-linux-gnu/debug/examples/hello\n$\n```\n\n## C Runtime interop\n\nTo compile C code with a `*-mustang-*` target, you may need to\n[tell the `cc` crate which C compiler to use]; for example, for `i686-mustang-linux-gnu`,\nset the environment variable `CC_i686-mustang-linux-gnu` to\n`i686-linux-gnu-gcc`.\n\n[tell the `cc` crate which C compiler to use]: https://github.com/alexcrichton/cc-rs#external-configuration-via-environment-variables\n\n## panic = \"abort\"\n\nWhen using `panic = \"abort\"` in your Cargo.toml, change the `-Z build-std` to\n`-Z build-std=panic_abort,std`. See [here] for background.\n\n[here]: https://github.com/rust-lang/wg-cargo-std-aware/issues/29\n\n## Known Limitations\n\nKnown limitations in `mustang` include:\n\n - Dynamic linking isn't implemented yet.\n - Many libc C functions that aren't typically needed by most Rust programs\n   aren't implemented yet.\n\n## Alternatives\n\n[Eyra] uses the same underlying libraries as Mustang, but doesn't use a custom\ntarget, and doesn't need `-Z build-std`.\n\nUsing [Origin] directly is another option; there are [examples] showing how\nto do this. Using origin directly can produce very small binary sizes; the\n`tiny` example can produce a 408-byte executable. The big downside of using\nOrigin directly is that it doesn't provide a `std` implementation.\n\n[Origin Studio] is a demo of what a `std`-like environment on top of Origin\nmight look like. It has things like `println!`, but it's also currently lots\nof features, such as `File`.\n\n[Eyra]: https://github.com/sunfishcode/eyra#readme\n[Origin]: https://github.com/sunfishcode/origin#readme\n[examples]: https://github.com/sunfishcode/origin/tree/main/example-crates\n[Origin Studio]: https://github.com/sunfishcode/origin-studio#readme\n\n## Background\n\nMustang is partly inspired by similar functionality in [`steed`], but a few\nthings are different. cargo's [build-std] is now available, which makes it\nmuch easier to work with custom targets. And Mustang is starting with the\napproach of starting by replacing libc interfaces and using `std` as-is,\nrather than reimplementing `std`. This is likely to evolve, but whatever we\ndo, a high-level goal of Mustang is to avoid ever having to reimplement `std`.\n\nWhere does `mustang` go from here? Will it support feature X, platform Y, or\nuse case Z? If `origin` can do program startup in Rust, and [`rustix`] can do\nsystem calls in Rust, what does it all mean?\n\nAnd could `mustang` eventually support new ABIs that aren't limited to passing\nC-style `argc`/`argv`(/`envp`) convention, allowing new kinds of program\nargument passing?\n\nLet's find out! Come say hi in the [chat] or an [issue].\n\n## How does one port `mustang` to a new architecture?\n\n - Port [`rustix`] to the architecture, adding assembly sequences for\n   making syscalls.\n - Port [`origin`] to the architecture, adding assembly sequences for\n   program and thread primitives.\n - Create a target file in `mustang/target-specs`, by first following\n   [these instructions] to generate a specification of a built-in target,\n   and then:\n     - change `dynamic-linking` to false\n     - add `-nostartfiles` and `-Wl,--undefined=_Unwind_Backtrace` to\n       pre-link-args\n     - add `\"vendor\": \"mustang\"`\n   See other targets in the `mustang/target-specs` directory for examples.\n - Compile some of the programs in the `examples` directory, using\n   the new target. Try `nm -u` on the binaries to check for undefined\n   symbols which need to be implemented.\n - Add the architecture to tests/tests.rs.\n - Add CI testing to .github/workflows/main.yml, by copying what's done\n   for other architectures.\n\n## How does one port `mustang` to a new OS?\n\nOne probably needs to do similar things as for a new architecture, and also\nwrite a new `origin::rust` implementation to handle the OS's convention for\narguments, environment variables, and initialization functions.\n\n## Using mustang in non-mustang programs\n\nIn non-`*-mustang-*` targets, importing this crate and using the\n`mustang::can_run_this!()` macro has no effect, does not depend on nightly\nRust, and has no extra dependencies.\n\nSee the [mustang-example] example for more details.\n\n## Similar crates\n\nc-scape has some similarities to [relibc], but has a different focus. Relibc is\naiming to be a complete libc replacement, while c-scape is just aiming to cover\nthe things used by Rust's `std` and popular crates. Some parts of Relibc are\nimplemented in C, while c-scape is implemented entirely in Rust.\n\nc-scape is also similar to [steed]. See the [Background] for details.\n\nThe most significant thing that makes c-scape unique though is its design as a\nset of wrappers around Rust crates with Rust interfaces. C ABI compatibility is\nuseful for getting existing code working, but once things are working, we can\nsimplify and optimize by changing code to call into the Rust interfaces\ndirectly. This can eliminate many uses of raw pointers and C-style\nNUL-terminated strings, so it can be much safer.\n\nOther similar projects are [tiny-std] and [veneer]. Similar to steed, they\ncontain their own implementations of std.\n\n[relibc]: https://gitlab.redox-os.org/redox-os/relibc/\n[steed]: https://github.com/japaric/steed\n[tiny-std]: https://github.com/MarcusGrass/tiny-std\n[veneer]: https://crates.io/crates/veneer\n[`steed`]: https://github.com/japaric/steed\n[build-std]: https://doc.rust-lang.org/cargo/reference/unstable.html#build-std\n[Rust itself already does this]: https://github.com/rust-lang/rust/blob/6bed1f0bc3cc50c10aab26d5f94b16a00776b8a5/library/std/src/sys/unix/mod.rs#L71\n[`rustix`]: https://github.com/bytecodealliance/rustix#readme\n[`origin`]: https://github.com/sunfishcode/origin#readme\n[chat]: https://bytecodealliance.zulipchat.com/#narrow/stream/206238-general\n[issue]: https://github.com/sunfishcode/mustang/issues\n[these instructions]: https://docs.rust-embedded.org/embedonomicon/custom-target.html#fill-the-target-file\n[Background]: #background\n[mustang-example]: https://github.com/sunfishcode/mustang/blob/main/example-crates/mustang-example/README.md\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsunfishcode%2Fmustang","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsunfishcode%2Fmustang","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsunfishcode%2Fmustang/lists"}