This guide will walk you through building PowerShell on Linux. We'll start by showing how to set up your environment from scratch.
These instructions are written assuming the Ubuntu 14.04 LTS, since that's the distro the team uses. The build module works on a best-effort basis for other distributions.
Using Git requires it to be setup correctly; refer to the README and Contributing Guidelines.
This guide assumes that you have recursively cloned the PowerShell
repository and cd
ed into it.
We use the .NET Command Line Interface (dotnet
) to
build the managed components, and CMake to build the native
components. Install the following packages for the toolchain:
dotnet
: Must be installed from theStart-PSBootstrap
module as described below.cmake
make
g++
Unfortunately, the apt-get
feed for dotnet
has been deprecated,
and the latest version is only distributed in the form of three
separate packages, which require manual dependency resolution.
Installing the toolchain is as easy as running Start-PSBootstrap
in
PowerShell. Of course, this requires a self-hosted copy of PowerShell
on Linux.
Fortunately, this is as easy as downloading and installing the
package. Unfortunately, while the repository is still private, the
package cannot be downloaded as simply as with wget
. We have a
script that wraps the GitHub API and uses a personal access token to
authorize in order to obtain the package.
The ./tools/download.sh
script will also install the PowerShell package.
You can alternativelly download via a browser, upload it to your box via some other method, and manually install it.
In Bash:
git clone https://github.com/PowerShell/powerShell.git
If git prompts you for your password, you need to enter your access token. Click GitHub Help for how to get access token.
GITHUB_TOKEN=<replace with your token>
./tools/download.sh
powershell
You should now be in a powershell
console host that is installed
separately from any development copy you're about to build. Just
import our module, bootstrap the dependencies, and build!
In PowerShell:
Change your directory to the one that you just cloned, for example, ``./src/PowerShell`.
Import-Module ./build.psm1
Start-PSBootstrap
The Start-PSBootstrap
function does the following:
- Adds the LLVM package feed
- Installs our dependencies combined with the dependencies of the .NET
CLI toolchain via
apt-get
- Uninstalls any prior versions of .NET CLI
- Downloads and installs the latest .NET CLI 1.0.0-preview2 SDK to
~/.dotnet
If you want to use dotnet
outside of Start-PSBuild
, add ~/.dotnet
to your
PATH
environment variable.
If you have any problems installing dotnet
, please see their
documentation.
The version of .NET CLI is very important, you need a recent build of 1.0.0 (not 1.0.1).
Previous installations of DNX, dnvm
, or older installations of .NET
CLI can cause odd failures when running. Please check your version and
uninstall prior any prior versions.
We maintain a PowerShell module with
the function Start-PSBuild
to build PowerShell. Since this is
PowerShell code, it requires self-hosting. If you have followed the
toolchain setup section above, you should have powershell
installed.
If you cannot or do not want to self-host,
Start-PSBuild
is just a convenience; you can execute each step of the build process yourself in Bash; see [Build manually][#Build manually] below.
Import-Module ./build.psm1
git submodule init
git submodule update
Start-PSBuild
Congratulations! If everything went right, PowerShell is now built.
The Start-PSBuild
script will output the location of the executable:
./src/powershell/bin/Linux/netcoreapp1.0/ubuntu.14.04-x64/powershell
.
You should now be running the powershell
that is what you just built if your run the above executable. You can run our cross-platform Pester tests with Start-PSPester
, and
our xUnit tests with Start-PSxUnit
.
The following goes into detail about what Start-PSBuild
does.
The libpsl-native.so
library consists of native functions that
CorePsPlatform.cs
P/Invokes.
pushd src/libpsl-native
cmake -DCMAKE_BUILD_TYPE=Debug .
make -j
make test
popd
This library will be emitted in the src/powershell
project, where dotnet
consumes it as "content" and thus automatically deploys it.
The powershell
project is the .NET Core PowerShell host. It is the top level
project, so dotnet build
transitively builds all its dependencies, and emits a
powershell
executable. The --configuration Linux
flag is necessary to ensure
that the preprocessor definition LINUX
is defined (see issue #673).
dotnet restore
cd src/powershell
dotnet build --configuration Linux
The executable will be in
./bin/[configuration]/[framework]/[rid]/[binary name]
, where our
configuration is Linux
, framework is netcoreapp1.0
, runtime
identifier is ubuntu.14.04-x64
, and binary name is powershell
. The
function Get-PSOutput
will return the path to the executable; thus
you can execute the development copy via & (Get-PSOutput)
.
For deploying PowerShell, dotnet publish
will emit a publish
directory that contains a flat list of every dependency required for
PowerShell. This can be copied to, say, /usr/local/share/powershell
or packaged.