From aaf3d4c514bdae60f18e340f749768fa3c033934 Mon Sep 17 00:00:00 2001 From: angie Date: Fri, 15 Dec 2023 14:44:53 -0300 Subject: [PATCH] changelog and readme --- CHANGELOG.md | 13 +++++++++++ README.md | 56 +++++++++++++++++++++++++++++++++++++--------- src/rs/checksum.rs | 4 ---- 3 files changed, 58 insertions(+), 15 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 7a837fc..1bf82d9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +### Added + +- Add Rust support +- New static method `CICKind.fromHashMd5`. + - Returns a CIC kind based on the passed md5 hash. + +### Changed + +- Library was reimplemented in Rust, allowing faster runtime calculation. + - The Python API is still the same + +### Fixed + - Fix links in `CHANGELOG.md` ## [1.0.1] - 2023-09-21 diff --git a/README.md b/README.md index 127d633..d668f55 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,10 @@ -# ipl3checksum ![PyPI - Downloads] ![GitHub License] ![GitHub release (latest SemVer)] ![PyPI] ![GitHub contributors] +# ipl3checksum + +![PyPI - Downloads] +![GitHub License] +![GitHub release (latest SemVer)] +![PyPI] +![GitHub contributors] [PyPI - Downloads]: [GitHub License]: @@ -6,7 +12,7 @@ [PyPI]: [GitHub contributors]: -A Python library to calculate the IPL3 checksum for N64 ROMs. +A Python and Rust library to calculate the IPL3 checksum for N64 ROMs. ## How to use it? @@ -17,7 +23,10 @@ romBytes = # A big endian bytes-like object cickind = ipl3checksum.CICKind.CIC_6102_7101 checksum = ipl3checksum.calculateChecksum(romBytes, cickind) -assert checksum is not None # Not able to compute the checksum, probably because rom was too small + +# If this assert fails it is because the library was not able to compute the +# checksum, probably because the passed rom was too small +assert checksum is not None print(f"{checksum[0]:08X}") print(f"{checksum[1]:08X}") @@ -27,7 +36,8 @@ This library also contains a CIC detector: ```py cickind = ipl3checksum.detectCIC(romBytes) -print(cickind) # Either a `ipl3checksum.CICKind` or None if was not able to detect the CIC +# Either a `ipl3checksum.CICKind` or None if was not able to detect the CIC +print(cickind) ``` ## Features @@ -36,6 +46,7 @@ print(cickind) # Either a `ipl3checksum.CICKind` or None if was not able to dete - Can calculate the checksum of a ROM using the algorithm of any of the supported CIC variants. - Can detect any of the supported CIC variants. +- Fast calculation written in Rust. ### Restrictions/requirements @@ -44,10 +55,13 @@ supported CIC variants. - Since the checksum algorithm is calculated on the first MiB after IPL3 (from `0x1000` to `0x101000`), then the library expects the passed ROM to be at least `0x101000` bytes long, otherwise the library will reject the ROM. - - If it is not the case, then pad your ROM with zeroes to that size. + - If your ROM is not big enough then it is suggested then pad your ROM with + zeroes until it reaches that size. ## Installing +### Python version + First you need to install the library, one way of doing it is via `pip`. ```bash @@ -58,21 +72,25 @@ If you use a `requirements.txt` file in your repository, then you can add this library with the following line: ```txt -ipl3checksum>=1.0.0,<2.0.0 +ipl3checksum>=1.1.0,<2.0.0 `````` Now you can invoke the library from your script. -### Development version +#### Development version -The unstable development version is located at the [develop](https://github.com/Decompollaborate/ipl3checksum/tree/develop) +The unstable development version is located at the +[develop](https://github.com/Decompollaborate/ipl3checksum/tree/develop) branch. PRs should be made into that branch instead of the main one. -The recommended way to install a locally cloned repo is by passing the `-e` -(editable) flag to `pip`. +Since this library uses Rust code then you'll need a Rust compiler installed +on your system. To build the Python bindings you'll also need `maturin` +installed via `pip`. + +The recommended way to install a locally cloned repo the following. ```bash -python3 -m pip install -e . +python3 -m pip install . ``` In case you want to mess with the latest development version without wanting to @@ -86,6 +104,22 @@ python3 -m pip install git+https://github.com/Decompollaborate/ipl3checksum.git@ NOTE: Installing the development version is not recommended unless you know what you are doing. Proceed at your own risk. +### Rust version + +See this crate at . + +To add this library to your project using Cargo: + +```bash +cargo add ipl3checksum +``` + +Or add the following line manually to your `Cargo.toml` file: + +```toml +ipl3checksum = "1.1.0" +``` + ## Versioning and changelog This library follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html). diff --git a/src/rs/checksum.rs b/src/rs/checksum.rs index 64c1077..daf39cd 100644 --- a/src/rs/checksum.rs +++ b/src/rs/checksum.rs @@ -212,11 +212,7 @@ pub fn calculate_checksum_autodetect(rom_bytes: &[u8]) -> Option<(u32, u32)> { #[cfg(test)] mod tests { - //use rstest::rstest; - //use std::path::PathBuf; - use std::fs; - use crate::{cickinds::CICKind, utils}; #[test]