diff --git a/README.md b/README.md index ae3e6c7..8a061b4 100644 --- a/README.md +++ b/README.md @@ -1,33 +1,27 @@ # ctru-rs -A Rust wrapper around [libctru](https://github.com/devkitPro/libctru). +This repository is home of the `ctru-rs` project, which aims to bring full control of the Nintendo 3DS console to homebrew developers using Rust. ## Structure This repository is organized as follows: -* `ctru-rs`: Safe, idiomatic wrapper around `ctru-sys` + * [`ctru-rs`](./ctru-rs/) - Safe, idiomatic wrapper around [`ctru-sys`](./ctru-sys/). + * [`ctru-sys`](./ctru-sys/) - Low-level, unsafe bindings to [`libctru`](https://github.com/devkitPro/libctru). -* `ctru-sys`: Low-level, unsafe bindings to `libctru`. +## Getting Started - This crate's version changes according to the version of `libctru` - used to generate the bindings, with the following convention: - - * `libctru` version `X.Y.Z-W` - * `ctru-sys` version `XY.Z.P+X.Y.Z-W` - - where `P` is usually 0 but may be incremented for fixes in e.g. - binding generation, `libc` dependency bump, etc. - - It may be possible to build this crate against a different version of `libctru`, - but you may encounter linker errors or ABI issues. A build-time Cargo warning - (displayed when built with `-vv`) will be issued if the build script detects - a mismatch or is unable to check the installed `libctru` version. +Specific information about how to use the crates is present in the individual README for each package. +Have a look at `ctru-rs`' [README.md](./ctru-rs/README.md) for a broad overview. ## Original version -This project is based on the efforts the original authors: - * [Eidolon](https://github.com/HybridEidolon) - * [FenrirWolf](https://github.com/FenrirWolf) +This project is based on the efforts of the original authors: + * [Eidolon](https://github.com/HybridEidolon) + * [FenrirWolf](https://github.com/FenrirWolf) The old version is archived [here](https://github.com/rust3ds/ctru-rs-old). + +## License + +This project is distributed under the Zlib license. diff --git a/ctru-rs/README.md b/ctru-rs/README.md new file mode 100644 index 0000000..297c8cc --- /dev/null +++ b/ctru-rs/README.md @@ -0,0 +1,23 @@ +# ctru-rs + +Safe and idiomatic Rust wrapper around [`libctru`](https://github.com/devkitPro/libctru). +This crate uses the bindings provided by [`ctru-sys`](../ctru-sys/). + +## Getting Started + +Thoroughly read the [`ctru-rs` wiki](https://github.com/rust3ds/ctru-rs/wiki/Getting-Started) to meet the requirements +and to understand what it takes to develop homebrew software on the Nintendo 3DS family of consoles. +After that, you can simply add the crate as a dependency to your project and build your final binary by using [`cargo-3ds`](https://github.com/rust3ds/cargo-3ds) +or by manually compiling for the `armv6k-nintendo-3ds` target. + +## Examples + +Many examples to demonstrate the `ctru-rs` functionality are available in the [`examples`](./examples/) folder. Simply run them via + +```bash +cargo 3ds run --example +``` + +## License + +This project is distributed under the Zlib license. diff --git a/ctru-rs/src/lib.rs b/ctru-rs/src/lib.rs index 37428f8..7e29748 100644 --- a/ctru-rs/src/lib.rs +++ b/ctru-rs/src/lib.rs @@ -1,4 +1,4 @@ -//! Safe wrapper around `libctru`. +//! Safe and idiomatic Rust wrapper around [`libctru`](https://github.com/devkitPro/libctru). //! //! # About //! @@ -6,11 +6,12 @@ //! Thanks to it, developers can access the underlying system services and the console's hardware to develop userland applications //! (such as HID devices, network capabilities, graphics, built-in cameras, etc.). //! -//! Among these features, `ctru` also automatically includes functionality to properly integrate the Rust `std` with the console, which the developer would otherwise need to implement manually. +//! Among these features, `ctru-rs` also automatically includes functionality to properly integrate the Rust `std` with the console's operating system, +//! which the developer would otherwise need to implement manually. //! //! # Usage //! -//! Read thoroughly the official [`ctru` wiki](https://github.com/rust3ds/ctru-rs/wiki) which guides you through the setup needed to install the required toolchain and helpful tools. +//! Read thoroughly the official [`ctru-rs` wiki](https://github.com/rust3ds/ctru-rs/wiki) which guides you through the setup needed to install the required toolchain and helpful tools. //! After following the guide and understanding the many quirks of the Nintendo 3DS homebrew development environment, you can create a new project by including this crate as a dependency //! of your project in your `Cargo.toml` manifest and build your binaries either manually (for the `armv6k-nintendo-3ds` target) or via [`cargo-3ds`](https://github.com/rust3ds/cargo-3ds). //! @@ -57,7 +58,7 @@ macro_rules! from_impl { }; } -/// Activate the custom `ctru` panic handler. +/// Activate the custom `ctru-rs` panic handler. /// /// With this implementation, the main thread will stop and try to print debug info to an available [`Console`](console::Console). /// In case it fails to find an active [`Console`](console::Console) the program will just exit. diff --git a/ctru-rs/src/services/am.rs b/ctru-rs/src/services/am.rs index 9892bd7..31d46b5 100644 --- a/ctru-rs/src/services/am.rs +++ b/ctru-rs/src/services/am.rs @@ -4,7 +4,7 @@ //! - Read the installed applications on the console and their information (depending on the install location). //! - Install compatible applications to the console. //! -//! `ctru` doesn't support installing titles (yet). +//! `ctru-rs` doesn't support installing titles (yet). use crate::error::ResultCode; use crate::services::fs::FsMediaType; diff --git a/ctru-rs/src/services/mod.rs b/ctru-rs/src/services/mod.rs index a387933..ab948b3 100644 --- a/ctru-rs/src/services/mod.rs +++ b/ctru-rs/src/services/mod.rs @@ -3,13 +3,13 @@ //! Most of the 3DS console's functionalities (when writing user-land homebrew) are accessible via services, //! which need to be initialized before accessing any particular feature. //! -//! To ensure safety measures when using the underlying services, `ctru` leverages Rust's lifetime model. +//! To ensure safety measures when using the underlying services, `ctru-rs` leverages Rust's lifetime model. //! After initializing the handle for a specific service (e.g. [`Apt`](apt::Apt)) the service will be accessible as long as there is at least one handle "alive". //! As such, handles should be dropped *after* the use of a specific service. This is particularly important for services which are necessary for functionality //! "outside" their associated methods, such as [`RomFS`](romfs::RomFS), which creates an accessible virtual filesystem, or [`Soc`](soc::Soc), //! which enables all network communications via sockets. //! -//! In `ctru` some services only allow a single handle to be created at a time, to ensure a safe and controlled environment. +//! In `ctru-rs` some services only allow a single handle to be created at a time, to ensure a safe and controlled environment. pub mod am; pub mod apt; diff --git a/ctru-rs/src/services/romfs.rs b/ctru-rs/src/services/romfs.rs index dae4ed3..5d4a64b 100644 --- a/ctru-rs/src/services/romfs.rs +++ b/ctru-rs/src/services/romfs.rs @@ -21,7 +21,7 @@ use crate::services::ServiceReference; /// Handle to the RomFS service. /// /// This service lets the application access a virtual mounted device created using a folder included within the application bundle. -/// `ctru` will include as RomFS the folder specified in the `Cargo.toml` manifest (or use `./romfs` by default). Look at the [`romfs`](self) module for more information. +/// `ctru-rs` will include as RomFS the folder specified in the `Cargo.toml` manifest (or use `./romfs` by default). Look at the [`romfs`](self) module for more information. /// /// After mounting the RomFS file system, the included files and folders will be accessible exactly like any other file, just by using the drive prefix `romfs:/`. pub struct RomFS { diff --git a/ctru-sys/README.md b/ctru-sys/README.md new file mode 100644 index 0000000..280fd83 --- /dev/null +++ b/ctru-sys/README.md @@ -0,0 +1,33 @@ +# ctru-sys + +Raw Rust bindings over the [`libctru`](https://github.com/devkitPro/libctru) C library. + +## Requirements + +To use the bindings provided by this crate you will need to link against the [`libctru`](https://github.com/devkitPro/libctru) library. +Consult the [`ctru-rs` wiki](https://github.com/rust3ds/ctru-rs/wiki/Getting-Started) to learn how to obtain the required packages +to use this library. + +## Version + +This crate's version changes according to the version of `libctru` +used to generate the bindings, with the following convention: + + * [`libctru`](https://github.com/devkitPro/libctru) version `X.Y.Z-W` + * `ctru-sys` version `XY.Z.P+X.Y.Z-W` + + where `P` is usually 0 but may be incremented for fixes in e.g. + binding generation, `libc` dependency bump, etc. + +It may be possible to build this crate against a different version of [`libctru`](https://github.com/devkitPro/libctru), +but you may encounter linker errors or ABI issues. A build-time Cargo warning +(displayed when built with `-vv`) will be issued if the build script detects +a mismatch or is unable to check the installed [`libctru`](https://github.com/devkitPro/libctru) version. + +## Generating bindings + +Bindings of new versions of [`libctru`](https://github.com/devkitPro/libctru) can be built using the integrated [`bindgen.sh`](./bindgen.sh) script. + +## License + +This project is distributed under the Zlib license.