-
Notifications
You must be signed in to change notification settings - Fork 12.7k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Introduce infrastructure for generating target docs
- Loading branch information
Showing
17 changed files
with
1,092 additions
and
3 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,7 @@ | ||
| # List of all targets | ||
|
|
||
| An alphabetical list of all targets. | ||
|
|
||
| <!-- TARGET SECTION START --> | ||
| <!-- See `src/tools/target-docs` --> | ||
| <!-- TARGET SECTION END --> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,84 @@ | ||
| --- | ||
| tier: "2" | ||
| maintainers: ["@thomcc"] | ||
| metadata: | ||
| - target: "aarch64-apple-tvos" | ||
| notes: "ARM64 tvOS" | ||
| std: "unknown" | ||
| host: false | ||
| --- | ||
|
|
||
| ## Overview | ||
|
|
||
| Apple tvOS targets: | ||
| - Apple tvOS on aarch64 | ||
| - Apple tvOS Simulator on x86_64 | ||
|
|
||
| ## Requirements | ||
|
|
||
| These targets are cross-compiled. You will need appropriate versions of Xcode | ||
| and the SDKs for tvOS (`AppleTVOS.sdk`) and/or the tvOS Simulator | ||
| (`AppleTVSimulator.sdk`) to build a toolchain and target these platforms. | ||
|
|
||
| The targets support most (see below) of the standard library including the | ||
| allocator to the best of my knowledge, however they are very new, not yet | ||
| well-tested, and it is possible that there are various bugs. | ||
|
|
||
| In theory we support back to tvOS version 7.0, although the actual minimum | ||
| version you can target may be newer than this, for example due to the versions | ||
| of Xcode and your SDKs. | ||
|
|
||
| As with the other Apple targets, `rustc` respects the common environment | ||
| variables used by Xcode to configure this, in this case | ||
| `TVOS_DEPLOYMENT_TARGET`. | ||
|
|
||
| As mentioned, "most" of the standard library is supported, which means that some portions | ||
| are known to be unsupported. The following APIs are currently known to have | ||
| missing or incomplete support: | ||
|
|
||
| - `std::process::Command`'s API will return an error if it is configured in a | ||
| manner which cannot be performed using `posix_spawn` -- this is because the | ||
| more flexible `fork`/`exec`-based approach is prohibited on these platforms in | ||
| favor of `posix_spawn{,p}` (which still probably will get you rejected from | ||
| app stores, so is likely sideloading-only). A concrete set of cases where this | ||
| will occur is difficult to enumerate (and would quickly become stale), but in | ||
| some cases it may be worked around by tweaking the manner in which `Command` | ||
| is invoked. | ||
|
|
||
| ## Building the target | ||
|
|
||
| The targets can be built by enabling them for a `rustc` build in `config.toml`, by adding, for example: | ||
|
|
||
| ```toml | ||
| [build] | ||
| build-stage = 1 | ||
| target = ["aarch64-apple-tvos", "x86_64-apple-tvos", "aarch64-apple-tvos-sim"] | ||
| ``` | ||
|
|
||
| It's possible that cargo under `-Zbuild-std` may also be used to target them. | ||
|
|
||
| ## Building Rust programs | ||
|
|
||
| *Note: Building for this target requires the corresponding TVOS SDK, as provided by Xcode.* | ||
|
|
||
| Rust programs can be built for these targets | ||
|
|
||
| ```text | ||
| $ rustc --target aarch64-apple-tvos your-code.rs | ||
| ... | ||
| $ rustc --target x86_64-apple-tvos your-code.rs | ||
| ... | ||
| $ rustc --target aarch64-apple-tvos-sim your-code.rs | ||
| ``` | ||
|
|
||
| ## Testing | ||
|
|
||
| There is no support for running the Rust or standard library testsuite on tvOS or the simulators at the moment. Testing has mostly been done manually with builds of static libraries called from Xcode or a simulator. | ||
|
|
||
| It hopefully will be possible to improve this in the future. | ||
|
|
||
| ## Cross compilation | ||
|
|
||
| This target can be cross-compiled from x86_64 or aarch64 macOS hosts. | ||
|
|
||
| Other hosts are not supported for cross-compilation, but might work when also providing the required Xcode SDK. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,20 @@ | ||
| --- | ||
| tier: "1" | ||
| metadata: | ||
| - target: "i686-pc-windows-gnu" | ||
| notes: "32-bit MinGW (Windows 7+)" | ||
| std: true | ||
| host: true | ||
| footnotes: | ||
| - name: "x86_32-floats-return-ABI" | ||
| content: | | ||
| Due to limitations of the C ABI, floating-point support on `i686` targets is non-compliant: | ||
| floating-point return values are passed via an x87 register, so NaN payload bits can be lost. | ||
| See [issue #114479][https://github.com/rust-lang/rust/issues/114479]. | ||
| - name: "windows-support" | ||
| content: "Only Windows 10 currently undergoes automated testing. Earlier versions of Windows rely on testing and support from the community." | ||
| --- | ||
|
|
||
| ## Overview | ||
|
|
||
| 32-bit Windows using MinGW. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,99 @@ | ||
| --- | ||
| tier: "2" | ||
| maintainers: | ||
| - "[WANG Rui](https://github.com/heiher) `wangrui@loongson.cn`" | ||
| - "[ZHAI Xiang](https://github.com/xiangzhai) `zhaixiang@loongson.cn`" | ||
| - "[ZHAI Xiaojuan](https://github.com/zhaixiaojuan) `zhaixiaojuan@loongson.cn`" | ||
| - "[WANG Xuerui](https://github.com/xen0n) `git@xen0n.name`" | ||
| metadata: | ||
| - target: "loongarch64-unknown-linux-gnu" | ||
| notes: "LoongArch64 Linux, LP64D ABI (kernel 5.19, glibc 2.36)" | ||
| std: true | ||
| host: true | ||
| --- | ||
|
|
||
| ## Overview | ||
|
|
||
| [LoongArch] is a new RISC ISA developed by Loongson Technology Corporation Limited. | ||
|
|
||
| [LoongArch]: https://loongson.github.io/LoongArch-Documentation/README-EN.html | ||
|
|
||
| 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. | ||
| 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>`. | ||
|
|
||
| | `<fabi-suffix>` | `Description` | | ||
| |------------------------|--------------------------------------------------------------------| | ||
| | f64 | The base ABI use 64-bits FPRs for parameter passing. (lp64d)| | ||
| | f32 | The base ABI uses 32-bit FPRs for parameter passing. (lp64f)| | ||
| | sf | The base ABI uses no FPR for parameter passing. (lp64s) | | ||
|
|
||
| <br> | ||
|
|
||
| |`ABI type(Base ABI/ABI extension)`| `C library` | `kernel` | `target tuple` | | ||
| |----------------------------------|-------------|----------|----------------------------------| | ||
| | lp64d/base | glibc | linux | loongarch64-unknown-linux-gnu | | ||
| | lp64f/base | glibc | linux | loongarch64-unknown-linux-gnuf32 | | ||
| | lp64s/base | glibc | linux | loongarch64-unknown-linux-gnusf | | ||
| | lp64d/base | musl libc | linux | loongarch64-unknown-linux-musl| | ||
| | lp64f/base | musl libc | linux | loongarch64-unknown-linux-muslf32| | ||
| | lp64s/base | musl libc | linux | loongarch64-unknown-linux-muslsf | | ||
|
|
||
| ## Requirements | ||
|
|
||
| This target is cross-compiled. | ||
| 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). | ||
|
|
||
| ## Building the target | ||
|
|
||
| The target can be built by enabling it for a `rustc` build. | ||
|
|
||
| ```toml | ||
| [build] | ||
| target = ["loongarch64-unknown-linux-gnu"] | ||
| ``` | ||
|
|
||
| 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`: | ||
|
|
||
| ```toml | ||
| [target.loongarch64-unknown-linux-gnu] | ||
| # ADJUST THIS PATH TO POINT AT YOUR TOOLCHAIN | ||
| cc = "/TOOLCHAIN_PATH/bin/loongarch64-unknown-linux-gnu-gcc" | ||
| cxx = "/TOOLCHAIN_PATH/bin/loongarch64-unknown-linux-gnu-g++" | ||
| ar = "/TOOLCHAIN_PATH/bin/loongarch64-unknown-linux-gnu-ar" | ||
| ranlib = "/TOOLCHAIN_PATH/bin/loongarch64-unknown-linux-gnu-ranlib" | ||
| linker = "/TOOLCHAIN_PATH/bin/loongarch64-unknown-linux-gnu-gcc" | ||
| ``` | ||
|
|
||
| ## Cross compilation | ||
|
|
||
| This target can be cross-compiled on a `x86_64-unknown-linux-gnu` host. Cross-compilation on other hosts may work but is not tested. | ||
|
|
||
| ## Testing | ||
| To test a cross-compiled binary on your build system, install the qemu binary that supports the LoongArch architecture and execute the following commands. | ||
| ```text | ||
| CC_loongarch64_unknown_linux_gnu=/TOOLCHAIN_PATH/bin/loongarch64-unknown-linux-gnu-gcc \ | ||
| CXX_loongarch64_unknown_linux_gnu=/TOOLCHAIN_PATH/bin/loongarch64-unknown-linux-gnu-g++ \ | ||
| AR_loongarch64_unknown_linux_gnu=/TOOLCHAIN_PATH/bin/loongarch64-unknown-linux-gnu-gcc-ar \ | ||
| CARGO_TARGET_LOONGARCH64_UNKNOWN_LINUX_GNUN_LINKER=/TOOLCHAIN_PATH/bin/loongarch64-unknown-linux-gnu-gcc \ | ||
| # SET TARGET SYSTEM LIBRARY PATH | ||
| CARGO_TARGET_LOONGARCH64_UNKNOWN_LINUX_GNUN_RUNNER="qemu-loongarch64 -L /TOOLCHAIN_PATH/TARGET_LIBRARY_PATH" \ | ||
| cargo run --target loongarch64-unknown-linux-gnu --release | ||
| ``` | ||
| Tested on x86 architecture, other architectures not tested. | ||
|
|
||
| ## Building Rust programs | ||
|
|
||
| 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. | ||
|
|
||
| If `rustc` has support for that target and the library artifacts are available, then Rust static libraries can be built for that target: | ||
|
|
||
| ```shell | ||
| $ rustc --target loongarch64-unknown-linux-gnu your-code.rs --crate-type staticlib | ||
| $ ls libyour_code.a | ||
| ``` | ||
|
|
||
| On Rust Nightly it's possible to build without the target artifacts available: | ||
|
|
||
| ```text | ||
| cargo build -Z build-std --target loongarch64-unknown-linux-gnu | ||
| ``` |
Oops, something went wrong.