rename targetPath to systemRoot

Author: SteveL-MSFT

dsc/src/args.rs

@@ -48,8 +48,8 @@ pub enum SubCommand {
         parameters: Option<String>,
         #[clap(short = 'f', long, help = "Parameters to pass to the configuration as a JSON or YAML file", conflicts_with = "parameters")]
         parameters_file: Option<String>,
-        #[clap(short = 't', long, help = "Target path to apply configuration, requires resource support.")]
-        target_path: Option<String>,
+        #[clap(short = 'r', long, help = "Specify the operating system root path if not targeting the current running OS")]
+        system_root: Option<String>,
         // Used to inform when DSC is used as a group resource to modify it's output
         #[clap(long, hide = true)]
         as_group: bool,

dsc/src/main.rs

@@ -68,19 +68,19 @@ fn main() {
             let mut cmd = Args::command();
             generate(shell, &mut cmd, "dsc", &mut io::stdout());
         },
-        SubCommand::Config { subcommand, parameters, parameters_file, target_path, as_group, as_include } => {
+        SubCommand::Config { subcommand, parameters, parameters_file, system_root, as_group, as_include } => {
             if let Some(file_name) = parameters_file {
                 info!("Reading parameters from file {file_name}");
                 match std::fs::read_to_string(&file_name) {
-                    Ok(parameters) => subcommand::config(&subcommand, &Some(parameters), &target_path, &input, &as_group, &as_include),
+                    Ok(parameters) => subcommand::config(&subcommand, &Some(parameters), &system_root, &input, &as_group, &as_include),
                     Err(err) => {
                         error!("Error: Failed to read parameters file '{file_name}': {err}");
                         exit(util::EXIT_INVALID_INPUT);
                     }
                 }
             }
             else {
-                subcommand::config(&subcommand, &parameters, &target_path, &input, &as_group, &as_include);
+                subcommand::config(&subcommand, &parameters, &system_root, &input, &as_group, &as_include);
             }
         },
         SubCommand::Resource { subcommand } => {

dsc/src/subcommand.rs

@@ -279,7 +279,7 @@ pub fn config(subcommand: &ConfigSubCommand, parameters: &Option<String>, mounte
             exit(EXIT_INVALID_ARGS);
         }
 
-        configurator.set_target_path(path);
+        configurator.set_system_root(path);
     }
 
     if let Err(err) = configurator.set_context(&parameters) {

dsc/tests/dsc_functions.tests.ps1

@@ -26,7 +26,7 @@ Describe 'tests for function expressions' {
     }
 
     It 'path(<path>) works' -TestCases @(
-        @{ path = "targetPath(), 'a'"; expected = "$PSHOME$([System.IO.Path]::DirectorySeparatorChar)a" }
+        @{ path = "systemRoot(), 'a'"; expected = "$PSHOME$([System.IO.Path]::DirectorySeparatorChar)a" }
         @{ path = "'a', 'b', 'c'"; expected = "a$([System.IO.Path]::DirectorySeparatorChar)b$([System.IO.Path]::DirectorySeparatorChar)c" }
     ) {
         param($path, $expected)
@@ -43,14 +43,14 @@ Describe 'tests for function expressions' {
         $out.results[0].result.actualState.output | Should -BeExactly $expected
     }
 
-    It 'default targetPath() is correct for the OS' {
+    It 'default systemRoot() is correct for the OS' {
         $config_yaml = @'
             $schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json
             resources:
             - name: Echo
               type: Microsoft.DSC.Debug/Echo
               properties:
-                output: "[targetPath()]"
+                output: "[systemRoot()]"
 '@
 
         $expected = if ($IsWindows) {

dsc_lib/src/configure/context.rs

@@ -12,7 +12,7 @@ use super::config_doc::{DataType, SecurityContextKind};
 pub struct Context {
     pub execution_type: ExecutionKind,
     pub outputs: HashMap<String, Value>, // this is used by the `reference()` function to retrieve output
-    pub target_path: PathBuf,
+    pub system_root: PathBuf,
     pub parameters: HashMap<String, (Value, DataType)>,
     pub security_context: SecurityContextKind,
     pub variables: HashMap<String, Value>,
@@ -25,7 +25,7 @@ impl Context {
         Self {
             execution_type: ExecutionKind::Actual,
             outputs: HashMap::new(),
-            target_path: get_default_os_target_path(),
+            system_root: get_default_os_system_root(),
             parameters: HashMap::new(),
             security_context: match get_security_context() {
                 SecurityContext::Admin => SecurityContextKind::Elevated,
@@ -44,13 +44,13 @@ impl Default for Context {
 }
 
 #[cfg(target_os = "windows")]
-fn get_default_os_target_path() -> PathBuf {
+fn get_default_os_system_root() -> PathBuf {
     // use SYSTEMDRIVE env var to get the default target path
     let system_drive = std::env::var("SYSTEMDRIVE").unwrap_or_else(|_| "C:".to_string());
     PathBuf::from(system_drive)
 }
 
 #[cfg(not(target_os = "windows"))]
-fn get_default_os_target_path() -> PathBuf {
+fn get_default_os_system_root() -> PathBuf {
     PathBuf::from("/")
 }

dsc_lib/src/configure/mod.rs

@@ -485,8 +485,8 @@ impl Configurator {
     /// # Arguments
     ///
     /// * `mounted_path` - The mounted path to set.
-    pub fn set_target_path(&mut self, target_path: &str) {
-        self.context.target_path = PathBuf::from(target_path);
+    pub fn set_system_root(&mut self, system_root: &str) {
+        self.context.system_root = PathBuf::from(system_root);
     }
 
     /// Set the parameters and variables context for the configuration.

dsc_lib/src/functions/mod.rs

@@ -23,7 +23,7 @@ pub mod path;
 pub mod reference;
 pub mod resource_id;
 pub mod sub;
-pub mod target_path;
+pub mod system_root;
 pub mod variables;
 
 /// The kind of argument that a function accepts.
@@ -82,7 +82,7 @@ impl FunctionDispatcher {
         functions.insert("reference".to_string(), Box::new(reference::Reference{}));
         functions.insert("resourceId".to_string(), Box::new(resource_id::ResourceId{}));
         functions.insert("sub".to_string(), Box::new(sub::Sub{}));
-        functions.insert("targetPath".to_string(), Box::new(target_path::TargetPath{}));
+        functions.insert("systemRoot".to_string(), Box::new(system_root::SystemRoot{}));
         functions.insert("variables".to_string(), Box::new(variables::Variables{}));
         Self {
             functions,

dsc_lib/src/functions/target_path.rs renamed to dsc_lib/src/functions/system_root.rs

@@ -8,13 +8,11 @@ use serde_json::Value;
 use tracing::debug;
 
 #[derive(Debug, Default)]
-pub struct TargetPath {}
+pub struct SystemRoot {}
 
-/// Implements the `targetPath` function.
-/// This function returns the value of the mounted path.
-/// The optional parameter is a path appended to the mounted path.
-/// Path is not validated as it might be used for creation.
-impl Function for TargetPath {
+/// Implements the `systemRoot` function.
+/// This function returns the value of the specified system root path.
+impl Function for SystemRoot {
     fn min_args(&self) -> usize {
         0
     }
@@ -30,23 +28,23 @@ impl Function for TargetPath {
     fn invoke(&self, _args: &[Value], context: &Context) -> Result<Value, DscError> {
         debug!("Executing targetPath function");
 
-        Ok(Value::String(context.target_path.to_string_lossy().to_string()))
+        Ok(Value::String(context.system_root.to_string_lossy().to_string()))
     }
 }
 
 #[cfg(test)]
 mod tests {
     use crate::configure::context::Context;
     use crate::parser::Statement;
-    use std::{env, path::PathBuf};
+    use std::path::PathBuf;
 
     #[test]
     fn init() {
         let mut parser = Statement::new().unwrap();
-        let result = parser.parse_and_execute("[targetPath()]", &Context::new()).unwrap();
+        let result = parser.parse_and_execute("[systemRoot()]", &Context::new()).unwrap();
         // on windows, the default is SYSTEMDRIVE env var
         #[cfg(target_os = "windows")]
-        assert_eq!(result, env::var("SYSTEMDRIVE").unwrap());
+        assert_eq!(result, std::env::var("SYSTEMDRIVE").unwrap());
         // on linux/macOS, the default is /
         #[cfg(not(target_os = "windows"))]
         assert_eq!(result, "/");
@@ -57,8 +55,8 @@ mod tests {
         let mut parser = Statement::new().unwrap();
         let mut context = Context::new();
         let separator = std::path::MAIN_SEPARATOR;
-        context.target_path = PathBuf::from(format!("{separator}mnt"));
-        let result = parser.parse_and_execute("[targetPath()]", &context).unwrap();
+        context.system_root = PathBuf::from(format!("{separator}mnt"));
+        let result = parser.parse_and_execute("[systemRoot()]", &context).unwrap();
         assert_eq!(result, format!("{separator}mnt"));
     }