wslpluginapi-sys 0.2.0+2.4.4

Rust bindings for the WSL Plugin API
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55

# wslpluginapi-sys

[![Crates.io](https://img.shields.io/crates/v/wslpluginapi-sys?logo=rust)](https://crates.io/crates/wslpluginapi-sys)  
[![Docs.rs](https://img.shields.io/badge/docs.rs-wslpluginapi--sys-blue?logo=docs.rs)](https://docs.rs/wslpluginapi-sys)  
[![Build Status](https://github.com/mveril/wslpluginapi-sys/actions/workflows/ci.yml/badge.svg?logo=github)](https://github.com/mveril/wslpluginapi-sys/actions)  
[![License](https://img.shields.io/badge/license-MIT-blue.svg?logo=license)](LICENSE)  
[![Native API version](https://img.shields.io/badge/Microsoft.WSL.PluginApi-2.4.4-blue?logo=nuget)](https://www.nuget.org/packages/Microsoft.WSL.PluginApi/2.4.4)  
[![Platform](https://img.shields.io/badge/platform-Windows-blue?logo=windows&logoColor=white)](#)

`wslpluginapi-sys` is a Rust crate that provides low-level bindings to the Windows Subsystem for Linux (WSL) Plugin API. It offers a direct interface to the functions and structures defined in the WSL Plugin API, facilitating the development of WSL plugins in Rust.

## Features

- **Comprehensive Bindings**: Provides complete bindings to the WSL Plugin API, including structures like `WSLPluginAPIV1` or `WSLPluginHooksV1` and other essential components.  
- **Unsafe Abstractions**: Direct, unsafe bindings closely mirroring the original C API for maximum control and flexibility.

## Prerequisites

Before using `wslpluginapi-sys`, ensure you have the following installed:
- **Rust**: Latest stable version.


## Installation

Add `wslpluginapi-sys` to your `Cargo.toml`:

```toml
[dependencies]
wslpluginapi-sys = "0.1.0-beta.4+2.4.4"
```

## Safety

This crate provides unsafe bindings that closely follow the original C API. Users must ensure they uphold the necessary safety invariants when interacting with these bindings. Proper handling of pointers, memory management, and adherence to the API's expected usage patterns are crucial.

## NuGet package dependency

This project depends on a third-party dependency called [Microsoft.WSL.PluginApi](https://www.nuget.org/packages/Microsoft.WSL.PluginApi) from Microsoft, available on NuGet and providing bindings for it. 
## xtask bindgen
To upgrade it, change the version build metadata of the project to the target `Microsoft.WSL.PluginApi` version and run `cargo xtask bindgen` (don't forget to commit changes generated from the xtask). This xtask download the nuget package and run bindgen on the header to compute a rust file used as binding. This allow offline build with no need of the windows header at build time. All the output of this task is added to a `build` folder that need to be commit This folder contain a metadata file and a checksum file.
The information of this metadata file and checksum file are used at build time to detect the path of the binding and check the integrity (corect checksum and version correspondance).

### Requirement

To run this command you require the following dependencies
- llvm
- rustfmt (from rustup)
- Nuget CLI


## License

This project is Licensed under either MIT or Apache-2.0, at your option. See the LICENSE file for details.

Note: This crate is part of the [WSLPlugins-rs](https://github.com/mveril/wslplugins-rs) project, which aims to create an idiomatic Rust framework for developing WSL plugins.