Add a "Getting Started" guide

[Meziu]

As discussed in #97 and #32, we should setup the wiki on this repository to display helpful information on installing and getting to know our toolchain (as well as devkitPROs).

The wiki's page should be linked in the README.

[Meziu]

@rust3ds/active I've added a basic README to the organization's profile. Tell me if you have any suggestions to improve it.

[Techie-Pi]

It's great! I think it would be a good idea to remove the ⚠️ from the disclaimer.

--- # ⚠️ Disclaimer ⚠️
+++ # Disclaimer

[Meziu]

I've started working on the wiki for ctru-rs. For now I've only written the Home page and a Getting Started. Tell me if there is anything you'd like to see changed, added or removed.

[AzureMarker]

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 or install the bleeding edge version by running cargo install --git https://github.com/rust3ds/cargo-3ds.

cargo install cargo-3ds doesn't work because we haven't published it to crates.io yet.

$ cargo install cargo-3ds
    Updating crates.io index
error: could not find `cargo-3ds` in registry `crates-io` with version `*`

Even when using ctru-rs, modules such as std::process and std::thread (plus most third party crates) simply WILL NOT WORK because of how the OS operates. You can read more about that in [Unsupported Functionality].

std::thread does work, we just can't set the CPU affinity yet. It will spawn the thread on the current core (app core).

[Meziu]

cargo install cargo-3ds doesn't work because we haven't published it to crates.io yet.

I know, I just noted it there for simple future proofing. The current page is meant to mostly be a draft (weird how GitHub doesn’t let you actually make it a draft).

std::thread does work, we just can't set the CPU affinity yet. It will spawn the thread on the current core (app core).

True, I worded it badly. I meant that some functionality is locked away/threads aren’t preemptive. I should rephrase it.

[Meziu]

I've added the System Flaws page to list missing functionality and structural differences. As always, give me feedback on things to add and changes to make 😄

[ian-h-chamberlain]

Finally getting around to looking over the new wiki pages, thanks @Meziu for writing them up!

Also, check if $DEVKITPRO/tools/bin and $DEVKITARM/bin are visible in the PATH. If not, set them manually.

This is probably good advice generally (if the user wants to use those tools manually), but something occurred to me the other day: if we wanted, we could probably remove this requirement for cargo-3ds. Since we know all the relevant tools live in there and we require $DEVKITPRO/$DEVKITARM to be set, we could figure out the path to those tools without requiring the user's $PATH to be set accordingly, which might be easier for users to get started easily.

The std::process module is unsupported in its entirety. ... However, std::env (and environmental variables in general) is available for compatibility purposes. Beware of external crates and libraries which require access to processes.

Might be worth mentioning that std::env::set_var can be used in cases where libraries are expecting values to be set, since 3dslink/emulators don't have a way to pass env variables through.

Missing Functionality

Another thing worth mentioning might be stack traces (using backtrace-rs or on panic) - so far in my testing and after a bit of googling, it seems like it probably will never work the way Rust devs might be used to. We might want to include some tips about using arm-none-eabi-gdb to debug programs and get stack traces that way.

Cooperative threading and std::thread

This section definitely looks good! I think it covers most of the important parts, and we can probably revisit + update it whenever https://github.com/rust3ds/pthread-3ds/issues/24 gets resolved. It might also be good to add a reference to https://www.3dbrew.org/wiki/Multi-threading which describes some of the lower-level concepts even if they won't be directly used by consumers of rust3ds libs.

[Meziu]

This is probably good advice generally (if the user wants to use those tools manually), but something occurred to me the other day: if we wanted, we could probably remove this requirement for cargo-3ds. Since we know all the relevant tools live in there and we require $DEVKITPRO/$DEVKITARM to be set, we could figure out the path to those tools without requiring the user's $PATH to be set accordingly, which might be easier for users to get started easily.

How could we do that? Is there a common interface other than those env vars? (For example, I have no idea where the tools are placed in a Windows system).

Might be worth mentioning that std::env::set_var can be used in cases where libraries are expecting values to be set, since 3dslink/emulators don't have a way to pass env variables through.

Right, I should specify it.

Another thing worth mentioning might be stack traces (using backtrace-rs or on panic) - so far in my testing and after a bit of googling, it seems like it probably will never work the way Rust devs might be used to.

Hmm, other than a general warning I don't think there is much to do. I believe I already made clear that most crates wouldn't work regardless, especially low-level ones. 😅

We might want to include some tips about using arm-none-eabi-gdb to debug programs and get stack traces that way.

That would be a great idea for the Guides page. Writing an extensive guide on how to use the debugger (especially with rust-gdb) would be helpful for many newcomers (I wish I had one!).

[Meziu]

I've added the Guides page with a small introduction to unit tests and a step to step guide on rust-gdb. I've also added a small note about backtrace-rs in the System Flaws page.

Tell me what you think!

[ian-h-chamberlain]

The new stuff looks great! The wiki really feels like it's coming together, thanks for your efforts @Meziu !

[Meziu]

I will close this issue for now as there haven't been any major requests and changes, since this was supposed to track the "first version" of the wiki.

Feel free to open issues/discussions to integrate new paragraphs or changes to existing ones. I hope it helps! 😄