Updates to comments and tests

Co-authored-by: Ryan Bottriell <[email protected]>

Signed-off-by: David Gilligan-Cook <[email protected]>

Author: dcookspi

crates/spk-cli/group2/src/cmd_new.rs

@@ -44,12 +44,16 @@ fn get_stub(name: &PkgNameBuf) -> String {
 
 build:
 
-  # Set what level of host compatibility the built package should have:
-  # - full: package can be used on any OS and any architecture
-  # - os: package can be used anywhere that has the same OS type (mac, linux, windows)
-  # - arch: package can be used anywhere that has the same OS and CPU architecture (x86_64, i386)
-  # - distro: package can only be used on the same OS, CPU, and OS distribution version (eg linux distro)
-  host_compat: distro
+  # set which host related vars are added automatically to the built package:
+  # - Distro: adds 'distro', 'arch', 'os' and '<distroname>' vars, so the package
+  #           can only be used on the same OS, CPU, and OS distribution version 
+  #           (e.g. linux distro). This is the default.
+  # - Arch: adds 'arch' and 'os' vars, so the package can be used anywhere that
+  #         has the same OS and CPU architecture (x86_64, i386)
+  # - Os: adds 'os' var, so the package can be used anywhere that has the same 
+  #       OS type (mac, linux, windows)
+  # - None: adds no host vars, so package can be used on any OS and any architecture
+  auto_host_vars: Distro
 
   # options are all the inputs to the package build process, including
   # build-time dependencies

crates/spk-schema/crates/foundation/src/name/mod.rs

@@ -238,8 +238,8 @@ impl OptName {
 
 impl OptNameBuf {
     /// Construct a valid OptNameBuf, invalid characters will be
-    /// removed, the length will be padded or truncates, and uppercase
-    /// letter will be lowercased to make a valid option name.
+    /// removed, the length will be padded or truncated, and uppercase
+    /// letters will be lowercased to make a valid option name.
     pub fn new_lossy<S: AsRef<str>>(s: &S) -> OptNameBuf {
         if validate_opt_base_name(s).is_ok() {
             return unsafe { OptNameBuf::from_string(s.as_ref().to_string()) };

crates/spk-schema/src/build_spec_test.rs

@@ -19,7 +19,7 @@ fn test_host_compat_default() {
 #[case("None", true)]
 #[case("Tuesday", false)]
 fn test_build_spec_with_host_opt_value(#[case] value: &str, #[case] expected_result: bool) {
-    // Tests the host_compat value is valid
+    // Tests the auto_host_vars value is valid
     let res: serde_yaml::Result<BuildSpec> = serde_yaml::from_str(&format!(
         "{{
         auto_host_vars: {value},
@@ -38,7 +38,7 @@ fn test_build_spec_with_host_opt_contains_expected_names(
     #[case] value: &str,
     #[case] expected_names: Vec<String>,
 ) {
-    // Test the host_compat value generates the expected named options
+    // Test the auto_host_vars value generates the expected named options
     let res: serde_yaml::Result<BuildSpec> = serde_yaml::from_str(&format!(
         "{{
         auto_host_vars: {value},
@@ -75,9 +75,9 @@ fn test_build_spec_with_host_opt_does_not_have_disallowed_names(
     #[case] value: &str,
     #[case] invalid_names: Vec<&str>,
 ) {
-    // Test the host_compat value does not create the options names
+    // Test the auto_host_vars value does not create the options names
     // that are disallowed by that value. This test will have to
-    // change if the host_compat validation is disabled.
+    // change if the host compat validation is disabled.
     let res: serde_yaml::Result<BuildSpec> = serde_yaml::from_str(&format!(
         "{{
         auto_host_vars: {value},
@@ -110,13 +110,14 @@ fn test_build_spec_with_host_opt_does_not_have_disallowed_names(
     }
 }
 
-// #[case("distro")] - not checked, it has no disallowed names
 #[rstest]
+#[should_panic] // distro has no disallowed names
+#[case("distro")]
 #[case("Arch")]
 #[case("Os")]
 #[case("None")]
 fn test_build_spec_with_host_opt_and_disallowed_name(#[case] value: &str) {
-    // Test the host_compat value setting causes an error when there's
+    // Test the auto_host_vars value setting causes an error when there's
     // a disallowed option name in the build options.
     let res: serde_yaml::Result<BuildSpec> = serde_yaml::from_str(&format!(
         "{{
@@ -132,7 +133,7 @@ fn test_build_spec_with_host_opt_and_disallowed_name(#[case] value: &str) {
             let result = build_spec.opts_for_variant(&build_spec.variants[0]);
             assert!(result.is_ok())
         }
-        Err(err) => panic!("Fail: build spec didn't parse with host_compat {value}: {err:?}"),
+        Err(err) => panic!("Fail: build spec didn't parse with 'auto_host_vars: {value}': {err:?}"),
     }
 }
 

docs/ref/spec.md

@@ -72,7 +72,7 @@ Fetches and extracts a tar archive as package source files.
 | options     | _List[[BuildOption](#buildoption)]_ | The set of inputs for the package build process                |
 | variants    | _List[[OptionMap](#optionmap)]_     | The default variants of the package options to build           |
 | validation  | _[ValidationSpec](#validationspec)_ | Modifies the default package validation process                |
-| auto_host_vars | _[HostCompat](#hostcompat)_ | The host compatibility setting for the package's builds. It covers distro, arch, os, and distro version |
+| auto_host_vars | _[HostCompat](#hostcompat)_ | The host compatibility setting for the package's builds. Depending on the value, it injects build options like distro, arch, os, and distro version |
 
 ### BuildOption
 
@@ -126,7 +126,7 @@ options to each build, as described in the table:
 
 |  Value     | Adds these host options                        |
 | ---------- | ---------------------------------------------- |
-| **Distro** | "distro", "arch", "os", and the "<distroname>" |
+| **Distro** (default) | "distro", "arch", "os", and the "<distroname>" |
 | **Arch**   | "arch", "os", and the "<distroname>"           |
 | **Os**     | "os"                                           |
 | **None**   |                                                |