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.
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.gitInstall Rust:
- Install the Rust Toolchain.
Setup IDE
- This repository is fully with VSCode. Guidance below.
Code/VSCode is the de-facto Rust development environment.
The following extensions are required:
- rust-analyzer for Rust support.
- coverage-gutters for Coverage support.
- CodeLLDB for debugging.
- crates easier dependency management.
The VSCode configuration in Reloaded projects (.vscode) contain the following:
- Run Rust linter
clippyon Save. - Run code format
rustfmton 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.
First install or update tarpaulin:
cargo install cargo-tarpaulinTo 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).
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.
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.
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.
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.
- Add
"cdylib"crate type toCargo.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.
Individual projects are under the projects folder; they contain the following:
reloaded-hooks-portable: Core engine ofReloaded.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 theReloaded.Hookspackages.
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.
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.
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-gnuNow when you run cargo build, it will build code for all platforms; and you'll get your compiler errors, warnings etc.
- Install Docker Desktop.
- Disable WSL 2 (Docker Desktop -> Settings -> General -> Use the WSL 2 based engine).
- Install Podman from your package manager.
Install cross
cargo install cross
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.
See CONTRIBUTING for guidance on how to contribute to this project.
Licensed under GPL V3 w/ Reloaded FAQ, the default for Reloaded project.
Learn more about Reloaded's choice of licensing..