cargo-3ds/README.md

# cargo-3ds

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

## 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).

```txt
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`
  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](#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 `RUSTFLAGS` and `--target` set for the 3DS target.

### Basic Examples

* `cargo 3ds build`
* `cargo 3ds check --verbose`
* `cargo 3ds run --release --example foo`
* `cargo 3ds test --no-run`

### 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:

```txt
-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](#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.