PowerShell on Linux / OS X / Windows

	Ubuntu 14.04	Windows
master

Waffle.io scrum board

Obtain the source code

Setup Git

Install Git, the version control system.

sudo apt-get install git

If you do not have a preferred method of authentication, enable the storage credential helper, which will cache your credentials in plaintext on your system, so use a token.

git config --global credential.helper store

See the Contributing Guidelines for more Git information.

Download source code

Clone this repository recursively, as it's the superproject with a number of submodules.

git clone --recursive https://github.com/PowerShell/PowerShell-Linux.git

The src/omi submodule requires your GitHub user to have joined the Microsoft organization. If it fails to check out, Git will bail and not check out further submodules either.

On Windows, many fewer submodules are needed, so don't use clone --recursive.

Instead run:

git clone https://github.com/PowerShell/PowerShell-Linux.git
git submodule update --init --recursive -- src/monad src/windows-build test/Pester

Setup build environment

We use the .NET Command Line Interface (dotnet-cli) to build the managed components, and CMake to build the native components (on non-Windows platforms). Install dotnet-cli by following their documentation (make sure to install the dotnet-nightly package on Linux to get the latest version).

Note that OS X dependency installation instructions are not yet documented, and Windows only needs dotnet-cli.

Previous installations of DNX or dnvm can cause dotnet-cli to fail.

Linux

Tested on Ubuntu 14.04.

sudo sh -c 'echo "deb [arch=amd64] http://apt-mo.trafficmanager.net/repos/dotnet/ trusty main" > /etc/apt/sources.list.d/dotnetdev.list'
sudo apt-key adv --keyserver apt-mo.trafficmanager.net --recv-keys 417A0893
sudo apt-get update
sudo apt-get install dotnet-nightly

Then install the following additional build / debug tools:

sudo apt-get install g++ cmake make lldb-3.6 strace

OMI

To develop on the PowerShell Remoting Protocol (PSRP) for Linux, you'll need to be able to compile OMI, which additionally requires:

sudo apt-get install libpam0g-dev libssl-dev libcurl4-openssl-dev libboost-filesystem-dev 

Building

The command dotnet restore must be done at least once from the top directory to obtain all the necessary .NET packages.

Build with ./build.sh on Linux and OS X, and ./build.ps1 on Windows.

Specifically:

Linux

In Bash:

cd PowerShell-Linux
dotnet restore
./build.sh

Windows

In PowerShell:

cd PowerShell-Linux
dotnet restore
./build.ps1

Running

If you encounter any problems, see the known issues, otherwise open a new issue on GitHub.

Linux / OS X

• launch local shell with ./bin/powershell
• launch local shell in LLDB with ./debug.sh
• launch omiserver for PSRP (and in LLDB) with ./prsp.sh, and connect with Enter-PSSession from Windows

Windows

Launch ./bin/powershell.exe. The console output isn't the prettiest, but the vast majority of Pester tests pass. Run them in the console with Invoke-Pester test/powershell.

PowerShell Remoting Protocol

PSRP communication is tunneled through OMI using the omi-provider.

These build steps are not part of the ./build.sh script.

PSRP has been observed working on OS X, but the changes made to OMI to accomplish this are not even beta-ready and need to be done correctly. They exist on the andschwa-osx branch of the OMI repository.

Build OMI

cd src/omi/Unix
./configure --dev
make -j
cd ../../..

Build Provider

The provider uses CMake to build, link, and register with OMI.

cd src/omi-provider
cmake .
make -j
cd ../..

The provider also maintains its own native host library to initialize the CLR, but there are plans to refactor .NET's packaged host as a shared library.

Running

Some initial setup on Windows is required. Open an administrative command prompt and execute the following:

winrm set winrm/config/Client @{AllowUnencrypted="true"}
winrm set winrm/config/Client @{TrustedHosts="*"}

Then on Linux, launch omiserver in the debugger (after building with the instructions above):

./psrp.sh
run

The run command is executed inside of LLDB (the debugger) to start the omiserver process.

Now in a PowerShell prompt on Windows (opened after setting the WinRM client configurations):

Enter-PSSession -ComputerName <IP address of Linux machine> -Credential $cred -Authentication basic

The $cred variable can be empty; a credentials prompt will appear, enter any fake credentials you wish as authentication is not yet implemented.

The IP address of the Linux machine can be obtained with:

ip -f inet addr show dev eth0

Desired State Configuration

DSC support is in its infancy.

DSC also uses OMI, so build it first, then build DSC against it. Unfortunately, DSC cannot be configured to look for OMI elsewhere, so for now you need to symlink it to the expected location.

ln -s ../omi/Unix/ omi-1.0.8
./configure --no-rpm --no-dpkg --local
make -j

Detailed Build Script Notes

This explains ./build.sh.

The variable $BIN is the output directory, bin.

Managed

Builds with dotnet-cli. Publishes all dependencies into the bin directory. Emits its own native host as bin/powershell.

cd src/Microsoft.PowerShell.Linux.Host
dotnet publish --framework dnxcore50 --output $BIN
# Copy files that dotnet-publish doesn't currently deploy
cp *.ps1xml *_profile.ps1 $BIN

Native

• libpsl-native.so: native functions that CorePsPlatform.cs P/Invokes
• api-ms-win-core-registry-l1-1-0.dll: registry stub to prevent missing DLL error on shutdown

libpsl-native

Driven by CMake, with its own unit tests using Google Test.

cd src/libpsl-native
cmake -DCMAKE_BUILD_TYPE=Debug .
make -j
ctest -V
# Deploy development copy of libpsl-native
cp native/libpsl-native.* $BIN

The output is a .so on Linux and .dylib on OS X. It is unnecessary for Windows.

registry-stub

Provides RegCloseKey() to satisfy the disposal of SafeHandle objects on shutdown.

cd src/registry-stub
make
cp api-ms-win-core-registry-l1-1-0.dll $BIN

FullCLR PowerShell

On windows, we also build Full PowerShell for .NET 4.5.1

Setup environment

• You need Visual Studio to compile native host powershell.exe. If you don't have any visual studio installed, you can use Visual Studio 2013 Community edition.

• Add msbuild to PATH / create PowerShell alias to it.

• Install cmake and add it to PATH. You can install it from chocolatey or download cmake.

choco install cmake.portable

• dotnet-cli (see above for details)

Building

.\build.FullCLR.ps1

Troubleshooting: the build logic is relatively simple and contains following steps:

• building managed dlls: dotnet publish --runtime dnx451
• generating Visual Studio project: cmake -G "$cmakeGenerator"
• building powershell.exe from generated solution: msbuild powershell.sln

All this steps can be run separately from .\build.FullCLR.ps1, don't hesitate to experiment.

Running

Running FullCLR version is not as simple as CoreCLR version.

If you just run .\binFull\powershell.exe, you will get powershell process, but all interesting dlls (i.e. System.Management.Automation.dll) would be loaded from GAC, not your binFull directory.

@lzybkr wrote a module to deal with it and run side-by-side

Import-Module .\PowerShellGithubDev.psm1
Start-DevPSGithub -binDir $pwd\binFull

Troubleshooting: default for powershell.exe that we build is x86. There is a separate execution policy regkey for x86, and it's likely that you didn't bypass enable it. From powershell.exe (x86) run

Set-ExecutionPolicy Bypass

Running from CI server

We publish archive with fullCLR bits on every CI build.

• Download zip package from artifacts tab of the particular build.
• Unblock zip file: right-click in file explorer -> properties -> check 'Unblock' checkbox -> apply
• Extract zip file to $bin directory
• Start-DevPSGithub -binDir $bin