Skip to content

Commit 8f95079

Browse files
uweiganduweigand
committed
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 <[email protected]>
1 parent c602e9a commit 8f95079

File tree

4 files changed

+199
-2
lines changed

4 files changed

+199
-2
lines changed

‎src/doc/rustc/src/SUMMARY.md

+2
Original file line numberDiff line numberDiff line change
@@ -72,6 +72,8 @@
7272
- [riscv32imac-unknown-xous-elf](platform-support/riscv32imac-unknown-xous-elf.md)
7373
- [riscv64gc-unknown-linux-gnu](platform-support/riscv64gc-unknown-linux-gnu.md)
7474
- [riscv64gc-unknown-linux-musl](platform-support/riscv64gc-unknown-linux-musl.md)
75+
- [s390x-unknown-linux-gnu](platform-support/s390x-unknown-linux-gnu.md)
76+
- [s390x-unknown-linux-musl](platform-support/s390x-unknown-linux-musl.md)
7577
- [sparc-unknown-none-elf](./platform-support/sparc-unknown-none-elf.md)
7678
- [*-pc-windows-gnullvm](platform-support/pc-windows-gnullvm.md)
7779
- [\*-nto-qnx-\*](platform-support/nto-qnx.md)

‎src/doc/rustc/src/platform-support.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -99,7 +99,7 @@ target | notes
9999
`powerpc64le-unknown-linux-gnu` | PPC64LE Linux (kernel 3.10, glibc 2.17)
100100
[`riscv64gc-unknown-linux-gnu`](platform-support/riscv64gc-unknown-linux-gnu.md) | RISC-V Linux (kernel 4.20, glibc 2.29)
101101
[`riscv64gc-unknown-linux-musl`](platform-support/riscv64gc-unknown-linux-musl.md) | RISC-V Linux (kernel 4.20, musl 1.2.3)
102-
`s390x-unknown-linux-gnu` | S390x Linux (kernel 3.2, glibc 2.17)
102+
[`s390x-unknown-linux-gnu`](platform-support/s390x-unknown-linux-gnu.md) | S390x Linux (kernel 3.2, glibc 2.17)
103103
`x86_64-unknown-freebsd` | 64-bit FreeBSD
104104
`x86_64-unknown-illumos` | illumos
105105
`x86_64-unknown-linux-musl` | 64-bit Linux with musl 1.2.3
@@ -367,7 +367,7 @@ target | std | host | notes
367367
[`riscv64gc-unknown-openbsd`](platform-support/openbsd.md) | ✓ | ✓ | OpenBSD/riscv64
368368
[`riscv64-linux-android`](platform-support/android.md) | | | RISC-V 64-bit Android
369369
[`riscv64-wrs-vxworks`](platform-support/vxworks.md) | ✓ | |
370-
`s390x-unknown-linux-musl` | | | S390x Linux (kernel 3.2, musl 1.2.3)
370+
[`s390x-unknown-linux-musl`](platform-support/s390x-unknown-linux-musl.md) | | | S390x Linux (kernel 3.2, musl 1.2.3)
371371
`sparc-unknown-linux-gnu` | ✓ | | 32-bit SPARC Linux
372372
[`sparc-unknown-none-elf`](./platform-support/sparc-unknown-none-elf.md) | * | | Bare 32-bit SPARC V7+
373373
[`sparc64-unknown-netbsd`](platform-support/netbsd.md) | ✓ | ✓ | NetBSD/sparc64

‎src/doc/rustc/src/platform-support/s390x-unknown-linux-gnu.md

