{"id":30895448,"url":"https://github.com/mveril/wslplugins-rs","last_synced_at":"2026-04-01T19:51:28.958Z","repository":{"id":252666717,"uuid":"821738743","full_name":"mveril/wslplugins-rs","owner":"mveril","description":"An idiomatic WSL plugin framework for rust","archived":false,"fork":false,"pushed_at":"2025-07-13T17:52:16.000Z","size":178,"stargazers_count":0,"open_issues_count":2,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-07-13T19:36:19.639Z","etag":null,"topics":["framework","plugin","plugins","rust-library","wsl","wsl2","wsl2-plugin"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mveril.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-06-29T09:47:15.000Z","updated_at":"2025-01-24T18:49:57.000Z","dependencies_parsed_at":"2024-09-13T04:52:50.747Z","dependency_job_id":"349564f2-b74b-4564-bfc4-971fba8a3e9a","html_url":"https://github.com/mveril/wslplugins-rs","commit_stats":null,"previous_names":["mveril/wslplugins-rs"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/mveril/wslplugins-rs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mveril%2Fwslplugins-rs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mveril%2Fwslplugins-rs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mveril%2Fwslplugins-rs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mveril%2Fwslplugins-rs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mveril","download_url":"https://codeload.github.com/mveril/wslplugins-rs/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mveril%2Fwslplugins-rs/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":274231551,"owners_count":25245659,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-08T02:00:09.813Z","response_time":121,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["framework","plugin","plugins","rust-library","wsl","wsl2","wsl2-plugin"],"created_at":"2025-09-08T22:06:14.202Z","updated_at":"2026-04-01T19:51:28.929Z","avatar_url":"https://github.com/mveril.png","language":"Rust","readme":"# WSLPlugins-rs\n\n[![Crates.io](https://img.shields.io/crates/v/wslplugins-rs?logo=rust)](https://crates.io/crates/wslplugins-rs)\n[![Docs.rs](https://img.shields.io/badge/docs.rs-wslplugins--rs-blue?logo=docs.rs)](https://docs.rs/wslplugins-rs)\n[![Build Status](https://github.com/mveril/wslplugins-rs/actions/workflows/rust.yml/badge.svg?logo=github)](https://github.com/mveril/wslplugins-rs/actions)\n[![License: Apache-2.0](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE-APACHE)\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE-MIT)\n[![Platform](https://img.shields.io/badge/platform-Windows-blue?logo=windows\u0026logoColor=white)](#)\n\nWSLPlugins-rs is a Rust framework for building [WSL plugins](https://learn.microsoft.com/windows/wsl/wsl-plugins). It wraps the raw WSL plugin API with safer, more idiomatic Rust types and provides a procedural macro for generating the plugin entry points and hook wiring.\nThe project is intended for Windows hosts that load plugins through WSL. It includes:\n\n- a runtime crate: `wslplugins-rs`\n- a proc-macro crate: `wslplugins-macro`\n- examples that build real plugin DLLs\n\n## Features\n\n- Safe and ergonomic wrappers around the WSL plugin API\n- A `#[wsl_plugin_v1(...)]` macro to generate the exported entry points\n- Support for WSL metadata, session information, and command execution\n- Examples that can be built, signed, and loaded into WSL\n\n## Prerequisites\n\nInstall the following tools on Windows:\n\n- Rust stable and Cargo\n- PowerShell\n- OpenSSL for certificate generation in the signing script\n- `SignTool.exe` from the Windows SDK\n\nNotes:\n\n- `SignTool.exe` is easiest to access from a Visual Studio Developer Command Prompt or a shell where the Windows SDK tools are on `PATH`.\n- Running the signing step with `-Trust` requires administrator privileges because it installs the generated certificate locally.\n\n## Crates\n\n- `wslplugins-rs`: main framework crate\n- `wslplugins-macro`: procedural macro crate re-exported by `wslplugins-rs` when the `macro` feature is enabled\n\n## Quick Start\n\nAdd the crate with the `macro` feature:\n\n```toml\n[dependencies]\nwslplugins-rs = { version = \"0.1.0-beta.1\", features = [\"macro\"] }\n```\n\nThen implement a plugin:\n\n```rust\nuse wslplugins_rs::prelude::*;\n\npub(crate) struct MyPlugin {\n    context: \u0026'static WSLContext,\n}\n\n#[wsl_plugin_v1(2, 0, 5)]\nimpl WSLPluginV1 for MyPlugin {\n    fn try_new(context: \u0026'static WSLContext) -\u003e WinResult\u003cSelf\u003e {\n        Ok(Self { context })\n    }\n}\n```\n\nThe `macro` feature re-exports the `wsl_plugin_v1` attribute and generates the WSL entry points for a `WSLPluginV1` implementation.\n\n## Running Commands in WSL\n\nUse `ApiV1::new_command` to build and execute a Linux command from a plugin session.\n\n```rust\nuse wslplugins_rs::api::{ApiV1, WSLCommandExecution};\nuse wslplugins_rs::SessionID;\n\nfn run_version(api: \u0026ApiV1) -\u003e Result\u003c(), Box\u003cdyn std::error::Error\u003e\u003e {\n    let stream = api\n        .new_command(SessionID::from(0), \"/bin/cat\")\n        .with_arg(\"/proc/version\")\n        .execute()?;\n\n    drop(stream);\n    Ok(())\n}\n```\n\nNotes:\n\n- Program paths must be Linux UTF-8 paths such as `/bin/echo`\n- `argv[0]` defaults to the program path and can be overridden with `with_arg0`\n- `with_distribution_id` targets a specific user distribution\n- `execute()` returns a `TcpStream` connected to process stdin/stdout\n- stderr is forwarded to Linux `dmesg`\n\n## Examples\n\nTwo example plugins are included:\n\n- `examples/minimal`: a close Rust translation of Microsoft's sample plugin\n- `examples/dist-info`: a plugin focused on distribution metadata and tracing\n\nBuild one of them in release mode:\n\n```powershell\ncargo build --release -p minimal\n```\n\nor:\n\n```powershell\ncargo build --release -p dist-info\n```\n\nThe resulting plugin DLLs are produced in `target\\release\\`.\n\n## Signing a Plugin\n\nSign the built DLL with the provided PowerShell script:\n\n```powershell\n.\\sign-plugin.ps1 -PluginPath .\\target\\release\\minimal.dll -Trust\n```\n\nor:\n\n```powershell\n.\\sign-plugin.ps1 -PluginPath .\\target\\release\\dist_info.dll -Trust\n```\n\nIf you do not want to install the certificate automatically, omit `-Trust`.\n\n## Registering the Plugin in WSL\n\nRegister the signed DLL in the WSL plugins registry key:\n\n```cmd\nreg.exe add \"HKLM\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\Lxss\\Plugins\" /v minimal /d \"C:\\path\\to\\wslplugins-rs\\target\\release\\minimal.dll\" /t REG_SZ\n```\n\nAdjust the registry value name and DLL path for the plugin you want to load.\n\nRestart the WSL service after registration:\n\n```cmd\nsc.exe stop wslservice\nsc.exe start wslservice\n```\n\n## Verification\n\nAfter loading the plugin:\n\n- inspect the log output produced by the example\n- verify the DLL path in the registry\n- confirm the DLL was signed successfully\n\nThe `minimal` example writes to `C:\\wsl-plugin-demo.txt`.\n\n## Release Checks\n\nThe repository release workflow is centered on these commands:\n\n```powershell\ncargo test --workspace --all-features\ncargo clippy --workspace --all-targets --all-features\ncargo fmt --all -- --check\ncargo publish --workspace --dry-run\n```\n\n## Contributing\n\nContributions are welcome. Open an issue or submit a pull request with tests and a clear description of the change.\n\n## License\n\nLicensed under either MIT or Apache-2.0.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmveril%2Fwslplugins-rs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmveril%2Fwslplugins-rs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmveril%2Fwslplugins-rs/lists"}