2017-11-01 23:55:46 +01:00
# Build PowerShell on Windows for .NET Core
2016-03-30 23:54:49 +02:00
2017-04-11 18:44:43 +02:00
This guide will walk you through building PowerShell on Windows, targeting .NET Core.
2016-08-27 02:28:45 +02:00
We'll start by showing how to set up your environment from scratch.
2016-03-30 23:54:49 +02:00
2017-11-01 23:55:46 +01:00
## Environment
2016-03-30 23:54:49 +02:00
These instructions are tested on Windows 10 and Windows Server 2012
R2, though they should work anywhere the dependencies work.
2017-11-01 23:55:46 +01:00
### Git Setup
2016-04-14 01:21:23 +02:00
Using Git requires it to be setup correctly; refer to the
[README ](../../README.md ) and
2016-04-22 23:37:26 +02:00
[Contributing Guidelines ](../../.github/CONTRIBUTING.md ).
2016-04-14 01:21:23 +02:00
2016-08-27 02:28:45 +02:00
This guide assumes that you have recursively cloned the PowerShell repository and `cd` ed into it.
2016-04-14 01:21:23 +02:00
2017-11-01 23:55:46 +01:00
### Visual Studio
2016-08-20 00:43:40 +02:00
2017-04-11 18:44:43 +02:00
You will need to install an edition of Visual Studio 2015 (Community, Enterprise, or Professional) with the optional feature 'Common Tools for Visual C++' installed.
2016-08-27 02:28:45 +02:00
The free Community edition of Visual Studio 2015 can be downloaded [here ](https://www.visualstudio.com/visual-studio-community-vs/ ).
2016-08-20 00:43:40 +02:00
2017-11-08 04:40:40 +01:00
### Visual Studio Code
Building PowerShell using [Visual Studio Code ](https://code.visualstudio.com/ ) depends on the PowerShell executable to be called `pwsh` which means
that you must have PowerShell Core 6 Beta.9 (or newer) installed to successfully build this project (typically for the purpose of debugging).
2017-11-01 23:55:46 +01:00
### .NET CLI
2016-03-30 23:54:49 +02:00
2016-07-22 00:50:04 +02:00
We use the [.NET Command Line Interface][dotnet-cli] (`dotnet`) to build PowerShell.
2017-11-01 23:55:46 +01:00
The version we are currently using is `2.0.0` .
2016-07-22 00:50:04 +02:00
The `Start-PSBootstrap` function will automatically install it and add it to your path:
2016-04-14 01:21:23 +02:00
```powershell
2016-05-18 22:58:59 +02:00
Import-Module ./build.psm1
2016-04-14 01:21:23 +02:00
Start-PSBootstrap
```
2017-11-01 23:55:46 +01:00
Or you can call `Install-Dotnet` directly:
2016-03-30 23:54:49 +02:00
```powershell
2017-11-01 23:55:46 +01:00
Install-Dotnet
2016-03-30 23:54:49 +02:00
```
2017-11-01 23:55:46 +01:00
It removes the previously installed version of .NET CLI and install the version that PowerShell Core depends on.
2016-08-27 02:28:45 +02:00
If you have any problems installing `dotnet` , please see their [documentation][cli-docs].
2016-03-30 23:54:49 +02:00
2017-03-28 00:26:22 +02:00
[dotnet-cli]: https://github.com/dotnet/cli
[cli-docs]: https://www.microsoft.com/net/core#windowscmd
2016-03-30 23:54:49 +02:00
2017-11-01 23:55:46 +01:00
## Build using our module
2016-03-30 23:54:49 +02:00
2016-08-27 02:28:45 +02:00
We maintain a [PowerShell module ](../../build.psm1 ) with the function `Start-PSBuild` to build PowerShell.
2016-03-30 23:54:49 +02:00
```powershell
2016-05-18 22:58:59 +02:00
Import-Module ./build.psm1
2016-03-30 23:54:49 +02:00
Start-PSBuild
```
2017-11-01 23:55:46 +01:00
Congratulations! If everything went right, PowerShell is now built and executable as `./src/powershell-win-core/bin/Debug/netcoreapp2.0/win7-x64/publish/pwsh` .
2016-04-05 04:07:29 +02:00
2017-11-01 23:55:46 +01:00
This location is of the form `./[project]/bin/[configuration]/[framework]/[rid]/publish/[binary name]` ,
2017-04-11 18:44:43 +02:00
and our project is `powershell` , configuration is `Debug` by default,
2017-11-01 23:55:46 +01:00
framework is `netcoreapp2.0` , runtime identifier is `win7-x64` by default,
and binary name is `pwsh` .
2017-04-11 18:44:43 +02:00
The function `Get-PSOutput` will return the path to the executable;
2016-08-27 02:28:45 +02:00
thus you can execute the development copy via `& (Get-PSOutput)` .
2016-04-05 04:07:29 +02:00
2017-04-11 18:44:43 +02:00
The `powershell` project is the .NET Core PowerShell host.
It is the top level project, so `dotnet build` transitively builds all its dependencies,
2017-11-01 23:55:46 +01:00
and emits a `pwsh` executable.
2016-08-27 02:28:45 +02:00
The cross-platform host has built-in documentation via `--help` .
2016-04-05 04:07:29 +02:00
You can run our cross-platform Pester tests with `Start-PSPester` .
2016-08-14 22:52:40 +02:00
2017-11-01 23:55:46 +01:00
## Building in Visual Studio
2016-08-14 22:52:40 +02:00
2017-03-28 00:26:22 +02:00
We currently have the issue [#3400 ](https://github.com/PowerShell/PowerShell/issues/3400 ) tracking this task.