You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Rollup merge of rust-lang#127053 - xen0n:update-loong-docs, r=Nilstrieb,heiher
Update the LoongArch target documentation
The docs for the LoongArch targets are a bit dated since their introduction, and the prose has some room for improvement as well. Streamline a bit, referring to the neighboring targets' docs, and provide up-to-date information as much as I can come up with.
cc fellow target maintainer `@heiher` for review of target-specific bits
|`loongarch64-unknown-linux-gnu`| LoongArch64 Linux, LP64D ABI (kernel 5.19, glibc 2.36) |
11
+
|`loongarch64-unknown-linux-musl`| LoongArch64 Linux, LP64D ABI (kernel 5.19, musl 1.2.5) |
8
12
9
-
The target name follow this format: `<machine>-<vendor>-<os><fabi_suffix>`, where `<machine>` specifies the CPU family/model, `<vendor>` specifies the vendor and `<os>` the operating system name.
10
-
While the integer base ABI is implied by the machine field, the floating point base ABI type is encoded into the os field of the specifier using the string suffix `<fabi-suffix>`.
13
+
These support both native and cross builds, and have full support for `std`.
@@ -35,60 +29,109 @@ While the integer base ABI is implied by the machine field, the floating po
35
29
36
30
## Requirements
37
31
38
-
This target is cross-compiled.
39
-
A GNU toolchain for LoongArch target is required. It can be downloaded from https://github.com/loongson/build-tools/releases, or built from the source code of GCC (12.1.0 or later) and Binutils (2.40 or later).
32
+
### OS Version
40
33
41
-
## Building the target
34
+
The minimum supported Linux version is 5.19.
42
35
43
-
The target can be built by enabling it for a `rustc` build.
36
+
Some Linux distributions, mostly commercial ones, may provide forked Linux
37
+
kernels that has a version number less than 5.19 for their LoongArch ports.
38
+
Such kernels may still get patched to be compatible with the upstream Linux
39
+
5.19 UAPI, therefore supporting the targets described in this document, but
40
+
this is not always the case. The `rustup` installer contains a check for this,
41
+
and will abort if incompatibility is detected.
42
+
43
+
### Host toolchain
44
+
45
+
The targets require a reasonably up-to-date LoongArch toolchain on the host.
46
+
Currently the following components are used by the Rust CI to build the target,
47
+
and the versions can be seen as the minimum requirement:
48
+
49
+
* GNU Binutils 2.40
50
+
* GCC 13.x
51
+
* glibc 2.36
52
+
* linux-headers 5.19
53
+
54
+
Of these, glibc and linux-headers are at their respective earliest versions with
55
+
mainline LoongArch support, so it is impossible to use older versions of these.
56
+
Older versions of Binutils and GCC will not work either, due to lack of support
57
+
for newer LoongArch ELF relocation types, among other features.
58
+
59
+
Recent LLVM/Clang toolchains may be able to build the targets, but are not
60
+
currently being actively tested.
61
+
62
+
## Building
63
+
64
+
These targets are distributed through `rustup`, and otherwise require no
65
+
special configuration.
66
+
67
+
If you need to build your own Rust for some reason though, the targets can be
68
+
simply enabled in `config.toml`. For example:
44
69
45
70
```toml
46
71
[build]
47
72
target = ["loongarch64-unknown-linux-gnu"]
48
73
```
49
74
50
-
Make sure `loongarch64-unknown-linux-gnu-gcc` can be searched from the directories specified in`$PATH`. Alternatively, you can use GNU LoongArch Toolchain by adding the following to `config.toml`:
75
+
Make sure the LoongArch toolchain binaries are reachable from `$PATH`.
76
+
Alternatively, you can explicitly configure the paths in `config.toml`:
51
77
52
78
```toml
53
79
[target.loongarch64-unknown-linux-gnu]
54
-
# ADJUST THIS PATH TO POINT AT YOUR TOOLCHAIN
80
+
# Adjust the paths to point at your toolchain
81
+
# Suppose the toolchain is placed at /TOOLCHAIN_PATH, and the cross prefix is
82
+
# "loongarch64-unknown-linux-gnu-":
55
83
cc = "/TOOLCHAIN_PATH/bin/loongarch64-unknown-linux-gnu-gcc"
# Or alternatively, if binfmt_misc is set up for running LoongArch binaries
110
+
# transparently:
111
+
export QEMU_LD_PREFIX="$TOOLCHAIN_PATH"/sysroot
65
112
66
-
## Testing
67
-
To test a cross-compiled binary on your build system, install the qemu binary that supports the LoongArch architecture and execute the following commands.
cargo run --target loongarch64-unknown-linux-gnu --release
76
114
```
77
-
Tested on x86 architecture, other architectures not tested.
78
115
79
-
## Building Rust programs
116
+
## Testing
117
+
118
+
There are no special requirements for testing and running the targets.
119
+
For testing cross builds on the host, please refer to the "Cross-compilation"
120
+
section above.
80
121
81
-
Rust does not yet ship pre-compiled artifacts for this target. To compile for this target, you will either need to build Rust with the target enabled (see "Building the target" above), or build your own copy of `std` by using `build-std` or similar.
122
+
## Building Rust programs
82
123
83
-
If `rustc` has support for that target and the library artifacts are available, then Rust static libraries can be built for that target:
124
+
As the targets are available through `rustup`, it is very easy to build Rust
125
+
programs for these targets: same as with other architectures.
126
+
Note that you will need a LoongArch C/C++ toolchain for linking, or if you want
127
+
to compile C code along with Rust (such as for Rust crates with C dependencies).
0 commit comments