ctest: improve documentation and remove some unused items.

Author: mbyx

ctest/Cargo.toml

@@ -10,7 +10,7 @@ publish = true
 [dependencies]
 askama = "0.14.0"
 cc = "1.2.29"
-proc-macro2 = { version = "1.0.95", features = ["span-locations"] }
+proc-macro2 = { version = "1.0.101", features = ["span-locations"] }
 quote = "1.0.40"
 syn = { version = "2.0.104", features = ["full", "visit", "extra-traits"] }
 thiserror = "2.0.12"

ctest/README.md

@@ -10,7 +10,7 @@ APIs in Rust match the APIs defined in C.
 
 ## MSRV (Minimum Supported Rust Version)
 
-The MSRV is 1.63.0 because of the transitive dependencies.
+The MSRV is 1.88.0 because of the transitive dependencies.
 Note that MSRV may be changed anytime by dependencies.
 
 ## Example
@@ -34,7 +34,7 @@ mylib-sys = { path = "../mylib-sys" }
 libc = "0.2"
 
 [build-dependencies]
-ctest = "0.4"
+ctest = "0.5.0-beta.0"
 ```
 
 Next, add a build script to `systest/build.rs`:
@@ -52,7 +52,7 @@ fn main() {
 
     // Generate the tests, passing the path to the `*-sys` library as well as
     // the module to generate.
-    cfg.generate("../mylib-sys/lib.rs", "all.rs");
+    ctest::generate_test(&mut cfg, "../mylib-sys/lib.rs", "all.rs");
 }
 ```
 
@@ -72,10 +72,10 @@ directory, and everything should be kicked into action!
 
 ## How it works
 
-This library will parse the `*-sys` crate to learn about all extern fn
-definitions within. It will then generate a test suite to ensure that all
-function function signatures, constant values, struct layout/alignment, type
-size/alignment, etc, all match their C equivalent.
+This library will parse the `*-sys` crate to learn about all definitions within.
+It will then generate a test suite to ensure that all function signatures,
+constant values, struct layout/alignment, type size/alignment, etc,
+all match their C equivalent.
 
 The generated tests come in two forms. One is a Rust file which contains the
 `main` function (hence the `include!` above), and another is a C file which is
@@ -101,6 +101,14 @@ This project is licensed under either of
 
 at your option.
 
+## Modifying test templates
+If you modify the test templates for either Rust or C in any way, then before
+contributing you must run the following command to update the pre-generated test
+files we check against:
+```rust
+$ LIBC_BLESS=1 cargo test
+```
+
 ## Contribution
 
 Unless you explicitly state otherwise, any contribution intentionally submitted

ctest/src/ast/constant.rs

@@ -6,8 +6,6 @@ pub struct Const {
     pub(crate) public: bool,
     pub(crate) ident: BoxStr,
     pub(crate) ty: syn::Type,
-    #[expect(unused)]
-    pub(crate) expr: syn::Expr,
 }
 
 impl Const {

ctest/src/ast/mod.rs

@@ -48,24 +48,3 @@ impl fmt::Display for Abi {
         }
     }
 }
-
-/// Things that can appear directly inside of a module or scope.
-///
-/// This is not an exhaustive list and only contains variants directly useful
-/// for our purposes.
-#[derive(Debug, Clone)]
-#[expect(unused)]
-pub(crate) enum Item {
-    /// Represents a constant defined in Rust.
-    Const(Const),
-    /// Represents a function defined in Rust.
-    Fn(Box<Fn>),
-    /// Represents a static variable defined in Rust.
-    Static(Static),
-    /// Represents a type alias defined in Rust.
-    Type(Type),
-    /// Represents a struct defined in Rust.
-    Struct(Struct),
-    /// Represents a union defined in Rust.
-    Union(Union),
-}

ctest/src/cdecl.rs

@@ -2,8 +2,7 @@
 
 use std::fmt::Write;
 
