Getting Started
To run our tools and libraries to their full potential you must meet these requirements:
To run homebrew software on your Nintendo 3DS, you will need to modify the console's firmware. You will especially need the "Homebrew Launcher" application, which lets you run and debug your software (packaged in .3dsx executable files).
You can also run 3DS homebrew using an emulator, for faster iteration while developing, or if you don't have / don't want to hack a 3DS. Note that there might be some differences / limitations compared to running on real hardware, so you should always test your code on a real device if possible.
Follow this guide to install the language on your platform.
This section is unnecessary for people who already use the devkitARM toolchain to develop homebrew. If it's your first time using it, follow the next instruction, otherwise, skip to the next main paragraph.
devkitARM provides many packages to start working on software. You can install these tools and libraries on Windows, MacOS and Linux, by using dkp-pacman. Follow their "Getting Started" guide for your platform, by the end of which you should have the dkp-pacman installer ready in your terminal emulator (for Linux distros that use pacman, you can also just add their repositories as sources and use that instead, but keep in mind that we'll refer to it as dkp-pacman from now on).
dkp-pacman is the main installer for all devkitARM packages, including some third-party C libraries which have been ported over to Nintendo 3DS (these are known as "portlibs"). By using this tool, you can now install the main packages for developing. As the devkitPRO guide suggests, simply do sudo dkp-pacman -S 3ds-dev to install all main packages.
This may be a hard step to follow (especially if you're not used to using the command line) but it's absolutely needed to get our tools up and running. Restart your terminal emulator and check whether the environment variables DEVKITPRO and DEVKITARM are properly set. Also, check if $DEVKITPRO/tools/bin and $DEVKITARM/bin are visible in the PATH. If not, set them manually.
We are finally out of the C realm, and can continue our safe journey into Rust programming.
Install cargo-3ds
cargo-3ds is our custom made cargo extension to build and test 3DS executable files. You can install the latest stable version on crates.io by running cargo install cargo-3ds.
Rust3DS -sys libraries use bindgen at build time to generate bindings to devkitPro APIs, which in turn uses LLVM to parse C headers. For this to work correctly bindgen needs some version of LLVM installed — see their documentation for detailed installation instructions.
You can now start writing some real code! There are many ways to start depending on your objective. It's possible to use cargo-3ds to create a new project already prepared with the tools you'll need. Simply do cargo 3ds new <project-name> and get coding!
There are some very important things to note:
- Even though building, running and testing can be done via standard
cargocommands, we suggest you look into usingcargo-3dsto speedup most of the workflow (go look at its README to learn how it works). - To use all system-specific functionality and the Rust
stdyou'll have to depend onctru-rs. There are ways to get those working by yourself, but for the sake of this guide you should just base your work onctru-rs(there is a lot of great stuff here!). - Even while using
ctru-rs, modules such asstd::processandstd::thread(plus most third party crates) may not work (or work differently than originally intended) because of how the OS operates. You can read more about that in System Flaws.
If you don’t feel ready to start your own project, or simply want to see what the console is capable of, you can try the included examples.
Happy coding! 👋 🦀