Compile Cargo project with zig as linker
Project description
cargo-zigbuild
🚀 Help me to become a full-time open-source developer by sponsoring me on GitHub
Compile Cargo project with zig as linker for easier cross compiling.
Installation
cargo install --locked cargo-zigbuild
You can also install it using pip which will also install ziglang
automatically:
pip install cargo-zigbuild
We also provide a Docker image which has macOS SDK pre-installed in addition to cargo-zigbuild and Rust, for example to build for x86_64 macOS:
docker run --rm -it -v $(pwd):/io -w /io messense/cargo-zigbuild \
cargo zigbuild --release --target x86_64-apple-darwin
Usage
- Install zig following the official documentation,
on macOS, Windows and Linux you can also install zig from PyPI via
pip3 install ziglang
- Install Rust target via rustup, for example,
rustup target add aarch64-unknown-linux-gnu
- 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:
cargo zigbuild --target aarch64-unknown-linux-gnu.2.17
[!NOTE] There are various caveats with the glibc version targeting feature:
- If you do not provide a
--target
, Zig is not used and the command effectively runs a regularcargo build
.- If you specify an invalid glibc version,
cargo zigbuild
will not relay the warning emitted fromzig 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 (upstreamzig 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.
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
- Currently only Linux and macOS targets are supported, other target platforms can be added if you can make it work, pull requests are welcome.
- Only current Rust stable and nightly versions are regularly tested on CI, other versions may not work.
Known upstream zig issues:
- zig cc: parse
-target
and-mcpu
/-march
/-mtune
flags according to clang: Some Rust targets aren't recognized byzig cc
, for examplearmv7-unknown-linux-gnueabihf
, workaround by using-mcpu=generic
and explicitly passing target features in #58 - ability to link against darwin frameworks (such as CoreFoundation) when cross compiling:
Set the
SDKROOT
environment variable to a macOS SDK path to workaround it - zig misses some
compiler_rt
functions that may lead to undefined symbol error for certain targets. See also: zig compiler-rt status. - CPU features are not passed to clang
License
This work is released under the MIT license. A copy of the license is provided in the LICENSE file.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distributions
Built Distributions
Hashes for cargo_zigbuild-0.19.3-py3-none-win_arm64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 3a9fe2e2e650855ed309d252bfe76230f16011232c10ce616935e74e3cdb2a5e |
|
MD5 | 7a380bc13bc46ab390c45136e030b4cf |
|
BLAKE2b-256 | 0921558875d917297513b6049d2ea2e91633024fb88d563f2dadb527ee16667b |
Hashes for cargo_zigbuild-0.19.3-py3-none-win_amd64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | dcb3fe77ea4a85a6b4c2ef11eb19d273ab3eed3dd2a4909b68dc530f002b39f7 |
|
MD5 | fcba16cd91f3c1f2b404f8e9fcfdfbe7 |
|
BLAKE2b-256 | 4cb523627b75298a54cfd8e67a05b1faa965362aa0961a2d50bb4c77cc0df40c |
Hashes for cargo_zigbuild-0.19.3-py3-none-win32.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 169ec405074eec3d53da8b58db07f816876ea3d83031eeab554ab65b72b16e2a |
|
MD5 | f5f07e3fe393dbad2a6b11923d88f35f |
|
BLAKE2b-256 | 67a39bface5111ced2c9b87a1d7a493bf0de26eb8c7478d4898b49631a416381 |
Hashes for cargo_zigbuild-0.19.3-py3-none-manylinux_2_17_armv7l.manylinux2014_armv7l.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | c2ac2b6880451ef68df6ab231e3b65d338d545f90e0cf3a1d7d5fc7654802705 |
|
MD5 | 3c033c0b8e7de50bc3ce15a397812581 |
|
BLAKE2b-256 | 730fac1c23842230ddbb6f4328bf07a946f7802e2f09dab1bd3acfcdc2190aff |
Hashes for cargo_zigbuild-0.19.3-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | b3546b1cc0ffc7bd500505fc26ee3d4653be7649e277886125d939d94d4813e2 |
|
MD5 | 408b9e4b43a5ed3a014db8eadc5cc794 |
|
BLAKE2b-256 | d7d2fcf280daf7cc9a249417a53d3f2adf0ede975b6d127bfd4e970f380e31ed |
Hashes for cargo_zigbuild-0.19.3-py3-none-manylinux_2_5_x86_64.manylinux1_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | ebbe8f3e6dc9feb1c735968fb6e20a7c7f7fe848d585d346b68180f1191c7932 |
|
MD5 | 63a4d53fa81bad73381603f4ac6c30e7 |
|
BLAKE2b-256 | 3eeea50e5f75a18fd1540faf3a8ea0e8c2a3613c629d395ea6269488f06e2655 |
Hashes for cargo_zigbuild-0.19.3-py3-none-manylinux_2_5_i686.manylinux1_i686.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | c0f21971dff97b4034ee630205c566dd7e3b7e85ff59a62de71a669cdb620ca2 |
|
MD5 | 7839cd51d325895697db7ed79f6fa51f |
|
BLAKE2b-256 | 5555f1f0b42404449e4abaa21e3904108959e36e50c97b764936c4a23e9771e2 |
Hashes for cargo_zigbuild-0.19.3-py3-none-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 24775c112037168f9c608416e759e0dfb354ec2849ad25c479f4f9a70092a774 |
|
MD5 | e2f8ce76dd892951b6d97b875a1f65be |
|
BLAKE2b-256 | c721768eef12bb7c0700b28197c01944c70bf84224b0879c995c73694045319b |