68 lines
2.9 KiB
Markdown
68 lines
2.9 KiB
Markdown
libcsp-rust
|
|
=========
|
|
|
|
This project aims to provide libraries and tools to use
|
|
[`libcsp`](https://github.com/libcsp/libcsp) in your Rust project.
|
|
|
|
It provides 2 crates for this:
|
|
|
|
- [`libcsp-cargo-build`] provides an API to build the `libcsp` using `cargo` with the
|
|
[`cc`](https://docs.rs/cc/latest/cc/) crate.
|
|
- [`libcsp-rust`] provides the Rust bindings to `libcsp` and a safe and ergonomic Rust interface.
|
|
|
|
In addition, it provides a workspace to allow updating the `libcsp` and the corresponding bindings
|
|
more easily inside the `lib` directory. Some of the examples `libcsp` provides were ported to Rust
|
|
and are showcases in the `examples` directory.
|
|
|
|
## How it works
|
|
|
|
We assume that cargo should also take care of building the library.
|
|
|
|
1. Add the `libcsp-cargo-build` as a build dependency inside your `Cargo.toml`.
|
|
2. Add the `libcsp-rust` as a regular dependency inside your `Cargo.toml`.
|
|
3. Create a custom `build.rs` script which takes care of building `libcsp` using the API
|
|
provided by `libcsp-cargo-build`. You have to provide the source code for `libcsp` inside some
|
|
directory and pass that director to a builder API.
|
|
4. You can now write regular Rust code and use the API provided by `libcsp-rust` to use `libcsp`
|
|
in a safe and Rusty way.
|
|
|
|
It is recommended to have a look at the [example build script]() which should give you a general
|
|
idea of how a build script might look like to integrate `libcsp`.
|
|
|
|
## Running the example
|
|
|
|
The example uses both the builder crate and the bindings and API crate and implements the
|
|
[server/client example](https://github.com/libcsp/libcsp/blob/develop/examples/csp_server_client.c)
|
|
in Rust. You can run the example using the following steps:
|
|
|
|
1. Clone `libcsp` into the `lib` folder, for example by using the provided `lib/clone-csp.sh`
|
|
script.
|
|
2. You can now use `cargo run -p examples` to run the server/client example.
|
|
|
|
## Generating and update the bindings using the `lib` folder
|
|
|
|
The `lib` folder in this repository serves as the staging directory for the `libcsp` library to
|
|
build. However, it can also be used to update the bindings provided in `libcsp-rust` by providing
|
|
some tools and helpers to auto-generate and update the bindings file `bindings.rs`.
|
|
|
|
If you want to do this, you should install `bindgen-cli` first:
|
|
|
|
```sh
|
|
cargo install bindgen-cli --locked
|
|
```
|
|
|
|
`bindgen` needs some additional information provided by the user to generate the bindings:
|
|
An `autoconfig.h` file which is used to configure `libcsp`. Normally, this file is generated
|
|
by the C build system. This file is located at `cfg/csp` and is also updated automatically
|
|
when running the example application.
|
|
|
|
After cloning the repository, you can now run the following command to re-generate the bindings
|
|
file:
|
|
|
|
```sh
|
|
bindgen --use-core wrapper.h -- "-I./libcsp/include" "-I./cfg" "-I./libcsp/src" > bindings.rs
|
|
```
|
|
|
|
With the bindings file, you can now manually update the FFI bindings provided in
|
|
`libcsp-rust/src/ffi.rs` or in your own CSP library.
|