From 8f95079cfc36387c3f0b792b1c8c157f67c5be19 Mon Sep 17 00:00:00 2001 From: Ulrich Weigand Date: Mon, 18 Nov 2024 19:43:04 +0100 Subject: [PATCH] Document s390x-unknown-linux targets This adds documentation for the following existing targets: s390x-unknown-linux-gnu (Tier 2 with host tools) s390x-unknown-linux-musl (Tier 3) I volunteer as maintainer for these targets going forward. Signed-off-by: Ulrich Weigand --- src/doc/rustc/src/SUMMARY.md | 2 + src/doc/rustc/src/platform-support.md | 4 +- .../s390x-unknown-linux-gnu.md | 112 ++++++++++++++++++ .../s390x-unknown-linux-musl.md | 83 +++++++++++++ 4 files changed, 199 insertions(+), 2 deletions(-) create mode 100644 src/doc/rustc/src/platform-support/s390x-unknown-linux-gnu.md create mode 100644 src/doc/rustc/src/platform-support/s390x-unknown-linux-musl.md diff --git a/src/doc/rustc/src/SUMMARY.md b/src/doc/rustc/src/SUMMARY.md index 18f76ac6fe0cf..f3d8a4edd6cd4 100644 --- a/src/doc/rustc/src/SUMMARY.md +++ b/src/doc/rustc/src/SUMMARY.md @@ -72,6 +72,8 @@ - [riscv32imac-unknown-xous-elf](platform-support/riscv32imac-unknown-xous-elf.md) - [riscv64gc-unknown-linux-gnu](platform-support/riscv64gc-unknown-linux-gnu.md) - [riscv64gc-unknown-linux-musl](platform-support/riscv64gc-unknown-linux-musl.md) + - [s390x-unknown-linux-gnu](platform-support/s390x-unknown-linux-gnu.md) + - [s390x-unknown-linux-musl](platform-support/s390x-unknown-linux-musl.md) - [sparc-unknown-none-elf](./platform-support/sparc-unknown-none-elf.md) - [*-pc-windows-gnullvm](platform-support/pc-windows-gnullvm.md) - [\*-nto-qnx-\*](platform-support/nto-qnx.md) diff --git a/src/doc/rustc/src/platform-support.md b/src/doc/rustc/src/platform-support.md index 500eaafb63f66..243cb3b2fc832 100644 --- a/src/doc/rustc/src/platform-support.md +++ b/src/doc/rustc/src/platform-support.md @@ -99,7 +99,7 @@ target | notes `powerpc64le-unknown-linux-gnu` | PPC64LE Linux (kernel 3.10, glibc 2.17) [`riscv64gc-unknown-linux-gnu`](platform-support/riscv64gc-unknown-linux-gnu.md) | RISC-V Linux (kernel 4.20, glibc 2.29) [`riscv64gc-unknown-linux-musl`](platform-support/riscv64gc-unknown-linux-musl.md) | RISC-V Linux (kernel 4.20, musl 1.2.3) -`s390x-unknown-linux-gnu` | S390x Linux (kernel 3.2, glibc 2.17) +[`s390x-unknown-linux-gnu`](platform-support/s390x-unknown-linux-gnu.md) | S390x Linux (kernel 3.2, glibc 2.17) `x86_64-unknown-freebsd` | 64-bit FreeBSD `x86_64-unknown-illumos` | illumos `x86_64-unknown-linux-musl` | 64-bit Linux with musl 1.2.3 @@ -367,7 +367,7 @@ target | std | host | notes [`riscv64gc-unknown-openbsd`](platform-support/openbsd.md) | ✓ | ✓ | OpenBSD/riscv64 [`riscv64-linux-android`](platform-support/android.md) | | | RISC-V 64-bit Android [`riscv64-wrs-vxworks`](platform-support/vxworks.md) | ✓ | | -`s390x-unknown-linux-musl` | | | S390x Linux (kernel 3.2, musl 1.2.3) +[`s390x-unknown-linux-musl`](platform-support/s390x-unknown-linux-musl.md) | | | S390x Linux (kernel 3.2, musl 1.2.3) `sparc-unknown-linux-gnu` | ✓ | | 32-bit SPARC Linux [`sparc-unknown-none-elf`](./platform-support/sparc-unknown-none-elf.md) | * | | Bare 32-bit SPARC V7+ [`sparc64-unknown-netbsd`](platform-support/netbsd.md) | ✓ | ✓ | NetBSD/sparc64 diff --git a/src/doc/rustc/src/platform-support/s390x-unknown-linux-gnu.md b/src/doc/rustc/src/platform-support/s390x-unknown-linux-gnu.md new file mode 100644 index 0000000000000..b514a254e2708 --- /dev/null +++ b/src/doc/rustc/src/platform-support/s390x-unknown-linux-gnu.md @@ -0,0 +1,112 @@ +# `s390x-unknown-linux-gnu` + +**Tier: 2 (with Host Tools)** + +IBM z/Architecture (s390x) targets (including IBM Z and LinuxONE) running Linux. + +## Target maintainers + +- Ulrich Weigand, , [@uweigand](https://github.com/uweigand) + +## Requirements + +This target requires: + +* Linux Kernel version 3.2 or later +* glibc 2.17 or later + +Code generated by the target uses the z/Architecture ISA assuming a minimum +architecture level of z10 (Eighth Edition of the z/Architecture Principles +of Operation), and is compliant with the s390x ELF ABI. + +Reference material: + +* [z/Architecture Principles of Operation][s390x-isa] +* [z/Architecture ELF Application Binary Interface][s390x-abi] + +[s390x-isa]: https://publibfp.dhe.ibm.com/epubs/pdf/a227832d.pdf +[s390x-abi]: https://github.com/IBM/s390x-abi + +## Building the target + +This target is distributed through `rustup`, and otherwise requires no +special configuration. + +If you need to build your own Rust for some reason though, the target can be +enabled in `config.toml`. For example: + +```toml +[build] +target = ["s390x-unknown-linux-gnu"] +``` + +## Building Rust programs + +On a s390x Linux host, the `s390x-unknown-linux-gnu` target should be +automatically installed and used by default. + +On a non-s390x host, add the target: + +```bash +rustup target add s390x-unknown-linux-gnu +``` + +Then cross compile crates with: + +```bash +cargo build --target s390x-unknown-linux-gnu +``` + +## Testing + +There are no special requirements for testing and running the target. +For testing cross builds on the host, please refer to the "Cross-compilation +toolchains and C code" section below. + +## Cross-compilation toolchains and C code + +Rust code built using the target is compatible with C code compiled with +GCC or Clang using the `s390x-unknown-linux-gnu` target triple (via either +native or cross-compilation). + +On Ubuntu, a s390x cross-toolchain can be installed with: + +```bash +apt install gcc-s390x-linux-gnu g++-s390x-linux-gnu libc6-dev-s390x-cross +``` + +Depending on your system, you may need to configure the target to use the GNU +GCC linker. To use it, add the following to your `.cargo/config.toml`: + +```toml +[target.s390x-unknown-linux-gnu] +linker = "s390x-linux-gnu-gcc" +``` + +If your `s390x-linux-gnu-*` toolchain is not in your `PATH` you may need to +configure additional settings: + +```toml +[target.s390x-unknown-linux-gnu] +# Adjust the paths to point at your toolchain +cc = "/TOOLCHAIN_PATH/bin/s390x-linux-gnu-gcc" +cxx = "/TOOLCHAIN_PATH/bin/s390x-linux-gnu-g++" +ar = "/TOOLCHAIN_PATH/bin/s390x-linux-gnu-ar" +ranlib = "/TOOLCHAIN_PATH/bin/s390x-linux-gnu-ranlib" +linker = "/TOOLCHAIN_PATH/bin/s390x-linux-gnu-gcc" +``` + +To test cross compiled binaries on a non-s390x host, you can use +[`qemu`](https://www.qemu.org/docs/master/system/target-s390x.html). +On Ubuntu, a s390x emulator can be obtained with: + +```bash +apt install qemu-system-s390x +``` + +Then, in `.cargo/config.toml` set the `runner`: + +```toml +[target.s390x-unknown-linux-gnu] +runner = "qemu-s390x-static -L /usr/s390x-linux-gnu" +``` diff --git a/src/doc/rustc/src/platform-support/s390x-unknown-linux-musl.md b/src/doc/rustc/src/platform-support/s390x-unknown-linux-musl.md new file mode 100644 index 0000000000000..e00f8db7f8e1b --- /dev/null +++ b/src/doc/rustc/src/platform-support/s390x-unknown-linux-musl.md @@ -0,0 +1,83 @@ +# `s390x-unknown-linux-musl` + +**Tier: 3** + +IBM z/Architecture (s390x) targets (including IBM Z and LinuxONE) running Linux. + +## Target maintainers + +- Ulrich Weigand, , [@uweigand](https://github.com/uweigand) + +## Requirements + +This target requires: + +* Linux Kernel version 3.2 or later +* musl 1.2.3 or later + +Code generated by the target uses the z/Architecture ISA assuming a minimum +architecture level of z10 (Eighth Edition of the z/Architecture Principles +of Operation), and is compliant with the s390x ELF ABI. + +Reference material: + +* [z/Architecture Principles of Operation][s390x-isa] +* [z/Architecture ELF Application Binary Interface][s390x-abi] + +[s390x-isa]: https://publibfp.dhe.ibm.com/epubs/pdf/a227832d.pdf +[s390x-abi]: https://github.com/IBM/s390x-abi + +## Building the target + +Because it is Tier 3, Rust does not yet ship pre-compiled artifacts for this +target. + +Therefore, you can build Rust with support for the target by adding it to the +target list in `config.toml`, a sample configuration is shown below. + +```toml +[build] +target = ["s390x-unknown-linux-musl"] +``` + +## Building Rust programs + +Rust does not yet ship pre-compiled artifacts for this target. To compile for +this target, you will first need to build Rust with the target enabled (see +"Building the target" above). + +## Testing + +There are no special requirements for testing and running the target. +For testing cross builds on the host, please refer to the "Cross-compilation +toolchains and C code" section below. + +## Cross-compilation toolchains and C code + +Rust code built using the target is compatible with C code compiled with +GCC or Clang using the `s390x-unknown-linux-musl` target triple (via either +native or cross-compilation). + +Depending on your system, you may need to configure the target to use the GNU +GCC linker. To use it, add the following to your `.cargo/config.toml`: + +```toml +[target.s390x-unknown-linux-musl] +linker = "s390x-linux-musl-gcc" +``` + +If your `s390x-linux-musl-*` toolchain is not in your `PATH` you may need to +configure additional settings: + +```toml +[target.s390x-unknown-linux-musl] +# Adjust the paths to point at your toolchain +cc = "/TOOLCHAIN_PATH/bin/s390x-linux-musl-gcc" +cxx = "/TOOLCHAIN_PATH/bin/s390x-linux-musl-g++" +ar = "/TOOLCHAIN_PATH/bin/s390x-linux-musl-ar" +ranlib = "/TOOLCHAIN_PATH/bin/s390x-linux-musl-ranlib" +linker = "/TOOLCHAIN_PATH/bin/s390x-linux-musl-gcc" +``` + +To test cross compiled binaries on a non-s390x host, you can use +[`qemu`](https://www.qemu.org/docs/master/system/target-s390x.html).