added docs everywhere and refactor some bits (#336)

* refactor: remove some unused code and use IndexMap exclusively

Cargo.toml

@@ -18,7 +18,7 @@ native-tls = ['reqwest/native-tls', 'rattler/native-tls']
 rustls-tls = ['reqwest/rustls-tls', 'rattler/rustls-tls']
 
 [dependencies]
-serde = { version = "1.0.192", features = ["derive"] }
+serde = { version = "1.0.193", features = ["derive"] }
 serde_yaml = "0.9.27"
 rattler = { version = "0.12.2", default-features = false }
 rattler_conda_types = { version = "0.12.2", default-features = false }
@@ -59,7 +59,6 @@ tracing-subscriber = { version = "0.3.18", features = [
 ] }
 marked-yaml = { git = "https://github.com/GrayJack/marked-data.git", branch = "expand", package = "marked-yaml" }
 miette = { version = "5.10.0", features = ["fancy"] }
-linked-hash-map = "0.5.6"
 num_cpus = "1.16.0"
 goblin = "0.7.1"
 scroll = "0.11.0"

rust-tests/Cargo.toml

@@ -8,6 +8,6 @@ edition = "2021"
 [dependencies]
 glob = "0.3.1"
 itertools = "0.12.0"
-rattler_package_streaming = { version = "0.12.0", default-features = false }
+rattler_package_streaming = { version = "0.12.2", default-features = false }
 serde_json = "1.0.108"
 sha1 = "0.10.6"

src/hash.rs

@@ -1,4 +1,4 @@
-//! Compute the build string for a given variant
+//! Compute the build string / hash info for a given variant
 use std::collections::{BTreeMap, HashMap};
 
 use rattler_conda_types::NoArchType;
@@ -136,9 +136,13 @@ fn hash_variant(variant: &BTreeMap<String, String>) -> String {
     res[..HASH_LENGTH].to_string()
 }
 
+/// The hash info for a given variant
 #[derive(Debug, PartialEq, Clone, Eq, Hash)]
 pub struct HashInfo {
+    /// The hash (first 7 letters of the sha1sum)
     pub hash: String,
+
+    /// The hash prefix (e.g. `py38` or `np111`)
     pub hash_prefix: String,
 }
 
@@ -172,7 +176,8 @@ impl<'de> Deserialize<'de> for HashInfo {
     }
 }
 
-pub fn compute_buildstring(variant: &BTreeMap<String, String>, noarch: &NoArchType) -> HashInfo {
+/// Compute the build string for a given variant
+pub fn compute_hash_info(variant: &BTreeMap<String, String>, noarch: &NoArchType) -> HashInfo {
     let hash_prefix = compute_hash_prefix(variant, noarch);
     let hash = hash_variant(variant);
     HashInfo { hash, hash_prefix }
@@ -202,7 +207,7 @@ mod tests {
         input.insert("python".to_string(), "3.11.* *_cpython".to_string());
         input.insert("c_compiler_version".to_string(), "14".to_string());
 
-        let build_string_from_output = compute_buildstring(&input, &NoArchType::none());
+        let build_string_from_output = compute_hash_info(&input, &NoArchType::none());
         assert_eq!(build_string_from_output.to_string(), "py311h507f6e9");
     }
 }

src/lib.rs

@@ -1,3 +1,7 @@
+#![deny(missing_docs)]
+
+//! The library pieces of rattler-build
+
 pub mod build;
 pub mod metadata;
 pub mod recipe;

src/main.rs

@@ -24,7 +24,7 @@ use tracing_subscriber::{
 
 use rattler_build::{
     build::run_build,
-    hash::compute_buildstring,
+    hash::compute_hash_info,
     metadata::{BuildConfiguration, Directories, PackageIdentifier},
     recipe::{parser::Recipe, ParsingError},
     selectors::SelectorConfig,
@@ -284,7 +284,7 @@ async fn run_build_from_args(args: BuildOpts, multi_progress: MultiProgress) ->
 
     let mut subpackages = BTreeMap::new();
     for (_, _, _, output, variant) in outputs_and_variants {
-        let hash = compute_buildstring(&variant, &noarch);
+        let hash = compute_hash_info(&variant, &noarch);
 
         let selector_config = SelectorConfig {
             variant: variant.clone(),
@@ -341,7 +341,7 @@ async fn run_build_from_args(args: BuildOpts, multi_progress: MultiProgress) ->
                     _ => target_platform,
                 },
                 build_platform: Platform::current(),
-                hash: compute_buildstring(&variant, &noarch_type),
+                hash: compute_hash_info(&variant, &noarch_type),
                 variant: variant.clone(),
                 directories: Directories::create(
                     name.as_normalized(),

src/metadata.rs

@@ -14,22 +14,7 @@ use serde::{Deserialize, Serialize};
 
 use crate::{hash::HashInfo, render::resolved_dependencies::FinalizedDependencies};
 
-pub struct Metadata {
-    pub name: String,
-    pub version: String,
-    pub requirements: Vec<String>,
-}
-
-impl Default for Metadata {
-    fn default() -> Self {
-        Self {
-            name: String::from(""),
-            version: String::from("0.0.0"),
-            requirements: Vec::new(),
-        }
-    }
-}
-
+/// A Git revision
 #[derive(Serialize, Deserialize, Debug, Clone)]
 pub struct GitRev(String);
 
@@ -91,6 +76,7 @@ fn setup_build_dir(
 }
 
 impl Directories {
+    /// Create all directories needed for the building of a package
     pub fn create(
         name: &str,
         recipe_path: &Path,
@@ -161,6 +147,7 @@ fn default_true() -> bool {
     true
 }
 
+/// The configuration for a build of a package
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct BuildConfiguration {
     /// The target platform for the build
@@ -195,17 +182,27 @@ impl BuildConfiguration {
     }
 }
 
+/// A package identifier
 #[derive(Serialize, Deserialize, Debug, Clone)]
 pub struct PackageIdentifier {
+    /// The name of the package
     pub name: PackageName,
+    /// The version of the package
     pub version: String,
+    /// The build string of the package
     pub build_string: String,
 }
 
+/// A output. This is the central element that is passed to the `run_build` function
+/// and fully specifies all the options and settings to run the build.
 #[derive(Clone, Serialize, Deserialize)]
 pub struct Output {
+    /// The rendered recipe that is used to build this output
     pub recipe: crate::recipe::parser::Recipe,
+    /// The build configuration for this output (e.g. target_platform, channels, and other settings)
     pub build_configuration: BuildConfiguration,
+    /// The finalized dependencies for this output. If this is `None`, the dependencies have not been resolved yet.
+    /// During the `run_build` functions, the dependencies are resolved and this field is filled.
     pub finalized_dependencies: Option<FinalizedDependencies>,
 }
 

src/recipe.rs

@@ -1,3 +1,5 @@
+//! The recipe module contains all the logic to parse a recipe file.
+
 pub use self::{error::ParsingError, jinja::Jinja, parser::Recipe};
 
 pub mod parser;