Browse Source

New READMEs and fixed package labeling

pull/134/head
Andrea Ciliberti 1 year ago
parent
commit
10f70aa026
  1. 28
      README.md
  2. 23
      ctru-rs/README.md
  3. 9
      ctru-rs/src/lib.rs
  4. 2
      ctru-rs/src/services/am.rs
  5. 4
      ctru-rs/src/services/mod.rs
  6. 2
      ctru-rs/src/services/romfs.rs
  7. 33
      ctru-sys/README.md

28
README.md

@ -1,33 +1,27 @@
# ctru-rs # 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 ## Structure
This repository is organized as follows: 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` Specific information about how to use the crates is present in the individual README for each package.
used to generate the bindings, with the following convention: Have a look at `ctru-rs`' [README.md](./ctru-rs/README.md) for a broad overview.
* `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.
## Original version ## Original version
This project is based on the efforts the original authors: This project is based on the efforts of the original authors:
* [Eidolon](https://github.com/HybridEidolon) * [Eidolon](https://github.com/HybridEidolon)
* [FenrirWolf](https://github.com/FenrirWolf) * [FenrirWolf](https://github.com/FenrirWolf)
The old version is archived [here](https://github.com/rust3ds/ctru-rs-old). The old version is archived [here](https://github.com/rust3ds/ctru-rs-old).
## License
This project is distributed under the Zlib license.

23
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 <example-name>
```
## License
This project is distributed under the Zlib license.

9
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 //! # About
//! //!
@ -6,11 +6,12 @@
//! Thanks to it, developers can access the underlying system services and the console's hardware to develop userland applications //! 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.). //! (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 //! # 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 //! 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). //! 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). /// 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. /// In case it fails to find an active [`Console`](console::Console) the program will just exit.

2
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). //! - Read the installed applications on the console and their information (depending on the install location).
//! - Install compatible applications to the console. //! - 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::error::ResultCode;
use crate::services::fs::FsMediaType; use crate::services::fs::FsMediaType;

4
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, //! 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. //! 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". //! 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 //! 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), //! "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. //! 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 am;
pub mod apt; pub mod apt;

2
ctru-rs/src/services/romfs.rs

@ -21,7 +21,7 @@ use crate::services::ServiceReference;
/// Handle to the RomFS service. /// Handle to the RomFS service.
/// ///
/// This service lets the application access a virtual mounted device created using a folder included within the application bundle. /// 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:/`. /// 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 { pub struct RomFS {

33
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.
Loading…
Cancel
Save