+112
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
# `s390x-unknown-linux-gnu`
2+
3+
**Tier: 2 (with Host Tools)**
4+
5+
IBM z/Architecture (s390x) targets (including IBM Z and LinuxONE) running Linux.
6+
7+
## Target maintainers
8+
9+
- Ulrich Weigand, <[email protected]>, [@uweigand](https://github.com/uweigand)
10+
11+
## Requirements
12+
13+
This target requires:
14+
15+
* Linux Kernel version 3.2 or later
16+
* glibc 2.17 or later
17+
18+
Code generated by the target uses the z/Architecture ISA assuming a minimum
19+
architecture level of z10 (Eighth Edition of the z/Architecture Principles
20+
of Operation), and is compliant with the s390x ELF ABI.
21+
22+
Reference material:
23+
24+
* [z/Architecture Principles of Operation][s390x-isa]
25+
* [z/Architecture ELF Application Binary Interface][s390x-abi]
26+
27+
[s390x-isa]: https://publibfp.dhe.ibm.com/epubs/pdf/a227832d.pdf
28+
[s390x-abi]: https://github.com/IBM/s390x-abi
29+
30+
## Building the target
31+
32+
This target is distributed through `rustup`, and otherwise requires no
33+
special configuration.
34+
35+
If you need to build your own Rust for some reason though, the target can be
36+
enabled in `config.toml`. For example:
37+
38+
```toml
39+
[build]
40+
target = ["s390x-unknown-linux-gnu"]
41+
```
42+
43+
## Building Rust programs
44+
45+
On a s390x Linux host, the `s390x-unknown-linux-gnu` target should be
46+
automatically installed and used by default.
47+
48+
On a non-s390x host, add the target:
49+
50+
```bash
51+
rustup target add s390x-unknown-linux-gnu
52+
```
53+
54+
Then cross compile crates with:
55+
56+
```bash
57+
cargo build --target s390x-unknown-linux-gnu
58+
```
59+
60+
## Testing
61+
62+
There are no special requirements for testing and running the target.
63+
For testing cross builds on the host, please refer to the "Cross-compilation
64+
toolchains and C code" section below.
65+
66+
## Cross-compilation toolchains and C code
67+
68+
Rust code built using the target is compatible with C code compiled with
69+
GCC or Clang using the `s390x-unknown-linux-gnu` target triple (via either
70+
native or cross-compilation).
71+
72+
On Ubuntu, a s390x cross-toolchain can be installed with:
73+
74+
```bash
75+
apt install gcc-s390x-linux-gnu g++-s390x-linux-gnu libc6-dev-s390x-cross
76+
```
77+
78+
Depending on your system, you may need to configure the target to use the GNU
79+
GCC linker. To use it, add the following to your `.cargo/config.toml`:
80+
81+
```toml
82+
[target.s390x-unknown-linux-gnu]
83+
linker = "s390x-linux-gnu-gcc"
84+
```
85+
86+
If your `s390x-linux-gnu-*` toolchain is not in your `PATH` you may need to
87+
configure additional settings:
88+
89+
```toml
90+
[target.s390x-unknown-linux-gnu]
91+
# Adjust the paths to point at your toolchain
92+
cc = "/TOOLCHAIN_PATH/bin/s390x-linux-gnu-gcc"
93+
cxx = "/TOOLCHAIN_PATH/bin/s390x-linux-gnu-g++"
94+
ar = "/TOOLCHAIN_PATH/bin/s390x-linux-gnu-ar"
95+
ranlib = "/TOOLCHAIN_PATH/bin/s390x-linux-gnu-ranlib"
96+
linker = "/TOOLCHAIN_PATH/bin/s390x-linux-gnu-gcc"
97+
```
98+
99+
To test cross compiled binaries on a non-s390x host, you can use
100+
[`qemu`](https://www.qemu.org/docs/master/system/target-s390x.html).
101+
On Ubuntu, a s390x emulator can be obtained with:
102+
103+
```bash
104+
apt install qemu-system-s390x
105+
```
106+
107+
Then, in `.cargo/config.toml` set the `runner`:
108+
109+
```toml
110+
[target.s390x-unknown-linux-gnu]
111+
runner = "qemu-s390x-static -L /usr/s390x-linux-gnu"
112+
```

‎src/doc/rustc/src/platform-support/s390x-unknown-linux-musl.md

+83
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
# `s390x-unknown-linux-musl`
2+
3+
**Tier: 3**
4+
5+
IBM z/Architecture (s390x) targets (including IBM Z and LinuxONE) running Linux.
6+
7+
## Target maintainers
8+
9+
- Ulrich Weigand, <[email protected]>, [@uweigand](https://github.com/uweigand)
10+
11+
## Requirements
12+
13+
This target requires:
14+
15+
* Linux Kernel version 3.2 or later
16+
* musl 1.2.3 or later
17+
18+
Code generated by the target uses the z/Architecture ISA assuming a minimum
19+
architecture level of z10 (Eighth Edition of the z/Architecture Principles
20+
of Operation), and is compliant with the s390x ELF ABI.
21+
22+
Reference material:
23+
24+
* [z/Architecture Principles of Operation][s390x-isa]
25+
* [z/Architecture ELF Application Binary Interface][s390x-abi]
26+
27+
[s390x-isa]: https://publibfp.dhe.ibm.com/epubs/pdf/a227832d.pdf
28+
[s390x-abi]: https://github.com/IBM/s390x-abi
29+
30+
## Building the target
31+
32+
Because it is Tier 3, Rust does not yet ship pre-compiled artifacts for this
33+
target.
34+
35+
Therefore, you can build Rust with support for the target by adding it to the
36+
target list in `config.toml`, a sample configuration is shown below.
37+
38+
```toml
39+
[build]
40+
target = ["s390x-unknown-linux-musl"]
41+
```
42+
43+
## Building Rust programs
44+
45+
Rust does not yet ship pre-compiled artifacts for this target. To compile for
46+
this target, you will first need to build Rust with the target enabled (see
47+
"Building the target" above).
48+
49+
## Testing
50+
51+
There are no special requirements for testing and running the target.
52+
For testing cross builds on the host, please refer to the "Cross-compilation
53+
toolchains and C code" section below.
54+
55+
## Cross-compilation toolchains and C code
56+
57+
Rust code built using the target is compatible with C code compiled with
58+
GCC or Clang using the `s390x-unknown-linux-musl` target triple (via either
59+
native or cross-compilation).
60+
61+
Depending on your system, you may need to configure the target to use the GNU
62+
GCC linker. To use it, add the following to your `.cargo/config.toml`:
63+
64+
```toml
65+
[target.s390x-unknown-linux-musl]
66+
linker = "s390x-linux-musl-gcc"
67+
```
68+
69+
If your `s390x-linux-musl-*` toolchain is not in your `PATH` you may need to
70+
configure additional settings:
71+
72+
```toml
73+
[target.s390x-unknown-linux-musl]
74+
# Adjust the paths to point at your toolchain
75+
cc = "/TOOLCHAIN_PATH/bin/s390x-linux-musl-gcc"
76+
cxx = "/TOOLCHAIN_PATH/bin/s390x-linux-musl-g++"
77+
ar = "/TOOLCHAIN_PATH/bin/s390x-linux-musl-ar"
78+
ranlib = "/TOOLCHAIN_PATH/bin/s390x-linux-musl-ranlib"
79+
linker = "/TOOLCHAIN_PATH/bin/s390x-linux-musl-gcc"
80+
```
81+
82+
To test cross compiled binaries on a non-s390x host, you can use
83+
[`qemu`](https://www.qemu.org/docs/master/system/target-s390x.html).

0 commit comments

Comments
 (0)