diff --git a/docs/installing-nightly.md b/docs/installing-nightly.md new file mode 100644 index 000000000..f8b997346 --- /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..13e9c75b5 --- /dev/null +++ b/sharedScripts/install_cli_nightly.ps1 @@ -0,0 +1,58 @@ +[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/" +} + +# Fetch +if (!$InstallPath) { + # Default install for Windows + $InstallPath = [System.IO.Path]::combine($env:LOCALAPPDATA, "dsc") +} +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 = 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 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\""