Incorporate requested changes

crates/cxx-qt-build/Cargo.toml

@@ -23,7 +23,7 @@ qt-build-utils.workspace = true
 codespan-reporting = "0.11"
 version_check = "0.9"
 scratch = "1.0"
-serde = {version = "1.0", features = ["default", "derive"]}
+serde = { version = "1.0", features = ["default", "derive"] }
 serde_json = "1.0"
 
 [features]

crates/cxx-qt-build/src/dependencies.rs

@@ -145,23 +145,9 @@ impl Interface {
     }
 }
 
-// cxx-qt-lib example
-// Interface {
-//     export_crate_headers: false,
-//     exported_header_prefixes: Some(vec!["cxx-qt-lib/", "python3"]),
-//     generated_path: "cxx-qt-lib-internals",
-// }
-
-// cxx-qt-lib-headers example
-// Interface {
-//     export_crate_headers: true,
-//     exported_header_prefixes: Some(vec!["cxx-qt-lib-extras/..."]),
-//     reexport_links: vec!["cxx-qt-lib"],
-// }
-
 #[derive(Clone, Serialize, Deserialize)]
-// This struct is used by cxx-qt-build internally to propagate data through to downstream
-// dependencies
+/// This struct is used by cxx-qt-build internally to propagate data through to downstream
+/// dependencies
 pub(crate) struct Manifest {
     pub(crate) name: String,
     pub(crate) link_name: String,
@@ -172,12 +158,24 @@ pub(crate) struct Manifest {
 }
 
 #[derive(Clone)]
+/// A dependency that has been set up with [crate::CxxQtBuilder::library] and is available to
+/// the crate that is currently being built.
 pub(crate) struct Dependency {
+    /// The path of the dependencies export directory
     pub(crate) path: PathBuf,
+    /// The deserialized manifest of the dependency
     pub(crate) manifest: Manifest,
 }
 
 impl Dependency {
+    /// This function will search the environment for all dependencies that have been set up with
+    /// CxxQtBuilder::library.
+    /// They export their manifest paths as metadata, which will be exposed to us as an environment
+    /// variable.
+    /// We extract those paths here, parse the manifest and make sure to set it up correctly as a
+    /// dependency.
+    ///
+    /// See also the internals "build system" section of our book.
     pub(crate) fn find_all() -> Vec<Dependency> {
         std::env::vars_os()
             .map(|(var, value)| (var.to_string_lossy().to_string(), value))
@@ -283,12 +281,12 @@ pub(crate) fn all_compile_definitions(
                 }
                 Occupied(entry) => {
                     let existing_value = &entry.get().0;
+                    // Only allow duplicate definitions with the same value
                     if existing_value != value {
                         panic!("Conflicting compiler definitions requested!\nCrate {existing} exports {variable}={existing_value:?}, and crate {conflicting} exports {variable}={value:?}",
                             existing=entry.get().1,
                             conflicting = dependency.manifest.name);
                     }
-                    // else: Ignore Duplicate definition with the same value
                 }
             }
         }

crates/cxx-qt-build/src/lib.rs

@@ -929,9 +929,6 @@ impl CxxQtBuilder {
     /// Generate and compile cxx-qt C++ code, as well as compile any additional files from
     /// [CxxQtBuilder::qobject_header] and [CxxQtBuilder::cc_builder].
     pub fn build(mut self) {
-        // TODO: Clean the directory before we start building
-        // This is currently creating issues with cxx-qt-lib, as cxx-qt-lib is writing custom
-        // headers currently
         dir::clean(dir::crate_target()).expect("Failed to clean crate export directory!");
 
         // We will do these two steps first, as setting up the dependencies can modify flags we