improve error handling

CHANGELOG.md

@@ -8,6 +8,10 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 
 # [unreleased]
 
+# [v0.1.3] 2024-06-01
+
+Fixed documentation build.
+
 # [v0.1.2] 2024-06-01
 
 Restructured crate to be the root package of a workspace.

Cargo.lock

@@ -44,7 +44,7 @@ checksum = "97b3888a4aecf77e811145cadf6eef5901f4782c53886191b2f693f24761847c"
 
 [[package]]
 name = "libcsp"
-version = "0.1.2"
+version = "0.1.3"
 dependencies = [
  "bitflags",
  "libc",
@@ -54,18 +54,10 @@ dependencies = [
 
 [[package]]
 name = "libcsp-cargo-build"
-version = "0.1.0"
-dependencies = [
- "cc",
-]
-
-[[package]]
-name = "libcsp-cargo-build"
-version = "0.1.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "554733e90f35324f10e32b4e848f5c85eb28cd099c5015d9fbe869f3b5a59944"
+version = "0.2.0"
 dependencies = [
  "cc",
+ "thiserror",
 ]
 
 [[package]]
@@ -73,12 +65,12 @@ name = "libcsp-rust-examples"
 version = "0.1.0"
 dependencies = [
  "libcsp",
- "libcsp-cargo-build 0.1.0 (registry+https://github.com/rust-lang/crates.io-index)",
+ "libcsp-cargo-build",
 ]
 
 [[package]]
 name = "libcsp-sys"
-version = "0.1.0"
+version = "0.1.1"
 dependencies = [
  "libc",
 ]
@@ -148,6 +140,26 @@ dependencies = [
  "unicode-ident",
 ]
 
+[[package]]
+name = "thiserror"
+version = "1.0.61"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c546c80d6be4bc6a00c0f01730c08df82eaa7a7a61f11d656526506112cc1709"
+dependencies = [
+ "thiserror-impl",
+]
+
+[[package]]
+name = "thiserror-impl"
+version = "1.0.61"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "46c3384250002a6d5af4d114f2845d37b57521033f30d5c3f46c4d70e1197533"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
 [[package]]
 name = "toml_datetime"
 version = "0.6.6"

Cargo.toml

@@ -1,6 +1,13 @@
+[workspace]
+members = [
+    "libcsp-cargo-build",
+    "examples"
+]
+resolver = "2"
+
 [package]
 name = "libcsp"
-version = "0.1.2"
+version = "0.1.3"
 edition = "2021"
 authors = ["Robin Mueller <muellerr@irs.uni-stuttgart.de>"]
 description = "Safe and ergonomic Rust API for libcsp on top on libcsp-sys"
@@ -16,10 +23,3 @@ bitflags = "2"
 num_enum = "0.7"
 libc = "0.2"
 libcsp-sys = { version = "0.1", path = "libcsp-sys" }
-
-[workspace]
-members = [
-    "libcsp-cargo-build",
-    "examples"
-]
-resolver = "2"

README.md

@@ -1,3 +1,6 @@
+[![Crates.io](https://img.shields.io/crates/v/libcsp)](https://crates.io/crates/libcsp)
+[![docs.rs](https://img.shields.io/docsrs/libcsp)](https://docs.rs/libcsp)
+
 libcsp-rust
 =========
 

clib/cfg/csp/autoconfig.h

@@ -1,4 +1,4 @@
-// This file was auto-generated by libcsp-cargo-build v0.1.0
+// This file was auto-generated by libcsp-cargo-build v0.2.0
 #define CSP_POSIX 1
 #define CSP_ZEPHYR 0
 

examples/Cargo.toml

@@ -4,7 +4,9 @@ version = "0.1.0"
 edition = "2021"
 
 [dependencies]
+# Must use local verion here, otherwise there will be multiple versions of `libcsp-sys`, and
+# cargo can not deal with this due to the link section.
 libcsp = { version = "0.1", path = ".." }
 
 [build-dependencies]
-libcsp-cargo-build = "0.1"
+libcsp-cargo-build = { version = "0.2", path = "../libcsp-cargo-build" }

examples/autoconfig.h

@@ -1,4 +1,4 @@
-// This file was auto-generated by libcsp-cargo-build v0.1.0
+// This file was auto-generated by libcsp-cargo-build v0.2.0
 #define CSP_POSIX 1
 #define CSP_ZEPHYR 0
 

examples/autoconfig.rs

@@ -1,4 +1,4 @@
-// This file was auto-generated by libcsp-cargo-build v0.1.0
+// This file was auto-generated by libcsp-cargo-build v0.2.0
 pub const CSP_CONN_RXQUEUE_LEN: usize = 16;
 pub const CSP_QFIFO_LEN: usize = 16;
 pub const CSP_PORT_MAX_BIND: usize = 16;

examples/build.rs

@@ -11,7 +11,8 @@ fn main() {
 
     // This helper structure will take care of the majority of work to compile libcsp using the
     // cc crate.
-    let mut csp_builder = Builder::new(PathBuf::from(libcsp_path), PathBuf::from(&out_dir));
+    let mut csp_builder = Builder::new(PathBuf::from(libcsp_path), PathBuf::from(&out_dir))
+        .expect("creating libcsp builder failed");
     // A lot of spam we are not interested in usually.
     csp_builder.compiler_warnings = false;
 

examples/src/lib.rs

@@ -1 +0,0 @@
-

libcsp-cargo-build/CHANGELOG.md

@@ -8,6 +8,10 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 
 # [unreleased]
 
+# [v0.2.0] 2024-06-01
+
+Added basic sanity checks for the user-provided `libcsp` location.
+
 # [v0.1.0] 2024-06-01
 
 Initial release

libcsp-cargo-build/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "libcsp-cargo-build"
-version = "0.1.0"
+version = "0.2.0"
 edition = "2021"
 description = "Tools to build libcsp using cargo"
 homepage = "https://egit.irs.uni-stuttgart.de/rust/libcsp-rust"
@@ -12,3 +12,4 @@ categories = ["aerospace", "external-ffi-bindings", "no-std", "hardware-support"
 
 [dependencies]
 cc = "1"
+thiserror = "1"

libcsp-cargo-build/README.md

@@ -1,3 +1,6 @@
+[![Crates.io](https://img.shields.io/crates/v/libcsp-cargo-build)](https://crates.io/crates/libcsp-cargo-build)
+[![docs.rs](https://img.shields.io/docsrs/libcsp-cargo-build)](https://docs.rs/libcsp-cargo-build)
+
 libcsp-cargo-build
 ========
 

libcsp-cargo-build/src/lib.rs

@@ -133,12 +133,34 @@ pub struct Builder {
     build: cc::Build,
 }
 
+#[derive(Debug, Copy, Clone, PartialEq, Eq, thiserror::Error)]
+pub enum BuildCreationError {
+    #[error("The specified libcsp path does not exist")]
+    PathDoesNotExist,
+    #[error("The specified libcsp path does not have the expected format of the library")]
+    InvalidLibcspFormat,
+}
+
 impl Builder {
-    /// Create a new builder instance.
-    pub fn new(libcsp_path: PathBuf, out_dir: PathBuf) -> Self {
+    /// Create a new builder instance. Returns [BuildCreationError] if the specified libcsp path
+    /// does not exist or does not have the expected format.
+    pub fn new(libcsp_path: PathBuf, out_dir: PathBuf) -> Result<Self, BuildCreationError> {
+        // Basic sanity checks for the passed libcsp path.
+        if !libcsp_path.exists() {
+            return Err(BuildCreationError::PathDoesNotExist);
+        }
+        if !libcsp_path
+            .join("include")
+            .join("csp")
+            .join("csp.h")
+            .exists()
+        {
+            return Err(BuildCreationError::InvalidLibcspFormat);
+        }
+
         let mut libcsp_src_path_base = libcsp_path.clone();
         libcsp_src_path_base.push("src");
-        Self {
+        Ok(Self {
             generate_autoconf_file: true,
             libcsp_path,
             libcsp_src_path_base,
@@ -146,7 +168,7 @@ impl Builder {
             cfg: Default::default(),
             compiler_warnings: true,
             build: Default::default(),
-        }
+        })
     }
 
     /// Access to the underlying [cc::Build] builder object.

libcsp-sys/CHANGELOG.md

@@ -8,6 +8,10 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 
 # [unreleased]
 
+# [v0.1.1] 2024-06-01
+
+Try to fix the documentation build.
+
 # [v0.1.0] 2024-06-01
 
 Initial release

libcsp-sys/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "libcsp-sys"
-version = "0.1.0"
+version = "0.1.1"
 edition = "2021"
 authors = ["Robin Mueller <muellerr@irs.uni-stuttgart.de>"]
 description = "FFI bindings for libcsp"

libcsp-sys/README.md

@@ -1,3 +1,6 @@
+[![Crates.io](https://img.shields.io/crates/v/libcsp-sys)](https://crates.io/crates/libcsp-sys)
+[![docs.rs](https://img.shields.io/docsrs/libcsp-sys)](https://docs.rs/libcsp-sys)
+
 libcsp-sys
 ========
 

libcsp-sys/build.rs

@@ -15,19 +15,24 @@ fn main() {
         println!("cargo:rustc-link-lib=csp");
     }
 
-    let out_path = env::var("OUT_DIR").unwrap();
-    let csp_conf_dir = match env::var(ENV_KEY_CSP_CONFIG_DIR) {
-        Ok(conf_path) => conf_path,
-        Err(_e) => {
-            println!(
+    let mut csp_conf_path = if std::env::var("DOCS_RS").is_ok() {
+        PathBuf::from("./templates")
+    } else {
+        match env::var(ENV_KEY_CSP_CONFIG_DIR) {
+            Ok(conf_path) => conf_path.into(),
+            Err(_e) => {
+                println!(
                 "cargo:warning={} not set, using CARGO_MANIFEST_DIR to search for autoconfig.rs",
                 ENV_KEY_CSP_CONFIG_DIR
             );
-            env::var("CARGO_MANIFEST_DIR").expect("CARGO_MANIFEST_DIR not set")
+                env::var("CARGO_MANIFEST_DIR")
+                    .expect("CARGO_MANIFEST_DIR not set")
+                    .into()
+            }
         }
     };
-    let mut csp_conf_path = PathBuf::new();
-    csp_conf_path.push(csp_conf_dir);
+
+    let out_path = env::var("OUT_DIR").unwrap();
     csp_conf_path.push("autoconfig.rs");
     if !csp_conf_path.exists() {
         panic!(