12 KiB
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.
See the Contributing Guidelines for more Git information, such as our installation instructions, contributing rules, and Git best practices.
Download source code
Clone this repository. It is a "superproject" and has a number of other repositories embedded within it as submodules. Please see the contributing guidelines and learn about submodules.
git clone https://github.com/PowerShell/PowerShell.git
cd PowerShell
Linux
Linux will need every submodule, so update them recursively:
git submodule update --init --recursive
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. Please follow the instructions on the Open Source Hub.
Windows
On Windows, many fewer submodules are needed, so specify them:
git submodule update --init --recursive -- src/monad src/windows-build src/Microsoft.PowerShell.Linux.Host/Modules/Pester
Setup build environment
We use the .NET Command Line Interface (dotnet
) to build
the managed components, and CMake to build the native components (on
non-Windows platforms). Install dotnet
by following their documentation.
The version of .NET CLI is very important, you want a recent 1.0.0 beta (not 1.0.1). The following instructions will install precisely 1.0.0.001718, though any 1.0.0 version should work.
Previous installations of DNX,
dnvm
, or older installations of .NET CLI can cause odd failures when running. Please check your version.
Linux
Tested on Ubuntu 14.04.
This installs the .NET CLI package feed. The benefit to this is that
installing dotnet
using apt-get
will also install all of its
dependencies automatically.
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=1.0.0.001718-1
The drawback of using the feed is that it gets out of date. The pinned
version is the most recent package published to the feed, but newer
packages are available. To upgrade the package, install it by
hand. Unfortunately, dpkg
does not handle dependency resolution, so
it is recommended to first install the older version from the feed,
and then upgrade it.
wget https://dotnetcli.blob.core.windows.net/dotnet/beta/Installers/Latest/dotnet-ubuntu-x64.latest.deb
sudo dpkg -i ./dotnet-ubuntu-x64.latest.deb
Additionally, PowerShell on Linux builds a native library, so install the following additional build / debug tools.
sudo apt-get install g++ cmake make lldb-3.6 strace
Windows
Tested on Windows 10 and Windows Server 2012 R2.
Invoke-WebRequest -Uri https://raw.githubusercontent.com/dotnet/cli/rel/1.0.0/scripts/obtain/install.ps1 -OutFile install.ps1
./install.ps1 -version 1.0.0.001718 -channel beta
If you meet Unable to cast COM object of type 'System.__ComObject' to interface type 'Microsoft.Cci.ISymUnmanagedWriter5'
, please install
Visual C++ Redistributable for Visual Studio 2015.
OS X
The OS X dependency installation instructions are not yet documented. You can try their PKG installer, or their obtain script. We do not (yet) routinely test on OS X, but some developers use PowerShell on 10.10 and 10.11.
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.
Start-PSBuild
from module ./PowerShellGitHubDev.psm1
on Windows
and Linux / OS X, if you are self-hosting PowerShell.
Specifically:
Linux
In Bash:
cd PowerShell
dotnet restore
./build.sh
Windows
In PowerShell:
cd PowerShell
dotnet restore
Import-Module .\PowerShellGitHubDev.psm1
Start-PSBuild # build CoreCLR version
Start-PSBuild -FullCLR # build FullCLR version
Tip: use Start-PSBuild -Verbose
switch to see more information
about build process.
Running
If you encounter any problems, see the known issues, otherwise open a new issue on GitHub.
The local managed host has built-in documentation via --help
.
Linux / OS X
- launch local shell with
./bin/powershell
- run tests with
./pester.sh
Windows
- launch
./bin/powershell.exe
- run tests with
./bin/powershell.exe -c "Invoke-Pester test/powershell"
Debugging
To enable debugging on Linux, follow the installation instructions for Experimental .NET Core Debugging in VS Code. You will also want to review their detailed instructions.
VS Code will place a .vscode
directory in the PowerShell folder.
This contains the launch.json
file, which you will customize using
the instructions below. You will also be prompted to create a
tasks.json
file.
Currently, debugging supports attaching to a currently running
powershell process. Assuming you've created a launch.json
file
correctly, within the "configuration" section, use the below settings:
"configurations": [
{
"name": "powershell",
"type": "coreclr",
"request": "attach",
"processName": "powershell"
}
]
VS Code will now attach to a running powershell
process. Start
powershell, then (in VS Code) press F5
to begin the debugger.
PowerShell Remoting Protocol
PSRP communication is tunneled through OMI using the omi-provider
.
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.
PSRP support is not built automatically. See the detailed notes on how to enable it.
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="*"}
You can also set the
TrustedHosts
to include the target's IP address.
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 theomiserver
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
Detailed Build Script Notes
This sections explains the build scripts.
The variable $BIN
is the output directory, bin
.
Managed
Builds with dotnet
. Publishes all dependencies into the bin
directory.
Emits its own native host as bin/powershell
. Uses a Linux
configuration to
add a preprocessor definition. The CORECLR
definition is added only when
targeting the netstandard1.5
framework. The LINUX
definition is added only
when --configuration Linux
is used.
cd src/Microsoft.PowerShell.Linux.Host
dotnet publish --configuration Linux
Native
The libpsl-native.so
library consists of native functions that
CorePsPlatform.cs
P/Invokes.
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.
PSRP
OMI
PSRP support is not built by ./build.sh
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
Note that the OMI build steps can be done with ./omibuild.sh
.
Build OMI from source in developer mode:
cd src/omi/Unix
./configure --dev
make -j
Provider
The provider uses CMake to build, link, and register with OMI.
cd src/omi-provider
cmake .
make -j
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.
FullCLR PowerShell
On Windows, we also build Full PowerShell for .NET 4.5.1
Setup environment
- You need Visual Studio to compile the native host
powershell.exe
.
If you don't have any visual studio installed, you can use Visual Studio 2013 Community edition.
- Add
msbuild
toPATH
/ create PowerShell alias to it.
Set-Alias msbuild C:\WINDOWS\Microsoft.NET\Framework\v4.0.30319\MSBuild.exe
- Install CMake and add it to
PATH.
You can install it from [Chocolatey][] or manually.
choco install cmake.portable
- Install dotnet-cli via their documentation
Building
Start-PSBuild -FullCLR
Troubleshooting: the build logic is relatively simple and contains following steps:
- building managed DLLs:
dotnet publish --runtime net451
- generating Visual Studio project:
cmake -G "$cmakeGenerator"
- building
powershell.exe
from generated solution:msbuild powershell.sln
All this steps can be run separately from Start-PSBuild
, don't
hesitate to experiment.
Running
Running FullCLR version is not as simple as CoreCLR version.
If you just run , you will get a .\binFull\powershell.exe
powershell
process, but all the interesting DLLs (i.e. System.Management.Automation.dll
)
would be loaded from the GAC, not your binFull
build 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 registry key 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 an archive with FullCLR bits on every CI build with AppVeyor.
- 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