src/doc/rustc/src/platform-support/armv6k-nintendo-3ds.md

   1 # `armv6k-nintendo-3ds`
   2
   3 **Tier: 3**
   4
   5 The Nintendo 3DS platform, which has an ARMv6K processor, and its associated
   6 operating system (`horizon`).
   7
   8 Rust support for this target is not affiliated with Nintendo, and is not derived
   9 from nor used with any official Nintendo SDK.
  10
  11 ## Target maintainers
  12
  13 - [@Meziu](https://github.com/Meziu)
  14 - [@AzureMarker](https://github.com/AzureMarker)
  15 - [@ian-h-chamberlain](https://github.com/ian-h-chamberlain)
  16
  17 ## Requirements
  18
  19 This target is cross-compiled. Dynamic linking is not supported.
  20
  21 `#![no_std]` crates can be built using `build-std` to build `core` and optionally
  22 `alloc`, and either `panic_abort` or `panic_unwind`.
  23
  24 `std` is partially supported, but mostly works. Some APIs are unimplemented
  25 and will simply return an error, such as `std::process`. An allocator is provided
  26 by default.
  27
  28 In order to support some APIs, binaries must be linked against `libc` written
  29 for the target, using a linker for the target. These are provided by the
  30 devkitARM toolchain. See
  31 [Cross-compilation toolchains and C code](#cross-compilation-toolchains-and-c-code)
  32 for more details.
  33
  34 Additionally, some helper crates provide implementations of some `libc` functions
  35 use by `std` that may otherwise be missing. These, or an alternate implementation
  36 of the relevant functions, are required to use `std`:
  37
  38 - [`pthread-3ds`](https://github.com/Meziu/pthread-3ds) provides pthread APIs for `std::thread`.
  39 - [`linker-fix-3ds`](https://github.com/Meziu/rust-linker-fix-3ds) fulfills some other missing libc APIs.
  40
  41 Binaries built for this target should be compatible with all variants of the
  42 3DS (and 2DS) hardware and firmware, but testing is limited and some versions may
  43 not work correctly.
  44
  45 This target generates binaries in the ELF format.
  46
  47 ## Building the target
  48
  49 You can build Rust with support for the target by adding it to the `target`
  50 list in `config.toml` and providing paths to the devkitARM toolchain.
  51
  52 ```toml
  53 [build]
  54 build-stage = 1
  55 target = ["armv6k-nintendo-3ds"]
  56
  57 [target.armv6k-nintendo-3ds]
  58 cc = "/opt/devkitpro/devkitARM/bin/arm-none-eabi-gcc"
  59 cxx = "/opt/devkitpro/devkitARM/bin/arm-none-eabi-g++"
  60 ar = "/opt/devkitpro/devkitARM/bin/arm-none-eabi-ar"
  61 ranlib = "/opt/devkitpro/devkitARM/bin/arm-none-eabi-ranlib"
  62 linker = "/opt/devkitpro/devkitARM/bin/arm-none-eabi-gcc"
  63 ```
  64
  65 Also, to build `compiler_builtins` for the target, export these flags before
  66 building the Rust toolchain:
  67
  68 ```sh
  69 export CFLAGS_armv6k_nintendo_3ds="-mfloat-abi=hard -mtune=mpcore -mtp=soft -march=armv6k"
  70 ```
  71
  72 ## Building Rust programs
  73
  74 Rust does not yet ship pre-compiled artifacts for this target.
  75
  76 The recommended way to build binaries is by using the
  77 [cargo-3ds](https://github.com/Meziu/cargo-3ds) tool, which uses `build-std`
  78 and provides commands that work like the usual `cargo run`, `cargo build`, etc.
  79
  80 You can also build Rust with the target enabled (see
  81 [Building the target](#building-the-target) above).
  82
  83 As mentioned in [Requirements](#requirements), programs that use `std` must link
  84 against both the devkitARM toolchain and libraries providing the `libc` APIs used
  85 in `std`.  There is a general-purpose utility crate for working with nonstandard
  86 APIs provided by the OS: [`ctru-rs`](https://github.com/Meziu/ctru-rs).
  87 Add it to Cargo.toml to use it in your program:
  88
  89 ```toml
  90 [dependencies]
  91 ctru-rs = { git = "https://github.com/Meziu/ctru-rs.git" }
  92 ```
  93
  94 Using this library's `init()` function ensures the symbols needed to link
  95 against `std` are present (as mentioned in [Requirements](#requirements)
  96 above), as well as providing a runtime suitable for `std`:
  97
  98 ```rust,ignore (requires-3rd-party-library)
  99 fn main() {
 100     ctru::init();
 101 }
 102 ```
 103
 104 ## Testing
 105
 106 Binaries built for this target can be run in an emulator (most commonly
 107 [Citra](https://citra-emu.org/)), or sent to a device through
 108 the use of a tool like devkitARM's `3dslink`. They may also simply be copied
 109 to an SD card to be inserted in the device.
 110
 111 The `cargo-3ds` tool mentioned in [Building Rust programs](#building-rust-programs)
 112 supports the use of `3dslink` with `cargo 3ds run`. The default Rust test runner
 113 is not supported, but
 114 [custom test frameworks](../../unstable-book/language-features/custom-test-frameworks.html)
 115 can be used with `cargo 3ds test` to run unit tests on a device.
 116
 117 The Rust test suite for `library/std` is not yet supported.
 118
 119 ## Cross-compilation toolchains and C code
 120
 121 C code can be built for this target using the
 122 [devkitARM toolchain](https://devkitpro.org/wiki/Getting_Started).
 123 This toolchain provides `arm-none-eabi-gcc` as the linker used to link Rust
 124 programs as well.
 125
 126 The toolchain also provides a `libc` implementation, which is required by `std`
 127 for many of its APIs, and a helper library `libctru` which is used by several
 128 of the helper crates listed in [Requirements](#requirements).
 129 This toolchain does not, however, include all of the APIs expected by `std`,
 130 and the remaining APIs are implemented by `pthread-3ds` and `linker-fix-3ds`.