From 8e74ca26e0d2148108ecfba1ea07baff9da124d8 Mon Sep 17 00:00:00 2001 From: Robin Mueller Date: Sat, 1 Jun 2024 01:14:40 +0200 Subject: [PATCH] clean up --- Cargo.toml | 3 - README.md | 32 +++++++++-- examples/autoconfig.h | 1 + examples/autoconfig.rs | 1 + lib/cfg/csp/autoconfig.h | 1 + libcsp-cargo-build/Cargo.toml | 9 ++- libcsp-cargo-build/README.md | 6 +- libcsp-cargo-build/src/lib.rs | 104 +++++++++++++++++----------------- libcsp-rust/Cargo.toml | 8 +++ libcsp-rust/README.md | 20 +++++++ 10 files changed, 120 insertions(+), 65 deletions(-) create mode 100644 libcsp-rust/README.md diff --git a/Cargo.toml b/Cargo.toml index 83e08e1..97acdf7 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,8 +1,5 @@ [workspace] - members = [ "libcsp-cargo-build", "libcsp-rust", "examples" ] - - resolver = "2" diff --git a/README.md b/README.md index 8a22aa3..28ff65e 100644 --- a/README.md +++ b/README.md @@ -6,9 +6,10 @@ This project aims to provide libraries and tools to use 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. +- [`libcsp-cargo-build`](https://egit.irs.uni-stuttgart.de/rust/libcsp-rust/src/branch/main/libcsp-cargo-build) + provides an API to build the `libcsp` using `cargo` with the [`cc`](https://docs.rs/cc/latest/cc/) crate. +- [`libcsp-rust`](https://egit.irs.uni-stuttgart.de/rust/libcsp-rust/src/branch/main/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 @@ -22,12 +23,12 @@ We assume that cargo should also take care of building the library. 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. + directory and pass the directory path 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`. +It is recommended to have a look at the [example build script](https://egit.irs.uni-stuttgart.de/rust/libcsp-rust/src/branch/main/examples/build.rs) +which should give you a general idea of how a build script might look like to integrate `libcsp`. ## Running the example @@ -39,6 +40,24 @@ in Rust. You can run the example using the following steps: script. 2. You can now use `cargo run -p examples` to run the server/client example. +## Compile-time configuration of the `libcsp-rust` library + +The `libcsp-rust` library 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](https://egit.irs.uni-stuttgart.de/rust/libcsp-rust/src/branch/main/examples/autoconfig.rs). +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`] 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: + +```toml +[env] +CSP_CONFIG_DIR = { value = "examples", relative = true } +``` + ## 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 @@ -65,3 +84,4 @@ bindgen --use-core wrapper.h -- "-I./libcsp/include" "-I./cfg" "-I./libcsp/src" 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. + diff --git a/examples/autoconfig.h b/examples/autoconfig.h index 78c8887..823f616 100644 --- a/examples/autoconfig.h +++ b/examples/autoconfig.h @@ -1,3 +1,4 @@ +// This file was auto-generated by the libcsp-cargo-build library #define CSP_POSIX 1 #define CSP_ZEPHYR 0 diff --git a/examples/autoconfig.rs b/examples/autoconfig.rs index e68ed1c..f343643 100644 --- a/examples/autoconfig.rs +++ b/examples/autoconfig.rs @@ -1,3 +1,4 @@ +// This file was auto-generated by the libcsp-cargo-build library pub const CSP_CONN_RXQUEUE_LEN: usize = 16; pub const CSP_QFIFO_LEN: usize = 16; pub const CSP_PORT_MAX_BIND: usize = 16; diff --git a/lib/cfg/csp/autoconfig.h b/lib/cfg/csp/autoconfig.h index 78c8887..823f616 100644 --- a/lib/cfg/csp/autoconfig.h +++ b/lib/cfg/csp/autoconfig.h @@ -1,3 +1,4 @@ +// This file was auto-generated by the libcsp-cargo-build library #define CSP_POSIX 1 #define CSP_ZEPHYR 0 diff --git a/libcsp-cargo-build/Cargo.toml b/libcsp-cargo-build/Cargo.toml index f07e35a..c96deec 100644 --- a/libcsp-cargo-build/Cargo.toml +++ b/libcsp-cargo-build/Cargo.toml @@ -2,8 +2,13 @@ name = "libcsp-cargo-build" version = "0.1.0" edition = "2021" - -[lib] +description = "Tools to build libcsp using cargo" +homepage = "https://egit.irs.uni-stuttgart.de/rust/libcsp-rust" +repository = "https://egit.irs.uni-stuttgart.de/rust/libcsp-rust" +license = "Apache-2.0" +keywords = ["no-std", "space", "aerospace", "ffi", "csp"] +# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html +categories = ["aerospace", "external-ffi-bindings", "no-std", "hardware-support", "embedded"] [dependencies] cc = "1" diff --git a/libcsp-cargo-build/README.md b/libcsp-cargo-build/README.md index ea802c4..cf840f4 100644 --- a/libcsp-cargo-build/README.md +++ b/libcsp-cargo-build/README.md @@ -3,5 +3,7 @@ libcsp-cargo-build This crate provides a library to allow building the [`libcsp`](https://github.com/libcsp/libcsp) with cargo. You can find some more high-level information and examples in the -[main workspace](https://egit.irs.uni-stuttgart.de/rust/libcsp-rust). The API documentation -should provide all additional advanced information you might require to tweak the `libcsp` build. +[main workspace](https://egit.irs.uni-stuttgart.de/rust/libcsp-rust). + +The API documentation should provide all additional advanced information you might require to tweak +the `libcsp` build. diff --git a/libcsp-cargo-build/src/lib.rs b/libcsp-cargo-build/src/lib.rs index f678ed2..5aeccb8 100644 --- a/libcsp-cargo-build/src/lib.rs +++ b/libcsp-cargo-build/src/lib.rs @@ -3,31 +3,31 @@ use std::{ path::{Path, PathBuf}, }; -pub mod autoconf { - pub const CFG_POSIX: &str = "CSP_POSIX"; - pub const CFG_ZEPHYR: &str = "CSP_ZEPHYR"; +pub mod cfg_keys { + pub const POSIX: &str = "CSP_POSIX"; + pub const ZEPHYR: &str = "CSP_ZEPHYR"; - pub const CFG_HAVE_STDIO: &str = "CSP_HAVE_STDIO"; - pub const CFG_ENABLE_CSP_PRINT: &str = "CSP_ENABLE_CSP_PRINT"; - pub const CFG_PRINT_STDIO: &str = "CSP_PRINT_STDIO"; + pub const HAVE_STDIO: &str = "CSP_HAVE_STDIO"; + pub const ENABLE_CSP_PRINT: &str = "CSP_ENABLE_CSP_PRINT"; + pub const PRINT_STDIO: &str = "CSP_PRINT_STDIO"; - pub const CFG_REPRODUCIBLE_BUILDS: &str = "CSP_REPRODUCIBLE_BUILDS"; + pub const REPRODUCIBLE_BUILDS: &str = "CSP_REPRODUCIBLE_BUILDS"; - pub const CFG_QFIFO_LEN: &str = "CSP_QFIFO_LEN"; - pub const CFG_PORT_MAX_BIND: &str = "CSP_PORT_MAX_BIND"; - pub const CFG_CONN_RXQUEUE_LEN: &str = "CSP_CONN_RXQUEUE_LEN"; - pub const CFG_CONN_MAX: &str = "CSP_CONN_MAX"; - pub const CFG_BUFFER_SIZE: &str = "CSP_BUFFER_SIZE"; - pub const CFG_BUFFER_COUNT: &str = "CSP_BUFFER_COUNT"; - pub const CFG_RDP_MAX_WINDOW: &str = "CSP_RDP_MAX_WINDOW"; - pub const CFG_RTABLE_SIZE: &str = "CSP_RTABLE_SIZE"; + pub const QFIFO_LEN: &str = "CSP_QFIFO_LEN"; + pub const PORT_MAX_BIND: &str = "CSP_PORT_MAX_BIND"; + pub const CONN_RXQUEUE_LEN: &str = "CSP_CONN_RXQUEUE_LEN"; + pub const CONN_MAX: &str = "CSP_CONN_MAX"; + pub const BUFFER_SIZE: &str = "CSP_BUFFER_SIZE"; + pub const BUFFER_COUNT: &str = "CSP_BUFFER_COUNT"; + pub const RDP_MAX_WINDOW: &str = "CSP_RDP_MAX_WINDOW"; + pub const RTABLE_SIZE: &str = "CSP_RTABLE_SIZE"; - pub const CFG_USE_RDP: &str = "CSP_USE_RDP"; - pub const CFG_USE_HMAC: &str = "CSP_USE_HMAC"; - pub const CFG_USE_PROMISC: &str = "CSP_USE_PROMISC"; - pub const CFG_USE_RTABLE: &str = "CSP_USE_RTABLE"; - pub const CFG_HAVE_LIBSOCKETCAN: &str = "CSP_HAVE_LIBSOCKETCAN"; - pub const CFG_HAVE_LIBZMQ: &str = "CSP_HAVE_LIBZMQ"; + pub const USE_RDP: &str = "CSP_USE_RDP"; + pub const USE_HMAC: &str = "CSP_USE_HMAC"; + pub const USE_PROMISC: &str = "CSP_USE_PROMISC"; + pub const USE_RTABLE: &str = "CSP_USE_RTABLE"; + pub const HAVE_LIBSOCKETCAN: &str = "CSP_HAVE_LIBSOCKETCAN"; + pub const HAVE_LIBZMQ: &str = "CSP_HAVE_LIBZMQ"; } const SRCS_LIST: &[&str] = &[ @@ -219,103 +219,101 @@ impl Builder { pub fn generate_autoconf_header_file(out_dir: impl AsRef, cfg: &Config) -> io::Result<()> { let out_dir = out_dir.as_ref(); let mut autoconf_file_string = String::new(); + autoconf_file_string + .push_str("// This file was auto-generated by the libcsp-cargo-build library\n"); #[cfg(unix)] autoconf_file_string.push_str("#define CSP_POSIX 1\n"); autoconf_file_string.push_str("#define CSP_ZEPHYR 0\n"); autoconf_file_string.push('\n'); autoconf_file_string.push_str(&format!( "#define {} {}\n", - autoconf::CFG_HAVE_STDIO, + cfg_keys::HAVE_STDIO, cfg.have_stdio as u32 )); autoconf_file_string.push_str(&format!( "#define {} {}\n", - autoconf::CFG_ENABLE_CSP_PRINT, + cfg_keys::ENABLE_CSP_PRINT, cfg.csp_print as u32 )); autoconf_file_string.push_str(&format!( "#define {} {}\n", - autoconf::CFG_PRINT_STDIO, + cfg_keys::PRINT_STDIO, cfg.print_stdio as u32 )); autoconf_file_string.push_str(&format!( "#define {} {}\n", - autoconf::CFG_REPRODUCIBLE_BUILDS, + cfg_keys::REPRODUCIBLE_BUILDS, cfg.reproducible_builds as u32 )); autoconf_file_string.push('\n'); autoconf_file_string.push_str(&format!( "#define {} {}\n", - autoconf::CFG_QFIFO_LEN, + cfg_keys::QFIFO_LEN, cfg.qfifo_len )); autoconf_file_string.push_str(&format!( "#define {} {}\n", - autoconf::CFG_PORT_MAX_BIND, + cfg_keys::PORT_MAX_BIND, cfg.port_max_bind )); autoconf_file_string.push_str(&format!( "#define {} {}\n", - autoconf::CFG_CONN_RXQUEUE_LEN, + cfg_keys::CONN_RXQUEUE_LEN, cfg.conn_rx_queue_len )); autoconf_file_string.push_str(&format!( "#define {} {}\n", - autoconf::CFG_CONN_MAX, + cfg_keys::CONN_MAX, cfg.conn_max )); autoconf_file_string.push_str(&format!( "#define {} {}\n", - autoconf::CFG_BUFFER_SIZE, + cfg_keys::BUFFER_SIZE, cfg.buffer_size )); autoconf_file_string.push_str(&format!( "#define {} {}\n", - autoconf::CFG_BUFFER_COUNT, + cfg_keys::BUFFER_COUNT, cfg.buffer_count )); autoconf_file_string.push_str(&format!( "#define {} {}\n", - autoconf::CFG_RDP_MAX_WINDOW, + cfg_keys::RDP_MAX_WINDOW, cfg.rdp_max_window )); autoconf_file_string.push_str(&format!( "#define {} {}\n", - autoconf::CFG_RTABLE_SIZE, + cfg_keys::RTABLE_SIZE, cfg.rtable_size )); autoconf_file_string.push('\n'); autoconf_file_string.push_str(&format!( "#define {} {}\n", - autoconf::CFG_USE_RDP, + cfg_keys::USE_RDP, cfg.rdp as u32 )); autoconf_file_string.push_str(&format!( "#define {} {}\n", - autoconf::CFG_USE_HMAC, + cfg_keys::USE_HMAC, cfg.hmac as u32 )); autoconf_file_string.push_str(&format!( "#define {} {}\n", - autoconf::CFG_USE_PROMISC, + cfg_keys::USE_PROMISC, cfg.promisc as u32 )); autoconf_file_string.push_str(&format!( "#define {} {}\n", - autoconf::CFG_USE_RTABLE, + cfg_keys::USE_RTABLE, cfg.rtable as u32 )); autoconf_file_string.push('\n'); - // TODO: Maybe those will be added at some point.. - autoconf_file_string.push_str(&format!( - "#define {} {}\n", - autoconf::CFG_HAVE_LIBSOCKETCAN, - 0 - )); - autoconf_file_string.push_str(&format!("#define {} {}\n", autoconf::CFG_HAVE_LIBZMQ, 0)); + // TODO: Maybe those will be added at some point.. For now, they are hardcoded to 0. + autoconf_file_string.push_str(&format!("#define {} {}\n", cfg_keys::HAVE_LIBSOCKETCAN, 0)); + autoconf_file_string.push_str(&format!("#define {} {}\n", cfg_keys::HAVE_LIBZMQ, 0)); let out_file = out_dir.join("autoconfig.h"); let mut file = std::fs::File::create(out_file)?; file.write_all(autoconf_file_string.as_bytes())?; @@ -325,39 +323,41 @@ pub fn generate_autoconf_header_file(out_dir: impl AsRef, cfg: &Config) -> pub fn generate_autoconf_rust_file(out_dir: impl AsRef, cfg: &Config) -> io::Result<()> { let out_dir = out_dir.as_ref(); let mut autoconf_file_string = String::new(); + autoconf_file_string + .push_str("// This file was auto-generated by the libcsp-cargo-build library\n"); autoconf_file_string.push_str(&format!( "pub const {}: usize = {};\n", - autoconf::CFG_CONN_RXQUEUE_LEN, + cfg_keys::CONN_RXQUEUE_LEN, cfg.conn_rx_queue_len )); autoconf_file_string.push_str(&format!( "pub const {}: usize = {};\n", - autoconf::CFG_QFIFO_LEN, + cfg_keys::QFIFO_LEN, cfg.qfifo_len )); autoconf_file_string.push_str(&format!( "pub const {}: usize = {};\n", - autoconf::CFG_PORT_MAX_BIND, + cfg_keys::PORT_MAX_BIND, cfg.port_max_bind )); autoconf_file_string.push_str(&format!( "pub const {}: usize = {};\n", - autoconf::CFG_CONN_MAX, + cfg_keys::CONN_MAX, cfg.conn_max )); autoconf_file_string.push_str(&format!( "pub const {}: usize = {};\n", - autoconf::CFG_BUFFER_SIZE, + cfg_keys::BUFFER_SIZE, cfg.buffer_size )); autoconf_file_string.push_str(&format!( "pub const {}: usize = {};\n", - autoconf::CFG_RDP_MAX_WINDOW, + cfg_keys::RDP_MAX_WINDOW, cfg.rdp_max_window )); autoconf_file_string.push_str(&format!( "pub const {}: usize = {};\n", - autoconf::CFG_RTABLE_SIZE, + cfg_keys::RTABLE_SIZE, cfg.rtable_size )); let out_file = out_dir.join("autoconfig.rs"); @@ -368,5 +368,5 @@ pub fn generate_autoconf_rust_file(out_dir: impl AsRef, cfg: &Config) -> i #[cfg(test)] mod tests { - // TODO: Unittest autoconf generator. + // TODO: Unittest autoconf generators. } diff --git a/libcsp-rust/Cargo.toml b/libcsp-rust/Cargo.toml index 3038ebe..72b8ffd 100644 --- a/libcsp-rust/Cargo.toml +++ b/libcsp-rust/Cargo.toml @@ -2,6 +2,14 @@ name = "libcsp-rust" version = "0.1.0" edition = "2021" +authors = ["Robin Mueller "] +description = "FFI bindings and a safe Rust API for libcsp" +homepage = "https://egit.irs.uni-stuttgart.de/rust/libcsp-rust" +repository = "https://egit.irs.uni-stuttgart.de/rust/libcsp-rust" +license = "Apache-2.0" +keywords = ["no-std", "space", "aerospace", "ffi", "csp"] +# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html +categories = ["aerospace", "external-ffi-bindings", "no-std", "hardware-support", "embedded"] links = "csp" [dependencies] diff --git a/libcsp-rust/README.md b/libcsp-rust/README.md new file mode 100644 index 0000000..438afc2 --- /dev/null +++ b/libcsp-rust/README.md @@ -0,0 +1,20 @@ +libcsp-rust +======== + +This crate provides Rust FFI bindings and a Rusty API for the [`libcsp` library](https://github.com/libcsp/libcsp). +You can find some more high-level information and examples in the +[main workspace](https://egit.irs.uni-stuttgart.de/rust/libcsp-rust). + +The API documentation should provide all additional information required to use this library. + +## Compile-time configuration of the `libcsp-rust` library + +The `libcsp-rust` library 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](https://egit.irs.uni-stuttgart.de/rust/libcsp-rust/src/branch/main/examples/autoconfig.rs). +The user has to provide the path to a directory containing this `autoconfig.rs` file using the +`CSP_CONFIG_DIR` environmental variable. + +It is recommended to read the [main workspace README](https://egit.irs.uni-stuttgart.de/rust/libcsp-rust) +for more information to make the generation and specification of this auto-configuration file +as conveniently and easy as possible.