changelog and readme

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

README.md

@@ -1,12 +1,18 @@
-# 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]: <https://img.shields.io/pypi/dm/ipl3checksum>
 [GitHub License]: <https://img.shields.io/github/license/Decompollaborate/ipl3checksum>
 [GitHub release (latest SemVer)]: <https://img.shields.io/github/v/release/Decompollaborate/ipl3checksum>
 [PyPI]: <https://img.shields.io/pypi/v/ipl3checksum>
 [GitHub contributors]: <https://img.shields.io/github/contributors/Decompollaborate/ipl3checksum?logo=purple>
 
-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 <https://crates.io/crates/ipl3checksum>.
+
+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).

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]