| Name | cargo-zigbuild JSON |
| Version |
0.19.6
JSON |
| download |
| home_page | None |
| Summary | Compile Cargo project with zig as linker |
| upload_time | 2024-12-16 01:06:38 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | None |
| license | MIT |
| keywords |
zig
cargo
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# cargo-zigbuild
[](https://github.com/rust-cross/cargo-zigbuild/actions?query=workflow%3ACI)
[](https://crates.io/crates/cargo-zigbuild)
[](https://docs.rs/cargo-zigbuild/)
[](https://pypi.org/project/cargo-zigbuild)
[](https://hub.docker.com/r/messense/cargo-zigbuild/)
> 🚀 Help me to become a full-time open-source developer by [sponsoring me on GitHub](https://github.com/sponsors/messense)
Compile Cargo project with [zig](https://github.com/ziglang/zig) as [linker](https://andrewkelley.me/post/zig-cc-powerful-drop-in-replacement-gcc-clang.html) for
[easier cross compiling](https://actually.fyi/posts/zig-makes-rust-cross-compilation-just-work/).
## Installation
```bash
cargo install --locked cargo-zigbuild
```
You can also install it using pip which will also install [`ziglang`](https://pypi.org/project/ziglang/) automatically:
```bash
pip install cargo-zigbuild
```
We also provide Docker images which has macOS SDK pre-installed in addition to cargo-zigbuild and Rust, for example to build for x86_64 macOS:
- Linux docker image ([ghcr.io](https://github.com/rust-cross/cargo-zigbuild/pkgs/container/cargo-zigbuild), [Docker Hub](https://hub.docker.com/r/messense/cargo-zigbuild)):
```bash
docker run --rm -it -v $(pwd):/io -w /io messense/cargo-zigbuild \
cargo zigbuild --release --target x86_64-apple-darwin
```
- Windows docker image ([ghcr.io](https://github.com/rust-cross/cargo-zigbuild/pkgs/container/cargo-zigbuild.windows), [Docker Hub](https://hub.docker.com/r/messense/cargo-zigbuild.windows)):
```powershell
docker run --rm -it -v ${pwd}:c:\io -w c:\io messense/cargo-zigbuild.windows `
cargo zigbuild --target x86_64-apple-darwin
```
> [!NOTE]
> Windows docker image can compile debug builds, but does NOT support `cargo build --release` for *-apple-darwin targets.
> You will get ```error: unable to run `strip`: program not found```. If you know a solution to this, please open an issue and/or PR.
[](https://repology.org/project/cargo-zigbuild/versions)
## Usage
1. Install [zig](https://ziglang.org/) following the [official documentation](https://ziglang.org/learn/getting-started/#installing-zig),
on macOS, Windows and Linux you can also install zig from PyPI via `pip3 install ziglang`
2. Install Rust target via rustup, for example, `rustup target add aarch64-unknown-linux-gnu`
3. Run `cargo zigbuild`, for example, `cargo zigbuild --target aarch64-unknown-linux-gnu`
### Specify glibc version
`cargo zigbuild` supports passing glibc version in `--target` option, for example,
to compile for glibc 2.17 with the `aarch64-unknown-linux-gnu` target:
```bash
cargo zigbuild --target aarch64-unknown-linux-gnu.2.17
```
> [!NOTE]
> There are [various caveats](https://github.com/rust-cross/cargo-zigbuild/issues/231#issuecomment-1983434802) with the glibc version targeting feature:
> - If you do not provide a `--target`, Zig is not used and the command effectively runs a regular `cargo build`.
> - If you specify an invalid glibc version, `cargo zigbuild` will not relay the warning emitted from `zig cc` about the fallback version selected.
> - This feature does not necessarily match the behaviour of dynamically linking to a specific version of glibc on the build host.
> - Version 2.32 can be specified, but runs on a host with only 2.31 available when it should instead abort with an error.
> - Meanwhile specifying 2.33 will correctly be detected as incompatible when run on a host with glibc 2.31.
> - Certain `RUSTFLAGS` like `-C linker` opt-out of using Zig, while `-L path/to/files` will have Zig ignore `-C target-feature=+crt-static`.
> - `-C target-feature=+crt-static` for statically linking to a glibc version is **not supported** (_upstream `zig cc` lacks support_)
### macOS universal2 target
`cargo zigbuild` supports a special `universal2-apple-darwin` target for building macOS universal2 binaries/libraries on Rust 1.64.0 and later.
```bash
rustup target add x86_64-apple-darwin
rustup target add aarch64-apple-darwin
cargo zigbuild --target universal2-apple-darwin
```
> **Note**
>
> Note that Cargo `--message-format` option doesn't work with universal2 target currently.
## Caveats
1. Currently only Linux and macOS targets are supported,
other target platforms can be added if you can make it work,
pull requests are welcome.
2. Only current Rust **stable** and **nightly** versions are regularly tested on CI, other versions may not work.
Known upstream zig [issues](https://github.com/ziglang/zig/labels/zig%20cc):
1. [zig cc: parse `-target` and `-mcpu`/`-march`/`-mtune` flags according to clang](https://github.com/ziglang/zig/issues/4911):
Some Rust targets aren't recognized by `zig cc`, for example `armv7-unknown-linux-gnueabihf`, workaround by using `-mcpu=generic` and
explicitly passing target features in [#58](https://github.com/rust-cross/cargo-zigbuild/pull/58)
2. [ability to link against darwin frameworks (such as CoreFoundation) when cross compiling](https://github.com/ziglang/zig/issues/1349):
Set the `SDKROOT` environment variable to a macOS SDK path to workaround it
3. [zig misses some `compiler_rt` functions](https://github.com/ziglang/zig/issues/1290) that may lead to undefined symbol error for certain
targets. See also: [zig compiler-rt status](https://github.com/ziglang/zig/blob/master/lib/compiler_rt/README.md).
4. [CPU features are not passed to clang](https://github.com/ziglang/zig/issues/10411)
## License
This work is released under the MIT license. A copy of the license is provided
in the [LICENSE](./LICENSE) file.
Raw data
{
"_id": null,
"home_page": null,
"name": "cargo-zigbuild",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "zig, cargo",
"author": null,
"author_email": null,
"download_url": null,
"platform": null,
"description": "# cargo-zigbuild\n\n[](https://github.com/rust-cross/cargo-zigbuild/actions?query=workflow%3ACI)\n[](https://crates.io/crates/cargo-zigbuild)\n[](https://docs.rs/cargo-zigbuild/)\n[](https://pypi.org/project/cargo-zigbuild)\n[](https://hub.docker.com/r/messense/cargo-zigbuild/)\n\n> \ud83d\ude80 Help me to become a full-time open-source developer by [sponsoring me on GitHub](https://github.com/sponsors/messense)\n\nCompile Cargo project with [zig](https://github.com/ziglang/zig) as [linker](https://andrewkelley.me/post/zig-cc-powerful-drop-in-replacement-gcc-clang.html) for\n[easier cross compiling](https://actually.fyi/posts/zig-makes-rust-cross-compilation-just-work/).\n\n## Installation\n\n```bash\ncargo install --locked cargo-zigbuild\n```\n\nYou can also install it using pip which will also install [`ziglang`](https://pypi.org/project/ziglang/) automatically:\n\n```bash\npip install cargo-zigbuild\n```\n\nWe also provide Docker images which has macOS SDK pre-installed in addition to cargo-zigbuild and Rust, for example to build for x86_64 macOS:\n\n- Linux docker image ([ghcr.io](https://github.com/rust-cross/cargo-zigbuild/pkgs/container/cargo-zigbuild), [Docker Hub](https://hub.docker.com/r/messense/cargo-zigbuild)):\n```bash\ndocker run --rm -it -v $(pwd):/io -w /io messense/cargo-zigbuild \\\n cargo zigbuild --release --target x86_64-apple-darwin\n```\n\n- Windows docker image ([ghcr.io](https://github.com/rust-cross/cargo-zigbuild/pkgs/container/cargo-zigbuild.windows), [Docker Hub](https://hub.docker.com/r/messense/cargo-zigbuild.windows)):\n```powershell\ndocker run --rm -it -v ${pwd}:c:\\io -w c:\\io messense/cargo-zigbuild.windows `\n cargo zigbuild --target x86_64-apple-darwin\n```\n> [!NOTE] \n> Windows docker image can compile debug builds, but does NOT support `cargo build --release` for *-apple-darwin targets.\n> You will get ```error: unable to run `strip`: program not found```. If you know a solution to this, please open an issue and/or PR.\n\n[](https://repology.org/project/cargo-zigbuild/versions)\n\n## Usage\n\n1. Install [zig](https://ziglang.org/) following the [official documentation](https://ziglang.org/learn/getting-started/#installing-zig),\non macOS, Windows and Linux you can also install zig from PyPI via `pip3 install ziglang`\n2. Install Rust target via rustup, for example, `rustup target add aarch64-unknown-linux-gnu`\n3. Run `cargo zigbuild`, for example, `cargo zigbuild --target aarch64-unknown-linux-gnu`\n\n### Specify glibc version\n\n`cargo zigbuild` supports passing glibc version in `--target` option, for example,\nto compile for glibc 2.17 with the `aarch64-unknown-linux-gnu` target:\n\n```bash\ncargo zigbuild --target aarch64-unknown-linux-gnu.2.17\n```\n\n> [!NOTE]\n> There are [various caveats](https://github.com/rust-cross/cargo-zigbuild/issues/231#issuecomment-1983434802) with the glibc version targeting feature:\n> - If you do not provide a `--target`, Zig is not used and the command effectively runs a regular `cargo build`.\n> - If you specify an invalid glibc version, `cargo zigbuild` will not relay the warning emitted from `zig cc` about the fallback version selected.\n> - This feature does not necessarily match the behaviour of dynamically linking to a specific version of glibc on the build host.\n> - Version 2.32 can be specified, but runs on a host with only 2.31 available when it should instead abort with an error.\n> - Meanwhile specifying 2.33 will correctly be detected as incompatible when run on a host with glibc 2.31.\n> - Certain `RUSTFLAGS` like `-C linker` opt-out of using Zig, while `-L path/to/files` will have Zig ignore `-C target-feature=+crt-static`.\n> - `-C target-feature=+crt-static` for statically linking to a glibc version is **not supported** (_upstream `zig cc` lacks support_)\n\n### macOS universal2 target\n\n`cargo zigbuild` supports a special `universal2-apple-darwin` target for building macOS universal2 binaries/libraries on Rust 1.64.0 and later.\n\n```bash\nrustup target add x86_64-apple-darwin\nrustup target add aarch64-apple-darwin\ncargo zigbuild --target universal2-apple-darwin\n```\n\n> **Note**\n>\n> Note that Cargo `--message-format` option doesn't work with universal2 target currently.\n\n## Caveats\n\n1. Currently only Linux and macOS targets are supported,\n other target platforms can be added if you can make it work,\n pull requests are welcome.\n2. Only current Rust **stable** and **nightly** versions are regularly tested on CI, other versions may not work.\n\nKnown upstream zig [issues](https://github.com/ziglang/zig/labels/zig%20cc):\n\n1. [zig cc: parse `-target` and `-mcpu`/`-march`/`-mtune` flags according to clang](https://github.com/ziglang/zig/issues/4911):\n Some Rust targets aren't recognized by `zig cc`, for example `armv7-unknown-linux-gnueabihf`, workaround by using `-mcpu=generic` and\n explicitly passing target features in [#58](https://github.com/rust-cross/cargo-zigbuild/pull/58)\n2. [ability to link against darwin frameworks (such as CoreFoundation) when cross compiling](https://github.com/ziglang/zig/issues/1349):\n Set the `SDKROOT` environment variable to a macOS SDK path to workaround it\n3. [zig misses some `compiler_rt` functions](https://github.com/ziglang/zig/issues/1290) that may lead to undefined symbol error for certain\n targets. See also: [zig compiler-rt status](https://github.com/ziglang/zig/blob/master/lib/compiler_rt/README.md).\n4. [CPU features are not passed to clang](https://github.com/ziglang/zig/issues/10411)\n\n## License\n\nThis work is released under the MIT license. A copy of the license is provided\nin the [LICENSE](./LICENSE) file.\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Compile Cargo project with zig as linker",
"version": "0.19.6",
"project_urls": {
"Source Code": "https://github.com/rust-cross/cargo-zigbuild"
},
"split_keywords": [
"zig",
" cargo"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "bd8c52383cac4d8b3307f9e9e5c05e1f222df60fa9871e7421331d30f766a7aa",
"md5": "4a80c5c47464d6bbb3ad66c07bab47fc",
"sha256": "c53d0120458cf27b54b05595941f6338054ff5f0e09cf43a93794f44ef41408e"
},
"downloads": -1,
"filename": "cargo_zigbuild-0.19.6-py3-none-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl",
"has_sig": false,
"md5_digest": "4a80c5c47464d6bbb3ad66c07bab47fc",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 2737258,
"upload_time": "2024-12-16T01:06:38",
"upload_time_iso_8601": "2024-12-16T01:06:38.726355Z",
"url": "https://files.pythonhosted.org/packages/bd/8c/52383cac4d8b3307f9e9e5c05e1f222df60fa9871e7421331d30f766a7aa/cargo_zigbuild-0.19.6-py3-none-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "58cf3df4a67dc2183b0f22844175620e090a9469eccabb4a50b47fe205701e55",
"md5": "c787390766450017b56e505b12321028",
"sha256": "c7d03733574d72232941ee926fb0b51aef96150ec78b1fbbf5ca44de26d66492"
},
"downloads": -1,
"filename": "cargo_zigbuild-0.19.6-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl",
"has_sig": false,
"md5_digest": "c787390766450017b56e505b12321028",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 1598291,
"upload_time": "2024-12-16T01:06:41",
"upload_time_iso_8601": "2024-12-16T01:06:41.822576Z",
"url": "https://files.pythonhosted.org/packages/58/cf/3df4a67dc2183b0f22844175620e090a9469eccabb4a50b47fe205701e55/cargo_zigbuild-0.19.6-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "4a858cb7e908ae84a87a5358476ffe85ce7c77aadede0a130384370f4d1444ef",
"md5": "87e616fed73faf51e892fea9485d15c2",
"sha256": "e9c5924128d7991d19f8f967d5354e85edd2bf26471a07cea6f88d753d5cdea4"
},
"downloads": -1,
"filename": "cargo_zigbuild-0.19.6-py3-none-manylinux_2_17_armv7l.manylinux2014_armv7l.whl",
"has_sig": false,
"md5_digest": "87e616fed73faf51e892fea9485d15c2",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 1533792,
"upload_time": "2024-12-16T01:06:44",
"upload_time_iso_8601": "2024-12-16T01:06:44.618898Z",
"url": "https://files.pythonhosted.org/packages/4a/85/8cb7e908ae84a87a5358476ffe85ce7c77aadede0a130384370f4d1444ef/cargo_zigbuild-0.19.6-py3-none-manylinux_2_17_armv7l.manylinux2014_armv7l.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "f28dde2a5fbf05d8ece0376b41ceee29eb92b0e0f6b581c7cd3d2891225f18d8",
"md5": "ab9f814af39c44591e9f05c5317510ef",
"sha256": "ef0fa7f2433be0391c521d2ce4d0a2d8bf7ab48ea02942ba076c406d70e4c6bf"
},
"downloads": -1,
"filename": "cargo_zigbuild-0.19.6-py3-none-manylinux_2_5_i686.manylinux1_i686.whl",
"has_sig": false,
"md5_digest": "ab9f814af39c44591e9f05c5317510ef",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 1661596,
"upload_time": "2024-12-16T01:06:47",
"upload_time_iso_8601": "2024-12-16T01:06:47.468967Z",
"url": "https://files.pythonhosted.org/packages/f2/8d/de2a5fbf05d8ece0376b41ceee29eb92b0e0f6b581c7cd3d2891225f18d8/cargo_zigbuild-0.19.6-py3-none-manylinux_2_5_i686.manylinux1_i686.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "42427e529cf15b8a498b58c0104410b1a1048e6037fc09ea68fcd87aa49eabc8",
"md5": "caa5e4e42f202feaf0ee4a6bcb7487fe",
"sha256": "cbe10baa78ff7e318953953362b927b087663671f6c1585c21db5ac4a832453c"
},
"downloads": -1,
"filename": "cargo_zigbuild-0.19.6-py3-none-manylinux_2_5_x86_64.manylinux1_x86_64.whl",
"has_sig": false,
"md5_digest": "caa5e4e42f202feaf0ee4a6bcb7487fe",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 1654588,
"upload_time": "2024-12-16T01:06:50",
"upload_time_iso_8601": "2024-12-16T01:06:50.883896Z",
"url": "https://files.pythonhosted.org/packages/42/42/7e529cf15b8a498b58c0104410b1a1048e6037fc09ea68fcd87aa49eabc8/cargo_zigbuild-0.19.6-py3-none-manylinux_2_5_x86_64.manylinux1_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "19d13f55efc8f65d7a5e5d631f86efacfdccfa2124511549bd1279cb0e513206",
"md5": "8409080e8474e7fcb177a52b22c329a6",
"sha256": "9194d33eed74a5bb1faccdce24538cb2e58802b2a3ccf191c6ff7d901b3ae8f4"
},
"downloads": -1,
"filename": "cargo_zigbuild-0.19.6-py3-none-win32.whl",
"has_sig": false,
"md5_digest": "8409080e8474e7fcb177a52b22c329a6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 1193620,
"upload_time": "2024-12-16T01:06:53",
"upload_time_iso_8601": "2024-12-16T01:06:53.519822Z",
"url": "https://files.pythonhosted.org/packages/19/d1/3f55efc8f65d7a5e5d631f86efacfdccfa2124511549bd1279cb0e513206/cargo_zigbuild-0.19.6-py3-none-win32.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "1dddf56ea5568fc8bb24c9d7d4821d62b5c9b59cf6804eca20659d0cc6d0e0e0",
"md5": "447c1ae905f877f4ef45e82470076b1a",
"sha256": "b8499ce8519239ed804a2a5684b70132558ae2a9abf5948ea8e500d4c0c196d6"
},
"downloads": -1,
"filename": "cargo_zigbuild-0.19.6-py3-none-win_amd64.whl",
"has_sig": false,
"md5_digest": "447c1ae905f877f4ef45e82470076b1a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 1311191,
"upload_time": "2024-12-16T01:06:56",
"upload_time_iso_8601": "2024-12-16T01:06:56.360664Z",
"url": "https://files.pythonhosted.org/packages/1d/dd/f56ea5568fc8bb24c9d7d4821d62b5c9b59cf6804eca20659d0cc6d0e0e0/cargo_zigbuild-0.19.6-py3-none-win_amd64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "2004c2b64ddec23785da2f6123564db936191e97d125785284eff860cbfd2a95",
"md5": "7a391a5f9d5fae6e14a8f9dce4f0b492",
"sha256": "c46567b45b2f7a97f9f15491c3df0c9416d0a03b6ed277ff0b98c409a6b41c5d"
},
"downloads": -1,
"filename": "cargo_zigbuild-0.19.6-py3-none-win_arm64.whl",
"has_sig": false,
"md5_digest": "7a391a5f9d5fae6e14a8f9dce4f0b492",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 1258710,
"upload_time": "2024-12-16T01:06:59",
"upload_time_iso_8601": "2024-12-16T01:06:59.002726Z",
"url": "https://files.pythonhosted.org/packages/20/04/c2b64ddec23785da2f6123564db936191e97d125785284eff860cbfd2a95/cargo_zigbuild-0.19.6-py3-none-win_arm64.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-16 01:06:38",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "rust-cross",
"github_project": "cargo-zigbuild",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "cargo-zigbuild"
}
