cargo-3ds

Cargo command to work with Nintendo 3DS project binaries. Based on cargo-psp.

Installation

To install the latest release on https://crates.io:

cargo install --locked cargo-3ds

To install the current master version of cargo-3ds:

cargo install --locked --git https://github.com/rust3ds/cargo-3ds

Usage

Use the nightly toolchain to build 3DS apps (either by using rustup override nightly for the project directory or by adding +nightly in the cargo invocation).

Commands:
  build
          Builds an executable suitable to run on a 3DS (3dsx)
  run
          Builds an executable and sends it to a device with `3dslink`
  test
          Builds a test executable and sends it to a device with `3dslink`
  new
          Sets up a new cargo project suitable to run on a 3DS
  help
          Print this message or the help of the given subcommand(s)

Options:
  -h, --help
          Print help information (use `-h` for a summary)

  -V, --version
          Print version information

Additional arguments will be passed through to the given subcommand. See passthrough arguments for more details.

It is also possible to pass any other cargo command (e.g. doc, check), and all its arguments will be passed through directly to cargo unmodified, with the proper --target armv6k-nintendo-3ds set.

Basic Examples

• cargo 3ds build
• cargo 3ds check --verbose
• cargo 3ds run --release --example foo
• cargo 3ds test --no-run
• cargo 3ds new my-new-project --edition 2021

Running executables

cargo 3ds test and cargo 3ds run use the 3dslink tool to send built executables to a device, and thus accept specific related arguments that correspond to 3dslink arguments:

-a, --address <ADDRESS>
      Specify the IP address of the device to send the executable to.

      Corresponds to 3dslink's `--address` arg, which defaults to automatically finding the device.

-0, --argv0 <ARGV0>
      Set the 0th argument of the executable when running it. Corresponds to 3dslink's `--argv0` argument

-s, --server
      Start the 3dslink server after sending the executable. Corresponds to 3dslink's `--server` argument

  --retries <RETRIES>
      Set the number of tries when connecting to the device to send the executable. Corresponds to 3dslink's `--retries` argument

Passthrough Arguments

Due to the way cargo-3ds, cargo, and 3dslink parse arguments, there is unfortunately some complexity required when invoking an executable with arguments.

All unrecognized arguments beginning with a dash (e.g. --release, --features, etc.) will be passed through to cargo directly.

NOTE: arguments for running executables must be specified before other unrecognized cargo arguments. Otherwise they will be treated as passthrough arguments which will most likely fail the resulting cargo command.

An optional -- may be used to explicitly pass subsequent args to cargo, including arguments to pass to the executable itself. To separate cargo arguments from executable arguments, another -- can be used. For example:

• cargo 3ds run -- -- xyz

  Builds an executable and send it to a device to run it with the argument xyz.

• cargo 3ds test --address 192.168.0.2 -- -- --test-arg 1

  Builds a test executable and attempts to send it to a device with the address 192.168.0.2 and run it using the arguments ["--test-arg", "1"].

• cargo 3ds test --address 192.168.0.2 --verbose -- --test-arg 1

  Build a test executable with cargo test --verbose, and attempts to send it to a device with the address 192.168.0.2 and run it using the arguments ["--test-arg", "1"].

  This works without two -- instances because --verbose begins the set of cargo arguments and ends the set of 3DS-specific arguments.

Caveats

Due to the fact that only one executable at a time can be sent with 3dslink, by default only the "last" executable built will be used. If a test or run command builds more than one binary, you may need to filter it in order to run the executable you want.

Doc tests sort of work, but cargo-3ds uses a number of unstable cargo and rustdoc features to make them work, so the output won't be as pretty and will require some manual workarounds to actually run the tests and see output from them. For now, cargo 3ds test --doc will not build a 3dsx file or use 3dslink at all.

License

This project is distributed under the MIT license or the Apache-2.0 license.