Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/sewer56/lightweight-mmap
Simple memory mapping helpers for Rust, with minimal amount of code generated. Segmented from NX Archive Library.
https://github.com/sewer56/lightweight-mmap
Last synced: 7 days ago
JSON representation
Simple memory mapping helpers for Rust, with minimal amount of code generated. Segmented from NX Archive Library.
- Host: GitHub
- URL: https://github.com/sewer56/lightweight-mmap
- Owner: Sewer56
- License: mit
- Created: 2024-11-01T23:20:55.000Z (15 days ago)
- Default Branch: main
- Last Pushed: 2024-11-09T00:34:54.000Z (8 days ago)
- Last Synced: 2024-11-09T01:24:57.093Z (8 days ago)
- Language: Rust
- Homepage:
- Size: 76.2 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README-DEV.MD
- Contributing: CONTRIBUTING.MD
- License: LICENSE
Awesome Lists containing this project
README
## Development
How to develop this project.
***Clone this Repository:***
```bash
# When cloning, make sure symlinks are enabled
git clone -c core.symlinks=true https://github.com/Sewer56/lightweight-mmap.git
```
***Install Rust:***
- Install the [Rust Toolchain.][rust-toolchain]
***Setup IDE***
- This repository is fully with VSCode. [Guidance below](#visual-studio-code-integration).
### Visual Studio Code Integration
`Code`/`VSCode` is the de-facto Rust development environment.
The following extensions are required:
- [rust-analyzer][rust-analyzer] for Rust support.
- [coverage-gutters][coverage-gutters] for Coverage support.
- [CodeLLDB][codelldb] for debugging.
- [crates](https://marketplace.visualstudio.com/items?itemName=serayuzgur.crates) easier dependency management.
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`:
```bash
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).
## Building C Libraries Locally
Reloaded-based C libraries are built with `panic=abort` and self-built STD to minimize binary size.
First get the prerequisites (nightly rust).
```
rustup toolchain install nightly
rustup component add rust-src --toolchain nightly
```
To build C library locally, run the following command:
```
RUSTFLAGS="-C panic=abort -C lto=fat -C embed-bitcode=yes" cargo +nightly rustc -Z build-std=std,panic_abort -Z build-std-features=panic_immediate_abort --crate-type cdylib --crate-type staticlib --target x86_64-unknown-linux-gnu
```
Replace `x86_64-unknown-linux-gnu` with your [target triple][target-triple].
## Optimizing for Size when Creating C Libraries
1. Add `"cdylib"` crate type to `Cargo.toml` (temporarily!! do not commit)
```
[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 --features c-exports
```
Change `--target` if needed for your platform.
This should produce binaries more appropriate for dynamic linking from C.
## File Layout
The following is the expected file layout for your project:
```
.vscode/
src/
Cargo.toml
```
The `src` folder should contains all source code for your project.
`Cargo.toml` should be in the root of the 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`.
```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:
```bash
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](https://www.docker.com/products/docker-desktop/).
- Disable WSL 2 (Docker Desktop -> Settings -> General -> Use the WSL 2 based engine).
#### Prerequisites (Linux)
- Install [Podman](https://podman.io) 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.
## Releasing a New Version
Make a tag, aptly named after the current version of the project. For instance, if you are publishing version `0.1.0`, the tag should be `0.1.0`. This will create a GitHub release for you automatically.
## Contributing
See [CONTRIBUTING](CONTRIBUTING.MD) for guidance on how to contribute to this project.
[codelldb]: https://marketplace.visualstudio.com/items?itemName=vadimcn.vscode-lldb
[coverage-gutters]: https://marketplace.visualstudio.com/items?itemName=ryanluker.vscode-coverage-gutters
[target-triple]: https://doc.rust-lang.org/nightly/rustc/platform-support.html
[rust-analyzer]: https://marketplace.visualstudio.com/items?itemName=rust-lang.rust-analyzer
[rust-toolchain]: https://www.rust-lang.org/tools/install