-type BoxStr = Box<str>;
-
+/// The constness of a C type.
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub(crate) enum Constness {
     Const,
@@ -13,6 +12,8 @@ pub(crate) enum Constness {
 #[cfg_attr(not(test), expect(unused_imports))]
 use Constness::{Const, Mut};
 
+use crate::BoxStr;
+
 /// A basic representation of C's types.
 #[derive(Clone, Debug)]
 pub(crate) enum CTy {
@@ -175,6 +176,7 @@ fn space_if(yes: bool, s: &mut String) {
     }
 }
 
+/// Create a named type with a certain constness.
 pub(crate) fn named(name: &str, constness: Constness) -> CTy {
     CTy::Named {
         name: name.into(),
@@ -186,6 +188,7 @@ pub(crate) fn named(name: &str, constness: Constness) -> CTy {
     }
 }
 
+/// Create a named type with certain qualifiers.
 #[cfg_attr(not(test), expect(unused))]
 pub(crate) fn named_qual(name: &str, qual: Qual) -> CTy {
     CTy::Named {
@@ -194,6 +197,7 @@ pub(crate) fn named_qual(name: &str, qual: Qual) -> CTy {
     }
 }
 
+/// Create a pointer to a type, specifying constness of the pointer.
 pub(crate) fn ptr(inner: CTy, constness: Constness) -> CTy {
     ptr_qual(
         inner,
@@ -205,21 +209,23 @@ pub(crate) fn ptr(inner: CTy, constness: Constness) -> CTy {
     )
 }
 
+/// Create a pointer to a type, specifying the qualifiers of the pointer.
 pub(crate) fn ptr_qual(inner: CTy, qual: Qual) -> CTy {
     CTy::Ptr {
         ty: Box::new(inner),
         qual,
     }
 }
 
+/// Create an array of some type and optional length.
 pub(crate) fn array(inner: CTy, len: Option<&str>) -> CTy {
     CTy::Array {
         ty: Box::new(inner),
         len: len.map(Into::into),
     }
 }
 
-/// Function type (not a pointer)
+/// Create a function type (not a pointer) with the given arguments and return type.
 #[cfg_attr(not(test), expect(unused))]
 pub(crate) fn func(args: Vec<CTy>, ret: CTy) -> CTy {
     CTy::Fn {
@@ -228,7 +234,9 @@ pub(crate) fn func(args: Vec<CTy>, ret: CTy) -> CTy {
     }
 }
 
-/// Function pointer
+/// Create a function pointer with the given arguments and return type.
+///
+/// By default the function pointer is mutable, with `volatile` and `restrict` keywords not applied.
 pub(crate) fn func_ptr(args: Vec<CTy>, ret: CTy) -> CTy {
     CTy::Ptr {
         ty: Box::new(CTy::Fn {

ctest/src/ffi_items.rs

@@ -1,3 +1,5 @@
+//! Conversion of Rust code to a simplified abstract syntax tree.
+
 use std::ops::Deref;
 
 use syn::punctuated::Punctuated;
@@ -208,14 +210,8 @@ impl<'ast> Visit<'ast> for FfiItems {
         let public = is_visible(&i.vis);
         let ident = i.ident.to_string().into_boxed_str();
         let ty = i.ty.deref().clone();
-        let expr = i.expr.deref().clone();
 
-        self.constants.push(Const {
-            public,
-            ident,
-            ty,
-            expr,
-        });
+        self.constants.push(Const { public, ident, ty });
     }
 
     fn visit_item_foreign_mod(&mut self, i: &'ast syn::ItemForeignMod) {

ctest/src/generator.rs

@@ -1,3 +1,5 @@
+//! Configuration of the test generator.
+
 use std::env;
 use std::fs::File;
 use std::io::Write;
@@ -15,8 +17,8 @@ use crate::{
     VolatileItemKind, expand,
 };
 
-/// A function that takes a mappable input and returns its mapping as Some, otherwise
-/// use the default name if None.
+/// A function that takes a mappable input and returns its mapping as `Some`, otherwise
+/// use the default name if `None`.
 type MappedName = Box<dyn Fn(&MapInput) -> Option<String>>;
 /// A function that determines whether to skip an item or not.
 type Skip = Box<dyn Fn(&MapInput) -> bool>;
@@ -52,16 +54,22 @@ pub struct TestGenerator {
     pub(crate) skip_fn_ptrcheck: Option<SkipTest>,
 }
 
+/// An error that occurs when generating the test files.
 #[derive(Debug, Error)]
 pub enum GenerationError {
+    /// An error that occurs when `rustc -Zunpretty=expand` fails to expand the crate.
     #[error("unable to expand crate {0}: {1}")]
     MacroExpansion(PathBuf, String),
+    /// An error that occurs when `syn` is unable to parse the expanded crate due to invalid syntax.
     #[error("unable to parse expanded crate {0}: {1}")]
     RustSyntax(String, String),
+    /// An error that occurs when the Rust to C translation fails.
     #[error("unable to prepare template input: {0}")]
     Translation(#[from] TranslationError),
+    /// An error that occurs when there are errors in the Rust side of the test template.
     #[error("unable to render Rust template: {0}")]
     RustTemplateRender(askama::Error),
+    /// An error that occurs when there are errors in the C side of the test template.
     #[error("unable to render C template: {0}")]
     CTemplateRender(askama::Error),
     #[error("unable to create or write template file: {0}")]
@@ -78,7 +86,7 @@ impl TestGenerator {
 
     /// Add a header to be included as part of the generated C file.
     ///
-    /// The generate C test will be compiled by a C compiler, and this can be
+    /// The generated C test will be compiled by a C compiler, and this can be
     /// used to ensure that all the necessary header files are included to test
     /// all FFI definitions.
     ///

ctest/src/lib.rs

@@ -2,7 +2,7 @@
 #![warn(unreachable_pub)]
 #![warn(missing_debug_implementations)]
 
-//! # ctest2 - an FFI binding validator
+//! # ctest - an FFI binding validator
 //!
 //! This library is intended to be used as a build dependency in a separate
 //! project from the main repo to generate tests which can be used to validate
@@ -33,6 +33,9 @@ pub type Result<T, E = Error> = std::result::Result<T, E>;
 /// A boxed string for representing identifiers.
 type BoxStr = Box<str>;
 
+/// The edition used by rustc when expanding macros and compiling tests.
+pub(crate) const EDITION: &str = "2021";
+
 /// A kind of item to which the C volatile qualifier could apply.
 ///
 /// This is necessary because `ctest` does not parse the header file, so it

ctest/src/macro_expansion.rs

@@ -3,7 +3,7 @@ use std::fs::canonicalize;
 use std::path::Path;
 use std::process::Command;
 
-use crate::Result;
+use crate::{EDITION, Result};
 
 /// Use rustc to expand all macros and pretty print the crate into a single file.
 pub fn expand<P: AsRef<Path>>(crate_path: P, cfg: &[(String, Option<String>)]) -> Result<String> {
@@ -13,7 +13,7 @@ pub fn expand<P: AsRef<Path>>(crate_path: P, cfg: &[(String, Option<String>)]) -
     cmd.env("RUSTC_BOOTSTRAP", "1")
         .arg("-Zunpretty=expanded")
         .arg("--edition")
-        .arg("2021") // By default, -Zunpretty=expanded uses 2015 edition.
+        .arg(EDITION) // By default, -Zunpretty=expanded uses 2015 edition.
         .arg(canonicalize(crate_path)?);
 
     // `libc` uses non standard cfg flags as well, which have to be manually expanded.

ctest/src/runner.rs

@@ -1,11 +1,13 @@
+//! Generation, compilation, and running of tests.
+
 use std::env;
 use std::fs::{File, canonicalize};
 use std::io::Write;
 use std::path::{Path, PathBuf};
 use std::process::Command;
 
 use crate::generator::GenerationError;
-use crate::{Result, TestGenerator};
+use crate::{EDITION, Result, TestGenerator};
 
 /// Generate all tests for the given crate and output the Rust side to a file.
 #[doc(hidden)]
@@ -122,10 +124,9 @@ pub fn __compile_test(
         .arg(format!("-Lnative={}", output_dir.display()))
         .arg(format!("-lstatic={}", library_file.to_str().unwrap()))
         .arg("--edition")
-        .arg("2021") // Defaults to 2015.
+        .arg(EDITION) // Defaults to 2015.
         .arg("-o")
-        .arg(&binary_path)
-        .arg("-Aunused");
+        .arg(&binary_path);
 
     // Pass in a different target, linker or flags if set, useful for cross compilation.