libcsp-rust/README.md

libcsp-rust

This project aims to provide libraries and tools to build and use the libcsp C library in your Rust project.

It provides 3 crates for this:

• libcsp provides a safe and ergonomic Rust interface on top of the libcsp-sys crate.
• libcsp-sys provides the Rust bindings to libcsp.
• libcsp-cargo-build provides an API to build the libcsp using cargo with the cc crate.

In addition, it provides a workspace to allow updating the libcsp C sources and the corresponding bindings more easily inside the clib directory. Some of the examples libcsp provides were ported to Rust and are showcased in the examples directory.

Please note that this is early-stage/experimental software. Important features might be missing. PRs and improvement suggestions are welcome! This project was primarily tested on a Linux/POSIX system so far.

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 as a regular dependency inside your Cargo.toml.
3. Create a custom build.rs script which takes care of building the libcsp C library using the API provided by libcsp-cargo-build. You have to provide the source code for libcsp inside some directory and pass the directory path to the builder API.
4. You can now write regular Rust code and use the Rust API provided by the libcsp crate to use the libcsp C library.

It is recommended to have a look at the example build script which should give you a general idea of how a build script which does the 4 steps above might look like.

Running the example

The example uses both the builder crate and the bindings and API crate and implements the server/client example in Rust. You can run the example using the following steps:

1. Clone/Copy libcsp into the lib folder, for example by using the provided lib/clone-csp.sh script or adding libcsp as a git submodule.
2. You can now use cargo run -p libcsp-rust-examples to run the server/client example.

Compile-time configuration of the libcsp-sys library

The libcsp-sys requires some compile-time configuration file to be included to work properly. You can see an example version of the file for the workspace here. The user has to provide the path to a directory containing this autoconfig.rs file using the CSP_CONFIG_DIR environmental variable.

You can automatically generate this file when using libcsp-cargo-build by using the [generate_autoconf_rust_file](here be link soon) method of the Builder object as done in the example build script.

In this workspace, the CSP_CONFIG_DIR variable is hardcoded using the following .cargo/config.toml configuration:

[env]
CSP_CONFIG_DIR = { value = "examples", relative = true }

Generating and update the bindings using the clib 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-sys 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:

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 clib/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:

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-sys/src/lib.rs or in your own CSP library.