clean up

Cargo.toml

@@ -1,8 +1,5 @@
 [workspace]
-
 members = [
     "libcsp-cargo-build", "libcsp-rust", "examples"
 ]
-
-
 resolver = "2"

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
+- [`libcsp-cargo-build`](https://egit.irs.uni-stuttgart.de/rust/libcsp-rust/src/branch/main/libcsp-cargo-build)
-  [`cc`](https://docs.rs/cc/latest/cc/) crate.
+  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-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
+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)
-idea of how a build script might look like to integrate `libcsp`.
+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.
+

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
 

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;

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
 

libcsp-cargo-build/Cargo.toml

@@ -2,8 +2,13 @@
 name = "libcsp-cargo-build"
 version = "0.1.0"
 edition = "2021"
-
+description = "Tools to build libcsp using cargo"
-[lib]
+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"

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
+[main workspace](https://egit.irs.uni-stuttgart.de/rust/libcsp-rust). 
-should provide all additional advanced information you might require to tweak the `libcsp` build.
+
+The API documentation should provide all additional advanced information you might require to tweak
+the `libcsp` build.

libcsp-cargo-build/src/lib.rs

@@ -3,31 +3,31 @@ use std::{
     path::{Path, PathBuf},
 };
 
-pub mod autoconf {
+pub mod cfg_keys {
-    pub const CFG_POSIX: &str = "CSP_POSIX";
+    pub const POSIX: &str = "CSP_POSIX";
-    pub const CFG_ZEPHYR: &str = "CSP_ZEPHYR";
+    pub const ZEPHYR: &str = "CSP_ZEPHYR";
 
-    pub const CFG_HAVE_STDIO: &str = "CSP_HAVE_STDIO";
+    pub const HAVE_STDIO: &str = "CSP_HAVE_STDIO";
-    pub const CFG_ENABLE_CSP_PRINT: &str = "CSP_ENABLE_CSP_PRINT";
+    pub const ENABLE_CSP_PRINT: &str = "CSP_ENABLE_CSP_PRINT";
-    pub const CFG_PRINT_STDIO: &str = "CSP_PRINT_STDIO";
+    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 QFIFO_LEN: &str = "CSP_QFIFO_LEN";
-    pub const CFG_PORT_MAX_BIND: &str = "CSP_PORT_MAX_BIND";
+    pub const PORT_MAX_BIND: &str = "CSP_PORT_MAX_BIND";
-    pub const CFG_CONN_RXQUEUE_LEN: &str = "CSP_CONN_RXQUEUE_LEN";
+    pub const CONN_RXQUEUE_LEN: &str = "CSP_CONN_RXQUEUE_LEN";
-    pub const CFG_CONN_MAX: &str = "CSP_CONN_MAX";
+    pub const CONN_MAX: &str = "CSP_CONN_MAX";
-    pub const CFG_BUFFER_SIZE: &str = "CSP_BUFFER_SIZE";
+    pub const BUFFER_SIZE: &str = "CSP_BUFFER_SIZE";
-    pub const CFG_BUFFER_COUNT: &str = "CSP_BUFFER_COUNT";
+    pub const BUFFER_COUNT: &str = "CSP_BUFFER_COUNT";
-    pub const CFG_RDP_MAX_WINDOW: &str = "CSP_RDP_MAX_WINDOW";
+    pub const RDP_MAX_WINDOW: &str = "CSP_RDP_MAX_WINDOW";
-    pub const CFG_RTABLE_SIZE: &str = "CSP_RTABLE_SIZE";
+    pub const RTABLE_SIZE: &str = "CSP_RTABLE_SIZE";
 
-    pub const CFG_USE_RDP: &str = "CSP_USE_RDP";
+    pub const USE_RDP: &str = "CSP_USE_RDP";
-    pub const CFG_USE_HMAC: &str = "CSP_USE_HMAC";
+    pub const USE_HMAC: &str = "CSP_USE_HMAC";
-    pub const CFG_USE_PROMISC: &str = "CSP_USE_PROMISC";
+    pub const USE_PROMISC: &str = "CSP_USE_PROMISC";
-    pub const CFG_USE_RTABLE: &str = "CSP_USE_RTABLE";
+    pub const USE_RTABLE: &str = "CSP_USE_RTABLE";
-    pub const CFG_HAVE_LIBSOCKETCAN: &str = "CSP_HAVE_LIBSOCKETCAN";
+    pub const HAVE_LIBSOCKETCAN: &str = "CSP_HAVE_LIBSOCKETCAN";
-    pub const CFG_HAVE_LIBZMQ: &str = "CSP_HAVE_LIBZMQ";
+    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<Path>, 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..
+    // TODO: Maybe those will be added at some point.. For now, they are hardcoded to 0.
-    autoconf_file_string.push_str(&format!(
+    autoconf_file_string.push_str(&format!("#define {} {}\n", cfg_keys::HAVE_LIBSOCKETCAN, 0));
-        "#define {} {}\n",
+    autoconf_file_string.push_str(&format!("#define {} {}\n", cfg_keys::HAVE_LIBZMQ, 0));
-        autoconf::CFG_HAVE_LIBSOCKETCAN,
-        0
-    ));
-    autoconf_file_string.push_str(&format!("#define {} {}\n", autoconf::CFG_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<Path>, cfg: &Config) ->
 pub fn generate_autoconf_rust_file(out_dir: impl AsRef<Path>, 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<Path>, cfg: &Config) -> i
 
 #[cfg(test)]
 mod tests {
-    // TODO: Unittest autoconf generator.
+    // TODO: Unittest autoconf generators.
 }

libcsp-rust/Cargo.toml

@@ -2,6 +2,14 @@
 name = "libcsp-rust"
 version = "0.1.0"
 edition = "2021"
+authors = ["Robin Mueller <muellerr@irs.uni-stuttgart.de>"]
+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]

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.