PowerShell Deployment and Usage Guide

Prerequisites

• Operating System: Windows, macOS, or Linux (PowerShell is cross-platform)
• Runtime: .NET 6.0 or later (PowerShell 7+ is built on .NET Core)
• Git: Required for cloning the repository
• Build Tools: Depending on your platform:
  • Windows: Visual Studio 2022 or .NET SDK
  • Linux/macOS: .NET SDK 6.0+
• Optional: Docker for container-based development

Installation

Clone the Repository

git clone https://github.com/PowerShell/PowerShell.git
cd PowerShell

Build Instructions by Platform

Windows

1. Open PowerShell as Administrator
2. Navigate to the cloned repository
3. Run the build script:

.\build.ps1

Linux

1. Install .NET 6.0+ SDK
2. Navigate to the cloned repository
3. Run the build script:

./build.sh

macOS

1. Install .NET 6.0+ SDK
2. Navigate to the cloned repository
3. Run the build script:

./build.sh

Configuration

Environment Variables

PowerShell doesn't require specific environment variables for basic operation, but you may want to configure:

• POWERSHELL_TELEMETRY_OPTOUT=1 to disable telemetry
• POWERSHELL_UPDATECHECK=Off to disable update checks

Configuration Files

PowerShell uses the following configuration files:

• $HOME/.config/powershell/profile.ps1 (Unix)
• $HOME/Documents/PowerShell/profile.ps1 (Windows)
• $HOME/.config/powershell/Microsoft.PowerShell_profile.ps1 (Unix)
• $HOME/Documents/PowerShell/Microsoft.PowerShell_profile.ps1 (Windows)

Module Paths

PowerShell searches for modules in these paths by default:

• $HOME/.local/share/powershell/Modules (Unix)
• $HOME/.config/powershell/Modules (Unix)
• $HOME\Documents\PowerShell\Modules (Windows)
• $PSHOME\Modules (System-wide)

Build & Run

Development Build

# Clean previous build
./clean.sh

# Build in Release mode
./build.sh -Configuration Release

Running PowerShell

From Source

# Navigate to the output directory
cd bin/Release/net6.0

# Run PowerShell
./pwsh

Installed Version

# After installation, run PowerShell directly
pwsh

Testing

# Run all tests
./test.ps1

# Run specific test suite
./test.ps1 -TestFile "Engine.Tests"

Deployment

Platform-Specific Installation

Windows

# Install via MSI package
Start-Process msiexec.exe -Wait -ArgumentList "/I PowerShell-7.3.6-win-x64.msi /quiet"

Linux (Ubuntu/Debian)

# Add Microsoft repository
wget -q https://packages.microsoft.com/config/ubuntu/22.04/packages-microsoft-prod.deb
sudo dpkg -i packages-microsoft-prod.deb

# Install PowerShell
sudo apt-get update
sudo apt-get install -y powershell

macOS

# Install via Homebrew
brew install --cask powershell

Docker Deployment

# Pull the official PowerShell image
docker pull mcr.microsoft.com/powershell:latest

# Run PowerShell in a container
docker run -it mcr.microsoft.com/powershell pwsh

Package Distribution

PowerShell can be packaged as:

• Windows: MSI installer
• Linux: DEB/RPM packages
• macOS: PKG installer
• Universal: ZIP archives

Troubleshooting

Common Build Issues

"dotnet" command not found

Solution: Install .NET 6.0+ SDK from https://dotnet.microsoft.com/download

Permission denied on build scripts

Solution:

chmod +x build.sh
chmod +x clean.sh

Build fails on Linux/macOS

Solution: Ensure all dependencies are installed:

sudo apt-get install -y curl libunwind8 gettext

Runtime Issues

Module not found

Solution: Check module paths:

$env:PSModulePath -split ';'

PowerShell won't start

Solution: Check for corrupted installation:

# Reset PowerShell configuration
Remove-Item -Recurse -Force $HOME/.config/powershell

Network connectivity issues with cmdlets

Solution: Check firewall settings and network permissions:

# Test network connectivity
Test-Connection -ComputerName github.com

Development Issues

Test failures

Solution: Run tests with verbose output:

./test.ps1 -Verbose

Code analysis warnings

Solution: Run code analysis:

./build.ps1 -CodeAnalysis

Debugging issues

Solution: Use Visual Studio or VS Code with PowerShell extension:

# Launch with debugger
pwsh -Debug

Performance Issues

Slow startup

Solution: Profile startup:

# Profile startup time
Measure-Command { pwsh -NoProfile -Command "exit" }

High memory usage

Solution: Check for memory leaks:

# Monitor memory usage
Get-Process pwsh | Select-Object ProcessName, WorkingSet