From 32dd18e3b60bca26a42f4e2ce78f17eab913eda2 Mon Sep 17 00:00:00 2001 From: "G.Reijn" Date: Fri, 7 Nov 2025 15:44:49 +0100 Subject: [PATCH 1/5] First PS script --- docs/installing-nightly.md | 86 +++++++++++++++++++++++++++ sharedScripts/install_cli_nightly.ps1 | 64 ++++++++++++++++++++ 2 files changed, 150 insertions(+) create mode 100644 docs/installing-nightly.md create mode 100644 sharedScripts/install_cli_nightly.ps1 diff --git a/docs/installing-nightly.md b/docs/installing-nightly.md new file mode 100644 index 000000000..5d53883ee --- /dev/null +++ b/docs/installing-nightly.md @@ -0,0 +1,86 @@ +# Installing the "Nightly" build of DSC CLI + +> **Note**: Nightly builds contain the latest development features but may have bugs or breaking +> changes. Only install if you want to test unreleased functionality. If you encounter issues, +> please [open an issue](https://github.com/PowerShell/DSC/issues/new). + +## Via script + +> **Note**: This script requires the [GitHub CLI](https://cli.github.com/) to have already been +> installed. + +### DSC CLI + +This will install the latest nightly DSC CLI binary: + +- **Windows**: `%LOCALAPPDATA%\dsc\dsc.exe` +- **Linux/macOS**: `~/.dsc/bin/dsc` + +1. (macOS/Linux) Run the following: + + ```sh + bash <(curl -Ls https://raw.githubusercontent.com/PowerShell/DSC/refs/heads/main/sharedScripts/install_cli_nightly.sh) + ``` + +1. (Windows) Run the following in a PowerShell window: + + ```powershell + iex "& { $(irm https://raw.githubusercontent.com/PowerShell/DSC/refs/heads/main/sharedScripts/install_cli_nightly.ps1) }" + ``` + +1. Add the installation directory to your PATH environment variable to use `dsc` from any location. + +## Manual + +We are not currently publishing "nightly" releases, but you can grab the latest bits by viewing +the latest Action workflows for the `main` branch (or any other branch). + +The easiest way to get these artifacts is through the GitHub site. Follow +[this link](https://github.com/PowerShell/DSC/actions/workflows/rust.yml?query=branch%3Amain+is%3Asuccess) +to view the latest successful Action workflows for the `main` branch. Select it to show the related +artifacts. + +On the details page, select the artifact for your platform: + +- `windows-bin` for Windows +- `linux-bin` for Linux +- `macos-bin` for macOS + +Extract the archive and place the `dsc` executable (or `dsc.exe` on Windows) in a directory in +your PATH. + +## Advanced Script Options + +### DSC CLI + +- macOS/Linux + + ```sh + # install to a custom directory + bash <(curl -Ls https://raw.githubusercontent.com/PowerShell/DSC/refs/heads/main/sharedScripts/install_cli_nightly.sh) --install-path /usr/local/bin + + # install from a fork repo + bash <(curl -Ls https://raw.githubusercontent.com/PowerShell/DSC/refs/heads/main/sharedScripts/install_cli_nightly.sh) --repo myusername/DSC + + # install from a custom branch + bash <(curl -Ls https://raw.githubusercontent.com/PowerShell/DSC/refs/heads/main/sharedScripts/install_cli_nightly.sh) --branch feature-branch + + # install from a specific github action run + bash <(curl -Ls https://raw.githubusercontent.com/PowerShell/DSC/refs/heads/main/sharedScripts/install_cli_nightly.sh) --run-id 6146657618 + ``` + +- Windows + + ```powershell + # install to a custom directory + iex "& { $(irm https://raw.githubusercontent.com/PowerShell/DSC/refs/heads/main/sharedScripts/install_cli_nightly.ps1) } -InstallPath C:\tools\dsc" + + # install from a fork repo + iex "& { $(irm https://raw.githubusercontent.com/PowerShell/DSC/refs/heads/main/sharedScripts/install_cli_nightly.ps1) } -Repo myusername/DSC" + + # install from a custom branch + iex "& { $(irm https://raw.githubusercontent.com/PowerShell/DSC/refs/heads/main/sharedScripts/install_cli_nightly.ps1) } -Branch feature-branch" + + # install from a specific github action run + iex "& { $(irm https://raw.githubusercontent.com/PowerShell/DSC/refs/heads/main/sharedScripts/install_cli_nightly.ps1) } -RunId 6146657618" + ``` diff --git a/sharedScripts/install_cli_nightly.ps1 b/sharedScripts/install_cli_nightly.ps1 new file mode 100644 index 000000000..13d6a65d0 --- /dev/null +++ b/sharedScripts/install_cli_nightly.ps1 @@ -0,0 +1,64 @@ +[cmdletbinding()] +param( + [string]$RunId, + [string]$Branch, + [string]$Repo, + [string]$InstallPath +) + +$ErrorActionPreference="Stop" + +if ($null -eq (Get-Command "gh" -ErrorAction SilentlyContinue)) { + throw "Please install the GitHub CLI: https://cli.github.com/" +} + +$platform = if ($IsWindows) { "windows" } elseif ($IsLinux) { "linux" } elseif ($IsMacOS) { "macos" } else { throw "Unsupported OS" } + +# Fetch +if (!$InstallPath) { + # Default install paths by platform + if ($IsWindows) { + $InstallPath = [System.IO.Path]::combine($env:LOCALAPPDATA, "dsc") + } else { + $InstallPath = [System.IO.Path]::combine($HOME, ".dsc", "bin") + } +} +if (!$Repo) { + $Repo = "PowerShell/DSC" +} +if (!$Branch) { + $Branch = "main" +} +if (!$RunId) { + $RunId = & gh run list -R $Repo --branch $Branch --workflow rust --status success -L 1 --json databaseId -q ".[0].databaseId"; if(!$?) { throw } + if (!$RunId) { + throw "Failed to find a successful build to install from" + } +} + +$tmpDir = [System.IO.Path]::combine([System.IO.Path]::GetTempPath(), [System.IO.Path]::GetRandomFileName()) +& gh run download -R $Repo $RunId -n "$platform-bin" --dir $tmpDir; if(!$?) { throw } + +$tar = Get-ChildItem -Path $tmpDir | Select-Object -First 1 +if (!$tar) { + throw "Failed to find downloaded artifact" +} + +if (-not (Get-Command "tar" -ErrorAction SilentlyContinue)) { + throw "Please install 'tar' to extract the downloaded artifact." +} + +tar -xf $tar.FullName -C $tmpDir; if(!$?) { throw } + +$installationFiles = Join-Path $tmpDir 'bin' 'debug' +New-Item -ItemType Directory -Force -Path $InstallPath | Out-Null +Move-Item -Path "$installationFiles/*" -Destination $InstallPath -Force -ErrorAction Ignore + +$dscExe = if ($IsWindows) { Join-Path $InstallPath "dsc.exe" } else { Join-Path $InstallPath "dsc" } +$versionStdout = & $dscExe --version; if(!$?) { throw } +$version = $versionStdout -replace 'dsc ', '' +Write-Host "Installed DSC CLI $version from https://github.com/$Repo/actions/runs/$RunId to $InstallPath" +Write-Host "Make sure to add $InstallPath to your PATH environment variable to use the 'dsc' command." + +# Cleanup +Remove-Item $tmpDir -Recurse \ No newline at end of file From 3f364bb1820bbd090f50a0d12a2446f4e9f9c3f3 Mon Sep 17 00:00:00 2001 From: "G.Reijn" Date: Fri, 7 Nov 2025 15:53:46 +0100 Subject: [PATCH 2/5] Add docs --- docs/installing-nightly.md | 2 +- sharedScripts/install_cli_nightly.ps1 | 12 +-- sharedScripts/install_cli_nightly.sh | 105 ++++++++++++++++++++++++++ 3 files changed, 109 insertions(+), 10 deletions(-) create mode 100644 sharedScripts/install_cli_nightly.sh diff --git a/docs/installing-nightly.md b/docs/installing-nightly.md index 5d53883ee..f8b997346 100644 --- a/docs/installing-nightly.md +++ b/docs/installing-nightly.md @@ -49,7 +49,7 @@ On the details page, select the artifact for your platform: Extract the archive and place the `dsc` executable (or `dsc.exe` on Windows) in a directory in your PATH. -## Advanced Script Options +## Advanced script options ### DSC CLI diff --git a/sharedScripts/install_cli_nightly.ps1 b/sharedScripts/install_cli_nightly.ps1 index 13d6a65d0..13e9c75b5 100644 --- a/sharedScripts/install_cli_nightly.ps1 +++ b/sharedScripts/install_cli_nightly.ps1 @@ -12,16 +12,10 @@ if ($null -eq (Get-Command "gh" -ErrorAction SilentlyContinue)) { throw "Please install the GitHub CLI: https://cli.github.com/" } -$platform = if ($IsWindows) { "windows" } elseif ($IsLinux) { "linux" } elseif ($IsMacOS) { "macos" } else { throw "Unsupported OS" } - # Fetch if (!$InstallPath) { - # Default install paths by platform - if ($IsWindows) { - $InstallPath = [System.IO.Path]::combine($env:LOCALAPPDATA, "dsc") - } else { - $InstallPath = [System.IO.Path]::combine($HOME, ".dsc", "bin") - } + # Default install for Windows + $InstallPath = [System.IO.Path]::combine($env:LOCALAPPDATA, "dsc") } if (!$Repo) { $Repo = "PowerShell/DSC" @@ -54,7 +48,7 @@ $installationFiles = Join-Path $tmpDir 'bin' 'debug' New-Item -ItemType Directory -Force -Path $InstallPath | Out-Null Move-Item -Path "$installationFiles/*" -Destination $InstallPath -Force -ErrorAction Ignore -$dscExe = if ($IsWindows) { Join-Path $InstallPath "dsc.exe" } else { Join-Path $InstallPath "dsc" } +$dscExe = Join-Path $InstallPath "dsc.exe" $versionStdout = & $dscExe --version; if(!$?) { throw } $version = $versionStdout -replace 'dsc ', '' Write-Host "Installed DSC CLI $version from https://github.com/$Repo/actions/runs/$RunId to $InstallPath" diff --git a/sharedScripts/install_cli_nightly.sh b/sharedScripts/install_cli_nightly.sh new file mode 100644 index 000000000..46e7b8659 --- /dev/null +++ b/sharedScripts/install_cli_nightly.sh @@ -0,0 +1,105 @@ +#!/usr/bin/env bash +set -e + +# Default values +INSTALL_PATH="" +REPO="PowerShell/DSC" +BRANCH="main" +RUN_ID="" + +# Parse command line arguments +while [[ $# -gt 0 ]]; do + case $1 in + --install-path) + INSTALL_PATH="$2" + shift 2 + ;; + --repo) + REPO="$2" + shift 2 + ;; + --branch) + BRANCH="$2" + shift 2 + ;; + --run-id) + RUN_ID="$2" + shift 2 + ;; + *) + echo "Unknown option: $1" + exit 1 + ;; + esac +done + +# Check for GitHub CLI +if ! command -v gh &> /dev/null; then + echo "Error: GitHub CLI (gh) is not installed." + echo "Please install it from: https://cli.github.com/" + exit 1 +fi + +# Detect platform +if [[ "$OSTYPE" == "linux-gnu"* ]]; then + PLATFORM="linux" +elif [[ "$OSTYPE" == "darwin"* ]]; then + PLATFORM="macos" +else + echo "Error: Unsupported OS: $OSTYPE" + exit 1 +fi + +# Set default install path if not provided +if [[ -z "$INSTALL_PATH" ]]; then + INSTALL_PATH="$HOME/.dsc/bin" +fi + +# Fetch run ID if not provided +if [[ -z "$RUN_ID" ]]; then + echo "Fetching latest successful build for branch '$BRANCH'..." + RUN_ID=$(gh run list -R "$REPO" --branch "$BRANCH" --workflow rust --status success -L 1 --json databaseId -q ".[0].databaseId") + + if [[ -z "$RUN_ID" ]]; then + echo "Error: Failed to find a successful build to install from" + exit 1 + fi +fi + +echo "Downloading artifacts from run $RUN_ID..." + +# Create temporary directory +TMP_DIR=$(mktemp -d) +trap "rm -rf $TMP_DIR" EXIT + +# Download artifact +gh run download -R "$REPO" "$RUN_ID" -n "${PLATFORM}-bin" --dir "$TMP_DIR" + +# Find the tar file +TAR_FILE=$(find "$TMP_DIR" -name "*.tar.gz" -o -name "*.tgz" | head -n 1) + +if [[ -z "$TAR_FILE" ]]; then + echo "Error: Failed to find downloaded artifact" + exit 1 +fi + +# Extract +echo "Extracting archive..." +tar -xzf "$TAR_FILE" -C "$TMP_DIR" + +# Install +echo "Installing to $INSTALL_PATH..." +mkdir -p "$INSTALL_PATH" +mv "$TMP_DIR/dsc" "$INSTALL_PATH/dsc" +chmod +x "$INSTALL_PATH/dsc" + +# Get version +VERSION=$("$INSTALL_PATH/dsc" --version 2>&1 || echo "unknown") + +echo "" +echo "Successfully installed DSC to $INSTALL_PATH/dsc" +echo "Version: $VERSION" +echo "From: https://github.com/$REPO/actions/runs/$RUN_ID" +echo "" +echo "To use DSC, add the following to your PATH:" +echo " export PATH=\"\$PATH:$INSTALL_PATH\"" From d04ae633c3547b5826caba3f92b9d0eaff841b17 Mon Sep 17 00:00:00 2001 From: "G.Reijn" Date: Fri, 7 Nov 2025 15:44:49 +0100 Subject: [PATCH 3/5] First PS script --- docs/installing-nightly.md | 86 +++++++++++++++++++++++++++ sharedScripts/install_cli_nightly.ps1 | 64 ++++++++++++++++++++ 2 files changed, 150 insertions(+) create mode 100644 docs/installing-nightly.md create mode 100644 sharedScripts/install_cli_nightly.ps1 diff --git a/docs/installing-nightly.md b/docs/installing-nightly.md new file mode 100644 index 000000000..5d53883ee --- /dev/null +++ b/docs/installing-nightly.md @@ -0,0 +1,86 @@ +# Installing the "Nightly" build of DSC CLI + +> **Note**: Nightly builds contain the latest development features but may have bugs or breaking +> changes. Only install if you want to test unreleased functionality. If you encounter issues, +> please [open an issue](https://github.com/PowerShell/DSC/issues/new). + +## Via script + +> **Note**: This script requires the [GitHub CLI](https://cli.github.com/) to have already been +> installed. + +### DSC CLI + +This will install the latest nightly DSC CLI binary: + +- **Windows**: `%LOCALAPPDATA%\dsc\dsc.exe` +- **Linux/macOS**: `~/.dsc/bin/dsc` + +1. (macOS/Linux) Run the following: + + ```sh + bash <(curl -Ls https://raw.githubusercontent.com/PowerShell/DSC/refs/heads/main/sharedScripts/install_cli_nightly.sh) + ``` + +1. (Windows) Run the following in a PowerShell window: + + ```powershell + iex "& { $(irm https://raw.githubusercontent.com/PowerShell/DSC/refs/heads/main/sharedScripts/install_cli_nightly.ps1) }" + ``` + +1. Add the installation directory to your PATH environment variable to use `dsc` from any location. + +## Manual + +We are not currently publishing "nightly" releases, but you can grab the latest bits by viewing +the latest Action workflows for the `main` branch (or any other branch). + +The easiest way to get these artifacts is through the GitHub site. Follow +[this link](https://github.com/PowerShell/DSC/actions/workflows/rust.yml?query=branch%3Amain+is%3Asuccess) +to view the latest successful Action workflows for the `main` branch. Select it to show the related +artifacts. + +On the details page, select the artifact for your platform: + +- `windows-bin` for Windows +- `linux-bin` for Linux +- `macos-bin` for macOS + +Extract the archive and place the `dsc` executable (or `dsc.exe` on Windows) in a directory in +your PATH. + +## Advanced Script Options + +### DSC CLI + +- macOS/Linux + + ```sh + # install to a custom directory + bash <(curl -Ls https://raw.githubusercontent.com/PowerShell/DSC/refs/heads/main/sharedScripts/install_cli_nightly.sh) --install-path /usr/local/bin + + # install from a fork repo + bash <(curl -Ls https://raw.githubusercontent.com/PowerShell/DSC/refs/heads/main/sharedScripts/install_cli_nightly.sh) --repo myusername/DSC + + # install from a custom branch + bash <(curl -Ls https://raw.githubusercontent.com/PowerShell/DSC/refs/heads/main/sharedScripts/install_cli_nightly.sh) --branch feature-branch + + # install from a specific github action run + bash <(curl -Ls https://raw.githubusercontent.com/PowerShell/DSC/refs/heads/main/sharedScripts/install_cli_nightly.sh) --run-id 6146657618 + ``` + +- Windows + + ```powershell + # install to a custom directory + iex "& { $(irm https://raw.githubusercontent.com/PowerShell/DSC/refs/heads/main/sharedScripts/install_cli_nightly.ps1) } -InstallPath C:\tools\dsc" + + # install from a fork repo + iex "& { $(irm https://raw.githubusercontent.com/PowerShell/DSC/refs/heads/main/sharedScripts/install_cli_nightly.ps1) } -Repo myusername/DSC" + + # install from a custom branch + iex "& { $(irm https://raw.githubusercontent.com/PowerShell/DSC/refs/heads/main/sharedScripts/install_cli_nightly.ps1) } -Branch feature-branch" + + # install from a specific github action run + iex "& { $(irm https://raw.githubusercontent.com/PowerShell/DSC/refs/heads/main/sharedScripts/install_cli_nightly.ps1) } -RunId 6146657618" + ``` diff --git a/sharedScripts/install_cli_nightly.ps1 b/sharedScripts/install_cli_nightly.ps1 new file mode 100644 index 000000000..13d6a65d0 --- /dev/null +++ b/sharedScripts/install_cli_nightly.ps1 @@ -0,0 +1,64 @@ +[cmdletbinding()] +param( + [string]$RunId, + [string]$Branch, + [string]$Repo, + [string]$InstallPath +) + +$ErrorActionPreference="Stop" + +if ($null -eq (Get-Command "gh" -ErrorAction SilentlyContinue)) { + throw "Please install the GitHub CLI: https://cli.github.com/" +} + +$platform = if ($IsWindows) { "windows" } elseif ($IsLinux) { "linux" } elseif ($IsMacOS) { "macos" } else { throw "Unsupported OS" } + +# Fetch +if (!$InstallPath) { + # Default install paths by platform + if ($IsWindows) { + $InstallPath = [System.IO.Path]::combine($env:LOCALAPPDATA, "dsc") + } else { + $InstallPath = [System.IO.Path]::combine($HOME, ".dsc", "bin") + } +} +if (!$Repo) { + $Repo = "PowerShell/DSC" +} +if (!$Branch) { + $Branch = "main" +} +if (!$RunId) { + $RunId = & gh run list -R $Repo --branch $Branch --workflow rust --status success -L 1 --json databaseId -q ".[0].databaseId"; if(!$?) { throw } + if (!$RunId) { + throw "Failed to find a successful build to install from" + } +} + +$tmpDir = [System.IO.Path]::combine([System.IO.Path]::GetTempPath(), [System.IO.Path]::GetRandomFileName()) +& gh run download -R $Repo $RunId -n "$platform-bin" --dir $tmpDir; if(!$?) { throw } + +$tar = Get-ChildItem -Path $tmpDir | Select-Object -First 1 +if (!$tar) { + throw "Failed to find downloaded artifact" +} + +if (-not (Get-Command "tar" -ErrorAction SilentlyContinue)) { + throw "Please install 'tar' to extract the downloaded artifact." +} + +tar -xf $tar.FullName -C $tmpDir; if(!$?) { throw } + +$installationFiles = Join-Path $tmpDir 'bin' 'debug' +New-Item -ItemType Directory -Force -Path $InstallPath | Out-Null +Move-Item -Path "$installationFiles/*" -Destination $InstallPath -Force -ErrorAction Ignore + +$dscExe = if ($IsWindows) { Join-Path $InstallPath "dsc.exe" } else { Join-Path $InstallPath "dsc" } +$versionStdout = & $dscExe --version; if(!$?) { throw } +$version = $versionStdout -replace 'dsc ', '' +Write-Host "Installed DSC CLI $version from https://github.com/$Repo/actions/runs/$RunId to $InstallPath" +Write-Host "Make sure to add $InstallPath to your PATH environment variable to use the 'dsc' command." + +# Cleanup +Remove-Item $tmpDir -Recurse \ No newline at end of file From 24fda824c8e129a23601bab31897e0359a717503 Mon Sep 17 00:00:00 2001 From: "G.Reijn" Date: Fri, 7 Nov 2025 15:53:46 +0100 Subject: [PATCH 4/5] Add docs --- docs/installing-nightly.md | 2 +- sharedScripts/install_cli_nightly.ps1 | 12 +-- sharedScripts/install_cli_nightly.sh | 105 ++++++++++++++++++++++++++ 3 files changed, 109 insertions(+), 10 deletions(-) create mode 100644 sharedScripts/install_cli_nightly.sh diff --git a/docs/installing-nightly.md b/docs/installing-nightly.md index 5d53883ee..f8b997346 100644 --- a/docs/installing-nightly.md +++ b/docs/installing-nightly.md @@ -49,7 +49,7 @@ On the details page, select the artifact for your platform: Extract the archive and place the `dsc` executable (or `dsc.exe` on Windows) in a directory in your PATH. -## Advanced Script Options +## Advanced script options ### DSC CLI diff --git a/sharedScripts/install_cli_nightly.ps1 b/sharedScripts/install_cli_nightly.ps1 index 13d6a65d0..13e9c75b5 100644 --- a/sharedScripts/install_cli_nightly.ps1 +++ b/sharedScripts/install_cli_nightly.ps1 @@ -12,16 +12,10 @@ if ($null -eq (Get-Command "gh" -ErrorAction SilentlyContinue)) { throw "Please install the GitHub CLI: https://cli.github.com/" } -$platform = if ($IsWindows) { "windows" } elseif ($IsLinux) { "linux" } elseif ($IsMacOS) { "macos" } else { throw "Unsupported OS" } - # Fetch if (!$InstallPath) { - # Default install paths by platform - if ($IsWindows) { - $InstallPath = [System.IO.Path]::combine($env:LOCALAPPDATA, "dsc") - } else { - $InstallPath = [System.IO.Path]::combine($HOME, ".dsc", "bin") - } + # Default install for Windows + $InstallPath = [System.IO.Path]::combine($env:LOCALAPPDATA, "dsc") } if (!$Repo) { $Repo = "PowerShell/DSC" @@ -54,7 +48,7 @@ $installationFiles = Join-Path $tmpDir 'bin' 'debug' New-Item -ItemType Directory -Force -Path $InstallPath | Out-Null Move-Item -Path "$installationFiles/*" -Destination $InstallPath -Force -ErrorAction Ignore -$dscExe = if ($IsWindows) { Join-Path $InstallPath "dsc.exe" } else { Join-Path $InstallPath "dsc" } +$dscExe = Join-Path $InstallPath "dsc.exe" $versionStdout = & $dscExe --version; if(!$?) { throw } $version = $versionStdout -replace 'dsc ', '' Write-Host "Installed DSC CLI $version from https://github.com/$Repo/actions/runs/$RunId to $InstallPath" diff --git a/sharedScripts/install_cli_nightly.sh b/sharedScripts/install_cli_nightly.sh new file mode 100644 index 000000000..46e7b8659 --- /dev/null +++ b/sharedScripts/install_cli_nightly.sh @@ -0,0 +1,105 @@ +#!/usr/bin/env bash +set -e + +# Default values +INSTALL_PATH="" +REPO="PowerShell/DSC" +BRANCH="main" +RUN_ID="" + +# Parse command line arguments +while [[ $# -gt 0 ]]; do + case $1 in + --install-path) + INSTALL_PATH="$2" + shift 2 + ;; + --repo) + REPO="$2" + shift 2 + ;; + --branch) + BRANCH="$2" + shift 2 + ;; + --run-id) + RUN_ID="$2" + shift 2 + ;; + *) + echo "Unknown option: $1" + exit 1 + ;; + esac +done + +# Check for GitHub CLI +if ! command -v gh &> /dev/null; then + echo "Error: GitHub CLI (gh) is not installed." + echo "Please install it from: https://cli.github.com/" + exit 1 +fi + +# Detect platform +if [[ "$OSTYPE" == "linux-gnu"* ]]; then + PLATFORM="linux" +elif [[ "$OSTYPE" == "darwin"* ]]; then + PLATFORM="macos" +else + echo "Error: Unsupported OS: $OSTYPE" + exit 1 +fi + +# Set default install path if not provided +if [[ -z "$INSTALL_PATH" ]]; then + INSTALL_PATH="$HOME/.dsc/bin" +fi + +# Fetch run ID if not provided +if [[ -z "$RUN_ID" ]]; then + echo "Fetching latest successful build for branch '$BRANCH'..." + RUN_ID=$(gh run list -R "$REPO" --branch "$BRANCH" --workflow rust --status success -L 1 --json databaseId -q ".[0].databaseId") + + if [[ -z "$RUN_ID" ]]; then + echo "Error: Failed to find a successful build to install from" + exit 1 + fi +fi + +echo "Downloading artifacts from run $RUN_ID..." + +# Create temporary directory +TMP_DIR=$(mktemp -d) +trap "rm -rf $TMP_DIR" EXIT + +# Download artifact +gh run download -R "$REPO" "$RUN_ID" -n "${PLATFORM}-bin" --dir "$TMP_DIR" + +# Find the tar file +TAR_FILE=$(find "$TMP_DIR" -name "*.tar.gz" -o -name "*.tgz" | head -n 1) + +if [[ -z "$TAR_FILE" ]]; then + echo "Error: Failed to find downloaded artifact" + exit 1 +fi + +# Extract +echo "Extracting archive..." +tar -xzf "$TAR_FILE" -C "$TMP_DIR" + +# Install +echo "Installing to $INSTALL_PATH..." +mkdir -p "$INSTALL_PATH" +mv "$TMP_DIR/dsc" "$INSTALL_PATH/dsc" +chmod +x "$INSTALL_PATH/dsc" + +# Get version +VERSION=$("$INSTALL_PATH/dsc" --version 2>&1 || echo "unknown") + +echo "" +echo "Successfully installed DSC to $INSTALL_PATH/dsc" +echo "Version: $VERSION" +echo "From: https://github.com/$REPO/actions/runs/$RUN_ID" +echo "" +echo "To use DSC, add the following to your PATH:" +echo " export PATH=\"\$PATH:$INSTALL_PATH\"" From 4ef77b1b41829148283642603ee16b7fefc96f43 Mon Sep 17 00:00:00 2001 From: "G.Reijn" Date: Tue, 18 Nov 2025 01:18:06 +0100 Subject: [PATCH 5/5] Apply suggestions Mikey --- docs/installing-nightly.md | 187 +++++++++++++++++++------- sharedScripts/install_cli_nightly.ps1 | 182 ++++++++++++++++++------- 2 files changed, 269 insertions(+), 100 deletions(-) diff --git a/docs/installing-nightly.md b/docs/installing-nightly.md index f8b997346..e988be2b1 100644 --- a/docs/installing-nightly.md +++ b/docs/installing-nightly.md @@ -1,86 +1,177 @@ # Installing the "Nightly" build of DSC CLI -> **Note**: Nightly builds contain the latest development features but may have bugs or breaking -> changes. Only install if you want to test unreleased functionality. If you encounter issues, -> please [open an issue](https://github.com/PowerShell/DSC/issues/new). +> [!NOTE] +> Nightly builds contain the latest development features but may have bugs or breaking changes. +> Only install if you want to test unreleased functionality. If you encounter issues, please +> [open an issue](https://github.com/PowerShell/DSC/issues/new). -## Via script +## Using a script -> **Note**: This script requires the [GitHub CLI](https://cli.github.com/) to have already been -> installed. +> [!NOTE] +> This script requires the [GitHub CLI](https://cli.github.com/) to have already been installed. ### DSC CLI -This will install the latest nightly DSC CLI binary: +This will install the latest nightly DSC CLI binary to the following location depending on your +platform: - **Windows**: `%LOCALAPPDATA%\dsc\dsc.exe` - **Linux/macOS**: `~/.dsc/bin/dsc` -1. (macOS/Linux) Run the following: +1. Retrieve the appropriate script. You can use the PowerShell script for Windows and the Bash script for Linux and macOS. - ```sh - bash <(curl -Ls https://raw.githubusercontent.com/PowerShell/DSC/refs/heads/main/sharedScripts/install_cli_nightly.sh) - ``` + - Bash (Linux and macOS): -1. (Windows) Run the following in a PowerShell window: + ```sh + curl -o https://raw.githubusercontent.com/PowerShell/DSC/refs/heads/main/sharedScripts/install_cli_nightly.sh + ``` - ```powershell - iex "& { $(irm https://raw.githubusercontent.com/PowerShell/DSC/refs/heads/main/sharedScripts/install_cli_nightly.ps1) }" - ``` + - PowerShell (Windows): -1. Add the installation directory to your PATH environment variable to use `dsc` from any location. + ```powershell + Invoke-WebRequest -Uri https://raw.githubusercontent.com/PowerShell/DSC/refs/heads/main/sharedScripts/install_cli_nightly.ps1 -OutFile install_cli_nightly.ps1 + ``` + +1. Review the script before invoking it. +1. Invoke the script to install `dsc`: + + - Bash (Linux and macOS): + + ```sh + ./install_cli_nightly.sh + ``` + + - PowerShell (Windows): + + ```powershell + ./install_cli_nightly.ps1 + ``` + +1. Add the installation directory to your `PATH` environment variable. ## Manual -We are not currently publishing "nightly" releases, but you can grab the latest bits by viewing -the latest Action workflows for the `main` branch (or any other branch). +We don't currently publish nightly releases, but you can get the latest builds by viewing the most +recent Action workflows for the `main` branch. -The easiest way to get these artifacts is through the GitHub site. Follow -[this link](https://github.com/PowerShell/DSC/actions/workflows/rust.yml?query=branch%3Amain+is%3Asuccess) -to view the latest successful Action workflows for the `main` branch. Select it to show the related -artifacts. +The easiest way to get these artifacts is through the GitHub site. The following link directs you +to the latest successful Action workflows for merges to the `main` branch: -On the details page, select the artifact for your platform: + + +Select the first link in the list to show the related artifacts. At the bottom of the page, +download the artifact by selecting the artifact for your platform: - `windows-bin` for Windows - `linux-bin` for Linux - `macos-bin` for macOS -Extract the archive and place the `dsc` executable (or `dsc.exe` on Windows) in a directory in -your PATH. +Extract the archive using the following steps: + +- The artifact will be downloaded as `-bin.zip`. You can invoke the following commands to + extract the contents into a folder called `dsc` in the current directory: + + - Bash (Linux, macOS) + + ```sh + # Be sure to set this to the appropriate platform: 'linux' or 'macos' + platform="linux" + artifact="$platform-bin.zip" + # requires `unzip`, install if needed to expand the zip file + unzip $artifact + # Expand the tar file + tar -xvf bin.tar + # Move the subfolder containing the binaries and manifests + mv ./bin/debug dsc + ``` + + - PowerShell (Linux, macOS, Windows): + + ```powershell + # Be sure to set this to the appropriate platform: 'linux', 'macos', or 'windows' + $platform = 'linux' + $artifact = "$platform-bin.zip" + # Expand the zip file + Expand-Archive -Path $artifact -DestinationPath . + # Expand the tar file + tar -xvf bin.tar + # Move the subfolder containing the binaries and manifests + Move-Item -Path ./bin/debug -Destination dsc + ``` + +- Optionally, you can clean up the downloaded archive and intermediary files and folders: + + - Bash (Linux, macOS) + + ```sh + rm -rf ./bin ./bin.tar ./linux-bin.zip + ``` + + - PowerShell (Linux, macOS, Windows) + + ```powershell + Remove-Item -Path ./$artifact, ./bin.tar, ./bin -Recurse -Force + ``` + +- Finally, make sure to add the folder containing the extracted binaries and resource manifests to + your `PATH` environmental variable ## Advanced script options -### DSC CLI +### CLI installation options + +- Install to a custom directory: + + - Bash (Linux, macOS): + + ```bash + install_cli_nightly.sh --install-path /usr/local/bin + ``` + + - PowerShell (Windows): + + ```powershell + install_cli_nightly.ps1 -InstallPath C:\tools\dsc + ``` + +- Install from a forking repository: + + - Bash (Linux, macOS): + + ```bash + install_cli_nightly.sh --repo myusername/DSC + ``` + + - PowerShell (Windows): + + ```powershell + install_cli_nightly.ps1 -Repo myusername/DSC" + ``` -- macOS/Linux +- Install from a branch other than `main`: - ```sh - # install to a custom directory - bash <(curl -Ls https://raw.githubusercontent.com/PowerShell/DSC/refs/heads/main/sharedScripts/install_cli_nightly.sh) --install-path /usr/local/bin + - Bash (Linux, macOS): - # install from a fork repo - bash <(curl -Ls https://raw.githubusercontent.com/PowerShell/DSC/refs/heads/main/sharedScripts/install_cli_nightly.sh) --repo myusername/DSC + ```bash + install_cli_nightly.sh --branch feature-branch + ``` - # install from a custom branch - bash <(curl -Ls https://raw.githubusercontent.com/PowerShell/DSC/refs/heads/main/sharedScripts/install_cli_nightly.sh) --branch feature-branch + - PowerShell (Windows): - # install from a specific github action run - bash <(curl -Ls https://raw.githubusercontent.com/PowerShell/DSC/refs/heads/main/sharedScripts/install_cli_nightly.sh) --run-id 6146657618 - ``` + ```powershell + install_cli_nightly.ps1 -Branch feature-branch" + ``` -- Windows +- Install from a specific GitHub Action run: - ```powershell - # install to a custom directory - iex "& { $(irm https://raw.githubusercontent.com/PowerShell/DSC/refs/heads/main/sharedScripts/install_cli_nightly.ps1) } -InstallPath C:\tools\dsc" + - Bash (Linux, macOS): - # install from a fork repo - iex "& { $(irm https://raw.githubusercontent.com/PowerShell/DSC/refs/heads/main/sharedScripts/install_cli_nightly.ps1) } -Repo myusername/DSC" + ```bash + install_cli_nightly.sh --run-id 6146657618 + ``` - # install from a custom branch - iex "& { $(irm https://raw.githubusercontent.com/PowerShell/DSC/refs/heads/main/sharedScripts/install_cli_nightly.ps1) } -Branch feature-branch" + - PowerShell (Windows): - # install from a specific github action run - iex "& { $(irm https://raw.githubusercontent.com/PowerShell/DSC/refs/heads/main/sharedScripts/install_cli_nightly.ps1) } -RunId 6146657618" - ``` + ```powershell + install_cli_nightly.ps1 -RunId 6146657618" + ``` diff --git a/sharedScripts/install_cli_nightly.ps1 b/sharedScripts/install_cli_nightly.ps1 index 13e9c75b5..7d596f1de 100644 --- a/sharedScripts/install_cli_nightly.ps1 +++ b/sharedScripts/install_cli_nightly.ps1 @@ -1,58 +1,136 @@ +# Copyright (c) Microsoft Corporation. +# Licensed under the MIT License. +<# + .SYNOPSIS + Install the latest build of DSC from a GitHub Actions run + .DESCRIPTION + This script installs a build of DSC from the artifact generated by a GitHub Actions run. The + artifact is retrieved as a `.zip` file containing a `.tar` archive with the required files. + The script retrieves the artifacts, extracts the contents, and then installs them to the `dsc` + folder in `LOCALAPPDATA`. + You can override the installation directory with the `-InstallPath` parameter. + By default, the script installs the artifact from the latest successful build on the `main` + branch in the `PowerShell/DSC` repository. You can select a different branch with the `-Branch` + parameter, a different repository with the `-Repo` parameter, and a specific run with the + `-RunId` parameter. + By default, the script removes the downloaded artifact archive and intermediary files and + folders. Use the `-NoClean` parameter to skip this cleanup step if needed. + This script requires the `gh` CLI and `tar` executable. If either tool isn't installed and + available, the script throws an error. + .PARAMETER InstallPath + Defines the folder to install DSC to. Defaults to the `dsc` folder in `LOCALAPPDATA`. Define + this value as the full path to an alternate location. The script will create the directory + path if it doesn't already exist. + .PARAMETER Branch + Defines which branch to retrieve the build artifact from. Defaults to `main`. + .PARAMETER Repo + Defines the repository to retrieve the build artifact from. Defaults to `PowerShell/DSC`. + Define this value with the user or organization followed by a forward slash and then the + repository name, like `SomeUserName/DSC`. + .PARAMETER RunId + Defines a specific GitHub Action run to retrieve the build artifact from. When this parameter + isn't specified, the script retrieves the build artifact from the latest successful build + agains the specified branch and repository. + .PARAMETER NoClean + By default, the script deletes the downloaded artifact and intermediary files and folders after + installing DSC to the specified path. Use this parameter to prevent the script from removing + these files and folders if needed. +#> [cmdletbinding()] param( - [string]$RunId, - [string]$Branch, - [string]$Repo, - [string]$InstallPath + [string] + $InstallPath = [System.IO.Path]::combine($env:LOCALAPPDATA, "dsc"), + + [string] + $Branch = 'main', + + [ValidatePattern('^\w+\/\w+$')] + [string] + $Repo = 'PowerShell/DSC', + + [string] + $RunId, + + [switch] + $NoClean ) - -$ErrorActionPreference="Stop" - -if ($null -eq (Get-Command "gh" -ErrorAction SilentlyContinue)) { - throw "Please install the GitHub CLI: https://cli.github.com/" +begin { + [string[]]$missing = @() + if (-not (Get-Command 'gh' -ErrorAction SilentlyContinue)) { + $missing += 'gh' + } + if (-not (Get-Command 'tar' -ErrorAction SilentlyContinue)) { + $missing += 'tar' + } + if ($missing.Count -gt 0) { + throw (@( + "This script requires the 'gh' CLI and 'tar' executable." + 'Please install the missing tools before invoking the script again:' + "'$($missing -join "', '")'" + ) -join ' ') + } + if ([string]::IsNullOrEmpty($RunId)) { + $latestRunParameters = @( + '-R', $Repo + '--branch', $Branch + '--workflow', 'rust' + '--status', 'success' + '-L', 1 + '--json', 'databaseId' + '-q', '.[0].databaseId' + ) + $RunId = & gh run list @latestRunParameters + if ($LASTEXITCODE -ne 0 -or [string]::IsNullOrEmpty($RunId)) { + throw "Unable to find a successful build to install from" + } + } + $tmpDir = [System.IO.Path]::combine( + [System.IO.Path]::GetTempPath(), + [System.IO.Path]::GetRandomFileName() + ) + $installationFiles = Join-Path -Path $tmpDir -ChildPath 'bin' -AdditionalChildPath 'debug' + $dscExe = Join-Path $InstallPath "dsc.exe" } - -# Fetch -if (!$InstallPath) { - # Default install for Windows - $InstallPath = [System.IO.Path]::combine($env:LOCALAPPDATA, "dsc") +process { + $ErrorActionPreference = 'Stop' + #region Download the artifact + $downloadArtifactParams = @( + '-R', $Repo + $RunId + '-n', "$platform-bin" + "--dir", $tmpDir + ) + gh run download @downloadArtifactParams + if ($LASTEXITCODE -ne 0) { + throw "Unable to download artifact" + } + #endregion Download the artifact + #region Expand the tar file + $tar = Get-ChildItem -Path $tmpDir | Select-Object -First 1 + if ($null -eq $tar) { + throw "Failed to find downloaded artifact" + } + tar -xf $tar.FullName -C $tmpDir + if ($LASTEXITCODE -ne 0) { + throw "Unable to extract the tar file from the artifact" + } + #endregion Expand the tar file + #region Move extracted files to the install directory + # Create the install directory if it doesn't exist + if (-not (Test-Path -Path $InstallPath -PathType Container)) { + $null = New-Item -ItemType Directory -Force -Path $InstallPath + } + Move-Item -Path "$installationFiles/*" -Destination $InstallPath -Force -ErrorAction Ignore + #endregion Copy extracted files to the install directory + #region Retrieve and display version information + $versionStdout = & $dscExe --version; if(!$?) { throw } + $version = $versionStdout -replace 'dsc ', '' + Write-Information "Installed DSC CLI $version from https://github.com/$Repo/actions/runs/$RunId to $InstallPath" + #endregion Retrieve and display version information + Write-Information "Make sure to add $InstallPath to your PATH environment variable to use the 'dsc' command." } -if (!$Repo) { - $Repo = "PowerShell/DSC" +clean { + if (-not $NoClean) { + Remove-Item $tmpDir -Recurse + } } -if (!$Branch) { - $Branch = "main" -} -if (!$RunId) { - $RunId = & gh run list -R $Repo --branch $Branch --workflow rust --status success -L 1 --json databaseId -q ".[0].databaseId"; if(!$?) { throw } - if (!$RunId) { - throw "Failed to find a successful build to install from" - } -} - -$tmpDir = [System.IO.Path]::combine([System.IO.Path]::GetTempPath(), [System.IO.Path]::GetRandomFileName()) -& gh run download -R $Repo $RunId -n "$platform-bin" --dir $tmpDir; if(!$?) { throw } - -$tar = Get-ChildItem -Path $tmpDir | Select-Object -First 1 -if (!$tar) { - throw "Failed to find downloaded artifact" -} - -if (-not (Get-Command "tar" -ErrorAction SilentlyContinue)) { - throw "Please install 'tar' to extract the downloaded artifact." -} - -tar -xf $tar.FullName -C $tmpDir; if(!$?) { throw } - -$installationFiles = Join-Path $tmpDir 'bin' 'debug' -New-Item -ItemType Directory -Force -Path $InstallPath | Out-Null -Move-Item -Path "$installationFiles/*" -Destination $InstallPath -Force -ErrorAction Ignore - -$dscExe = Join-Path $InstallPath "dsc.exe" -$versionStdout = & $dscExe --version; if(!$?) { throw } -$version = $versionStdout -replace 'dsc ', '' -Write-Host "Installed DSC CLI $version from https://github.com/$Repo/actions/runs/$RunId to $InstallPath" -Write-Host "Make sure to add $InstallPath to your PATH environment variable to use the 'dsc' command." - -# Cleanup -Remove-Item $tmpDir -Recurse \ No newline at end of file