overall update

Author: 29th-Day

.gitignore

@@ -1 +1,2 @@
 book
+.vscode

src/SUMMARY.md

@@ -2,7 +2,10 @@
 
 [Introduction](./introduction.md)
 - [Requirements](./requirements.md)
-- [Installation](./install.md)
+- [Installation](./install/install.md)
+    - [Homebrew](./install/homebrew.md)
+    - [Emulator](./install/emulator.md)
+    - [Development](./install/development.md)
 - [Wii U Architecture](./wiiu.md)
 - [Getting Started](./getting-started.md)
 - [Unsafe Territory](./unsafe.md)

src/faq.md

@@ -1,23 +1,34 @@
 # Frequently Asked Questions
 
 * [What is Homebrew?](#what-is-homebrew)
-* [Why Rust on the Wii U](#why-rust-on-the-wii-u)
 * [Will it every be a real std version?](#will-it-every-be-a-real-std-version)
+* [How to learn Rust?](#how-to-learn-rust)
+* [Why Rust on the Wii U](#why-rust-on-the-wii-u)
 
 ## What is Homebrew?
 
-Homebrew software refers to unofficial applications and tools developed by the community, bypassing manufacturer restrictions. It allows users to extend a console's functionality, enabling features like custom games, additional software, and system modifications.
+Homebrew software encompasses unofficial applications and tools created by the community, operating outside of the manufacturer's officially supported ecosystem. It empowers users to expand a console's capabilities, unlocking functionalities such as custom games, supplementary software, and system modifications.
 
-## Why Rust on the Wii U?
+# Will it every be a real std version?
 
-> I am a Rust developer. Of course, I’ve spent six months rewriting everything in Rust. So let me tell you about it...
+It is highly unlikely that `rust-wiiu` will ever become a fully integrated standard Rust environment. Several aspects of the underlying toolchain are fundamentally incompatible with standard Rust configurations. While a future integration might theoretically be possible given sufficient interest and a dedicated team of contributors, it is not feasible in the foreseeable future. Therefore, `rust-wiiu` will continue to exist as an external toolchain that strives to offer a developer experience (DX) as close as possible to a standard Rust environment.
 
-I was tired of the chaos that is C & C++. Between multiple (often partially incompatible) compilers, countless standards, and enough different ways to write the same functionality to make your head spin, C can feel more like an elaborate trap than a programming language. Add to that the sheer number of opportunities for bugs, and you have a recipe for frustration. Rust, by comparison, feels like a breath of fresh air: modern, well-structured, and designed to make your code both safe and sane.
+Furthermore, the freedom from strict adherence to the standard library (`std`) API can offer significant convenience, particularly for rapid development. While this flexibility might occasionally result in APIs that are less optimal or non-standardized in terms of performance, security, or other aspects, the trade-off in terms of ease and speed of development is often considered worthwhile.
 
-But it’s not just about my personal vendetta against C. C carries the 21ˢᵗ century on its back—and for that, it has my respect. However, I firmly believe that modern languages like Rust have a place ~~even~~ especially on legacy hardware. It lowers the barrier to entry for new developers. Yes, I know Rust isn’t exactly known for being beginner-friendly, but let’s be real: neither is C or C++. At least Rust comes with fantastic default tools for managing packages, formatting, error handling, ... and the compiler is flipping awesome once you develop Stockholm syndrome.
+# How to learn Rust?
 
-Finally, there’s a bigger picture here. By bringing Rust to legacy systems, we’re keeping niche communities alive and ensuring their codebases remain maintainable, readable, and understandable. A lot of the existing homebrew code is based on personal preferences in formatting and coding style, which makes it hard for third parties to follow. Rust offers a path forward with its clean structure by design, excellent tools, and rapidly growing popularity. So whether you’re here for the technical elegance, the nostalgia, or just to try something new, welcome aboard—let’s make something great.
+Start using it. If you have no prior programming experience, it's worth noting that Rust, with its explicit and strict nature (qualities that ultimately contribute to its strength and reliability), might present a steeper initial learning curve compared to some other languages. However, I would never want to discourage anyone from embarking on the journey of learning Rust. To support you in this endeavor, here's a curated list of resources that I personally recommend or that are highly regarded within the Rust community:
 
-# Will it every be a real std version?
+* [Comprehensive Rust 🦀](https://google.github.io/comprehensive-rust/): A complete course about Rust by Google.
+* [The Rust Programming Language](https://doc.rust-lang.org/stable/book/): The "official" Rust book by and for the community 
+* [Rust By Example](https://doc.rust-lang.org/rust-by-example/): Collection of Rust code examples
+
+## Why Rust on the Wii U?
+
+> I am a Rust developer. Of course, I’ve spent six months rewriting everything in Rust. So let me tell you about it...
+
+I was tired of the chaos that is C & C++. The fragmented compiler ecosystem, the ever-evolving standards, and the compiler's tendency to let programmers reek havoc can make C feel less like a language and more like an intricate maze. Add to that the sheer number of opportunities for bugs or undefined behavior, and you have a recipe for frustration. Rust, by comparison, feels like a breath of fresh air: modern, well-structured, and designed to make your code both safe and sane.
+
+But it’s not just about my personal vendetta against C. I firmly believe that modern languages like Rust have a valuable role to play ~~even~~ especially on legacy hardware. They lowers the barrier to entry for new developers. Okay, I know Rust has a reputation for a steeper learning curve, but at least Rust comes with fantastic default tools for managing packages, formatting, error handling, ... and the compiler is flipping awesome once you develop Stockholm syndrome.
 
-Most likely not - unless tremendous effort is done and the external dependencies are at least reduced, to make a more standalone toolchain. It currently depends on other crates and external C tooling. *Maybe* oneday if the interest is high enough and there are enough contributers to make it feasable. But for the forseeable future, `rust-wiiu` remains an external tool which just trys to have a DX similar to the a std environment.
+Ultimately, there's a bigger vision here. By introducing Rust to legacy environments, we can help sustain niche communities and ensure their codebases remain manageable, readable, and understandable. So much existing homebrew code reflects individual formatting and coding styles, making it challenging for others to contribute. Rust, with its inherent clean structure, great tooling, and increasing popularity, offers a promising path forward. So, whether you're drawn by the technical sophistication, the desire for a bit of nostalgia, or simply the curiosity to explore something new, welcome—let's build something great together.

src/getting-started.md

@@ -46,50 +46,52 @@ use wut;
 use wut::prelude::*;
 use wut::time::Duration;
 
-#[no_mangle]
+#[wut_main(Console)]
 fn main() {
-    wut::process::default();
-
     while wut::process::running() {
         println!("{:?}", wut::time::now());
         wut::thread::sleep(Duration::from_secs(1));
     }
-
-    wut::process::exit();
 }
 ```
 
 Let's digest this code part by part:
 
 #### 1. `!#[no_std]`
 
-The Wii U / CafeOS does now have official Rust support; who could have guessed? Rust, by default, assumes that you are on a "typical" platform like x86-linux, ARM-windows, AppleSilicon, etc[^1]. There exist 3 stages of features programmers can use with Rust: core, alloc, std. This enabled Rust to be used at every level of the software stack; from bootloaders to websites.
+The Wii U / CafeOS does now have official Rust support; who could have guessed? Rust, by default, assumes that you are on a "typical" platform like x86-linux, ARM-windows, AppleSilicon, etc[^1]. There exist 3 stages of feature sets programmers can use with Rust: core, alloc, std. This enables Rust to be used at every level of the software stack; from bootloader to websites.
 
-std is the "default" and used when on a typical platform and provides the entire Rust std library with platform specific implemtations. So no matter if you are on a UNIX or Windows system, `std::path` will just work. alloc is one level lower and provides a interface to and allocator. This basically means that the system has a heap and can make use of dynamic allocations (malloc, strings, vectors, ...). However, as this still requires some platform dependent code, a even lower level exist: core. Here, only base Rust functions exist (no platform dependence or dynamic allocations); meaning only stack-based memory can be used.
+[`std`](https://doc.rust-lang.org/std/index.html) is the "default" and used when on a typical platform and provides the entire Rust std library with platform specific implementations. So no matter if you are on a UNIX or Windows system, `std::path` will just work. [`alloc`](https://doc.rust-lang.org/alloc/index.html) is one level lower and provides a interface to and allocator. This basically means that the system has a heap and can make use of dynamic allocations (malloc, strings, vectors, ...). However, as this still requires some platform dependent code, a even lower level exist: [`core`](https://doc.rust-lang.org/core/index.html). Here, only base Rust functions exist (no platform dependence or dynamic allocations); meaning only stack-based memory can be used.
 
 So wait a minutes, does this mean at rust-wiiu doesn't even support `String`?! Calm down, rust-wiiu is way more close to a official supported platform (in form of programmer usage) than that might suggest. rust-wiiu defines a custom allocator and implements most of the relevant std-features, so you can use existing Rust knowledge. Still, the compiler/linker has to be informed about this "unusual environment".
 
 #### 2. `!#[no_main]`
 
-Also an embedded rust macro. This special macro tells the linker to not create a main function. This is needed because the `fn main()` isn't the first thing that get's ran during program execution. Lots of other functions run beforehand, to setup heaps, forward arguments, etc. devkitPro has it's own pre-main instructions, so we need to tell Rust to not do it's otherwise useful magic.
+Also an embedded rust macro. This special macro tells the linker to not create a main function. This is needed because the `fn main()` isn't the first thing that get's ran during program execution. Lots of other functions run beforehand, to setup heaps, forward arguments, etc. devkitPro has it's own pre-main instructions, so we need to tell Rust to not use it's otherwise useful magic.
 
 #### 3. `use ...`
 
 These are your well known Rust import statements. Nothing unusual about them. The "wut" library contains the functionalities of rust-wiiu and `prelude::*` is to "import common stuff"[^2].
 
-It should be mentioned that `wut::time::Duration` is the **same** thing as `std::time::Duration`. Both are just reexports of `core::time::Duration`, which contains the actual implementations. Wut, like std, exports the entire `core` module for convinience and a single point of access.
+It should be mentioned that `wut::time::Duration` is the **same** thing as `std::time::Duration`. Both are just reexports of `core::time::Duration`, which contains the actual implementations. Wut, like std, exports the entire `core` module for convenience and a single point of access.
 
-#### 4. `!#[no_mangle]`
+<!-- #### 4. `!#[no_mangle]`
 
-This macro is commonly used when interacting with forein functions, e.g. functions compiled in C[^3]. It disables [Name Mangeling](https://wikipedia.org/wiki/Name_mangling), which is a technique to make function names truly unique by changing them at compile time. This is normally not a problem (and actual wanted), but the devkitPro toolchain searches for a symbol named "main" during compiling/linking, so mangeling this name will make the main function indetectable.
+This macro is commonly used when interacting with foreign functions, e.g. functions compiled in C[^3]. It disables [Name Mangeling](https://wikipedia.org/wiki/Name_mangling), which is a technique to make function names truly unique by changing them at compile time. This is normally not a problem (and actual wanted), but the devkitPro toolchain searches for a symbol named "main" during compiling/linking, so mangling this name will make the main function indetectable.
 
 #### 5. `wut::process::default()`
 
-This function sets up some functionalities for wut. It does some thing similar, but not exlusively, to the stuff that would run pre-main. There are some configuration you could do by running `wut::process:new()` instead, but you can read the documentation for that. For now, it is required and you can mostly just ignore it.
+This function sets up some functionalities for wut. It does some thing similar, but not exlusively, to the stuff that would run pre-main. There are some configuration you could do by running `wut::process:new()` instead, but you can read the documentation for that. For now, it is required and you can mostly just ignore it. -->
+
+#### 4. `!#[wut_main(Console)]`
+
+Here the magic of rust-wiiu begins. This macro sets up some stuff not necessarily needed for the program to work but to make it behave more like a std environment. You can look up the documentation, but TL;DR it initializes a logger, cleaner exit, etc. This macro can be replaced with some other code and just a convenience.
+
+The most important thing for now is the attribute given to the macro, `Console`. This will result in a on screen console (which will conflict with on screen rendering btw). This is especially useful for early testing. The attribute can be omitted, changed or combined with other logger. Check the documentation for more info. 
 
 #### 6. `while wut::process::running() {…}`
 
-This is what in game development is called the "game loop". Here, the main code of the program is ran in an "infinite" loop. It would also be valid to write
+This is a normal main loop. Here, the main code of the program is ran in an "infinite" loop. It would also be valid to write
 
 ```rust
 loop {
@@ -100,20 +102,16 @@ loop {
 }
 ```
 
-The important thing is that during an infinite loop `wut::process::running()` is called somewhat frequently, as it is required for the HOME button to function (or more precisely, to move the app out of the foreground). This means, if you have the main thread blocking is some way, the app cannot be closed.
+The important thing is that during an infinite loop `wut::process::running()` is called somewhat frequently, as it is required for the foreground release, i.e. the HOME button,  to function (or more precisely, to move the app out of the foreground). This means, if you have the main thread blocking is some way, the app cannot be closed.
 
 #### 7. `println!(…)`
 
-What's so special about `println!()`? Nothing really, but since it deals with strings, it is normally defined by std. It is part of the "common stuff" imported via `wut::prelude::*`. Also, it's one of the things configurable via `wut::process::new()`.
+What's so special about `println!()`? Nothing really, but since it deals with strings, it is normally defined by std. It is part of the "common stuff" imported via `wut::prelude::*` (and gets setup with the `wut_main(Console)` macro).
 
 #### 8. `wut::time::now() & wut::thread::sleep()`
 
 These are examples of std features which are implemented in wut. They (should) behave like their std siblings.
 
-#### 9. `wut::process::exit()`
-
-This is like `wut::process:default()` but for exiting the app. It's required to clean up everything.
-
 ## Time to modify
 
 You now know all the basics of writing Rust code on the Wii U. Now it's time to get your hands dirty and try to implement whatever you want to implement. You can take a look at the documentation to see what std-like features are available and which additional tools are available like `wut::screen` for drawing simple(!) graphics or `wut::gamepad` for controller inputs.