ctru-rs

The ctru-rs project provides tools for Nintendo 3DS homebrew development using Rust. The repository is divided into three main components:

• ctru-rs: The primary crate for developers. It provides a safe, idiomatic Rust wrapper around the low-level bindings.
• ctru-sys: Low-level, unsafe Rust bindings to the C library libctru.
• test-runner: A helper crate designed to facilitate running Rust tests on actual 3DS hardware or an emulator.

To begin developing for the Nintendo 3DS, you should use the ctru-rs crate for a safe and idiomatic experience. Detailed installation and usage instructions are located in the package-specific documentation.

For a broad overview of how to use the crates, refer to the ctru-rs package README.

Doctests do not automatically use the crate's #![test_runner] attribute. To make doctests work with the runner, you must manually instantiate a runner at the beginning of the doctest (or within the fn main() if the test defines one).

Important: The runner instance must remain in scope for the entire duration of the test to ensure the test output is printed.

let _runner = test_runner::GdbRunner::default();

To develop homebrew software for the Nintendo 3DS using ctru-rs, you must first meet specific environment requirements. It is highly recommended to read the ctru-rs wiki Getting Started guide to understand the necessary toolchains and setup for 3DS development.

Once the environment is prepared, you can use ctru-rs by adding it as a dependency to your Cargo.toml.

To run automated Rust tests on 3DS hardware or an emulator, you must use custom_test_frameworks because the standard Rust test framework expects a traditional OS with subprocesses.

1. Add test-runner to your development dependencies:

   cargo add --dev test-runner --git https://github.com/rust3ds/ctru-rs

2. Configure your lib.rs or integration test files to use the custom test runner by adding the following attributes to the top of the file:

   #![feature(custom_test_frameworks)]
   #![test_runner(test_runner::run_gdb)]

To use ctru-sys, you must link against the libctru C library. The bindings are raw Rust bindings over the libctru library.

To obtain the required packages for libctru, consult the ctru-rs wiki at https://github.com/rust3ds/ctru-rs/wiki/Getting-Started.

The Soc service enables the use of network sockets and utilities found in std::net, which are inaccessible by default on the 3DS.

Important: You must hold a handle to the Soc instance for the duration of your network operations. If the Soc handle is dropped, subsequent std::net calls will return generic OS errors.

To use the service, initialize it using Soc::new() or Soc::init_with_buffer_size(num_bytes). Note that only one instance of the Soc service can be active at a time; attempting to initialize a second instance will return an error.

use ctru::services::soc::Soc;

// Initialize the service and keep the handle alive
let soc = Soc::new()?;

// Now you can use std::net functionality
// ...

The library provides three distinct runner implementations that implement the internal TestRunner trait. You can choose the one that best fits your debugging or execution environment:

• ConsoleRunner: For running tests with console output.
• GdbRunner: For running tests within a GDB debugging session.
• SocketRunner: For running tests via a socket interface.

You can control which Miis are visible in the selector using allowlists and blocklists for both Guest and User Miis.

Important: Guest Miis will not be available regardless of their allowlist/blocklist state if you do not set Options::ENABLE_GUESTS in set_options().

// Allowlist a guest Mii at index 2
mii_selector.allowlist_guest_mii(Index::Index(2));

// Blocklist all user-created Miis
mii_selector.blocklist_user_mii(Index::All);

ctru-rs is a safe and idiomatic Rust wrapper around libctru, providing access to Nintendo 3DS system services and hardware (HID, network, graphics, cameras, etc.). It also handles the integration of Rust std with the 3DS operating system.

To use ctru-rs:

1. Follow the official ctru-rs wiki to set up the required toolchain.
2. Add ctru-rs as a dependency in your Cargo.toml.
3. Build your binaries for the armv6k-nintendo-3ds target, either manually or using cargo-3ds.