Skip to content

[WIP, NOT YET USABLE] Next Gen no_std Rust rewrite the Reloaded.Hooks library.

License

Notifications You must be signed in to change notification settings

Reloaded-Project/Reloaded.Hooks-rs

Repository files navigation

reloaded-hooks

Crates.io Docs.rs CI

About

Advanced native function hooks for x86, x64. Now in Rust, and cross platform too! You can learn more about this project in the dedicated documentation page.

Development

How to develop this project.

Clone this Repository:

# When cloning, make sure symlinks are enabled
git clone -c core.symlinks=true https://github.com/Reloaded-Project/Reloaded.Hooks-rs.git

Install Rust:

Setup IDE

Visual Studio Code Integration

Code/VSCode is the de-facto Rust development environment.

The following extensions are required:

The VSCode configuration in Reloaded projects (.vscode) contain the following:

  • Run Rust linter clippy on Save.
  • Run code format rustfmt on Save.
  • Tasks for common operations (generate documentation, active CI/CD etc.).

These configurations are in the .vscode folder; and the tasks can be ran via Ctrl+Shift+P -> Run Task.

Test Coverage

First install or update tarpaulin:

cargo install cargo-tarpaulin

To run Coverage, run task (Ctrl+Shift+P -> Run Task), you should see something similar to:

Task Description
Cargo Watch Tarpaulin Automatically runs tests and updates coverage on save.
Generate Code Coverage Manually generate code coverage (cobertura.xml, tarpaulin-report.html)

The tarpaulin-report.html file can be opened in VSCode (Show Preview) for a live view.

For GUI integration, run action Coverage Gutter: Watch (in Ctrl+Shift+P actions menu).

Debugging Benchmarks

If you wish to debug benchmarks in VSCode, go to Run and Debug Menu and generate the launch profiles, you should get one for debugging benchmarks.

Benchmarks with Side Effects

Some benchmarks have side effects, such as assembly_hook_creation in x86 package; which make subsequent runs slower.

In those scenarios, you can run them as such:

cargo bench --bench my_benchmark -- assembly_hook_creation --warm-up-time 0.000000001 --measurement-time 5 --verbose

You will get a printout such as:

Benchmarking assembly_hook_creation: Warming up for 1.0000 ns
Benchmarking assembly_hook_creation: Collecting 100 samples in estimated 52.981 s (80800 iterations)
Benchmarking assembly_hook_creation: Analyzing
assembly_hook_creation  time:   [10.355 µs 10.613 µs 10.833 µs]
                        change: [-5.0994% -1.8940% +1.5054%] (p = 0.28 > 0.05)
                        No change in performance detected.

With this info, you'll find out that for 80800 iterations it takes, 10.613 µs on average, per iteration, or 857ms for all 80800 iterations, if extrapolated.

These benches are disabled by default, re-enable them in source code to run them if desired.

Profiling Benchmarks

Linux/OSX

Execute the following:

cargo bench --bench my_benchmark --profile profile -- --profile-time 10

This should give you a flamegraph in target/criterion/<method_name>/profile. You can open that flamegraph in a web browser.

Windows

Execute the following:

cargo bench --bench my_benchmark --no-run --profile profile

Navigate to the executable listed in the commandline:

target/profile/deps/my_benchmark-eced832ac8f31257.exe

And run with command my_benchmark-eced832ac8f31257.exe --bench --profile-time 10 under an external profiler, such as Visual Studio.

example

Optimizing for Size when Creating C Libraries

  1. Add "cdylib" crate type to Cargo.toml (if not already present)
[lib]
crate-type = ["cdylib"]

Install cargo-bloat, nightly toolchain and build-std:

cargo install cargo-bloat
rustup toolchain install nightly
rustup component add rust-src --toolchain nightly

Run cargo-bloat the following command to calculate package size:

RUSTFLAGS="-C panic=abort -C lto=fat -C embed-bitcode=yes" cargo +nightly bloat -Z build-std=std,panic_abort -Z build-std-features=panic_immediate_abort --target x86_64-pc-windows-gnu --profile profile --crate-type cdylib -n 100

Change --target if needed for your platform.
This should produce binaries more appropriate for dynamic linking from C.

File Layout

Individual projects are under the projects folder; they contain the following:

  • reloaded-hooks-portable: Core engine of Reloaded.Hooks, platform & architecture agnostic.
  • reloaded-hooks-x86-sys: Implements support for x86 & AMD64 architecture.
  • reloaded-hooks-aarch64-sys: Implements support for ARM64 (aarch64) architecture.
  • reloaded-hooks-buffers-common: Improves support on Linux/macOS/Windows by adding targeted memory allocation capabilities. Using reloaded-memory-buffers.
  • reloaded-hooks: High level API for the Reloaded.Hooks packages.

The following is the expected file layout for the repository:

.vscode/
docs/
mkdocs.yml

The docs folder, and mkdocs.yml contain MkDocs Material documentation for your project.

Cross Platform Targeting

Some templates allow for cross platform development.

To work with cross-platform code, where you need to access OS specific APIs, some helper scripts are provided.

Including All Code Paths

To include all code paths for local builds, consider editing .cargo/config.toml.

[build]
# Note: This breaks IntelliJ Rust. Remove this line temporarily if working from that IDE.
target = ['x86_64-unknown-linux-gnu','x86_64-apple-darwin','x86_64-pc-windows-gnu']

You might need to install the targets first:

rustup target add x86_64-unknown-linux-gnu
rustup target add x86_64-apple-darwin
rustup target add x86_64-pc-windows-gnu

Now when you run cargo build, it will build code for all platforms; and you'll get your compiler errors, warnings etc.

Cross Testing on Local Machine

Prerequisites (Windows)

  • Install Docker Desktop.
  • Disable WSL 2 (Docker Desktop -> Settings -> General -> Use the WSL 2 based engine).

Prerequisites (Linux)

  • Install Podman from your package manager.

Prerequisites (Common)

Install cross

cargo install cross

Running Cross-Platform Tests

Use the provided pwsh scripts in scripts folder.

  • ./test-wine-x64.ps1: Tests your code in Wine on x86_64.
  • ./test-linux-x64.ps1: Tests your code in Linux on x86_64.
  • ./test-linux-x86.ps1: Tests your code in Linux on x86.

These scripts can be used on any platform given the prerequisites are met.
If you need to test Apple stuff without an Apple machine, you're generally out of luck outside of using CI/CD for testing.

Contributing

See CONTRIBUTING for guidance on how to contribute to this project.

License

Licensed under GPL V3 w/ Reloaded FAQ, the default for Reloaded project.
Learn more about Reloaded's choice of licensing..

About

[WIP, NOT YET USABLE] Next Gen no_std Rust rewrite the Reloaded.Hooks library.

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages