Merge pull request #768 from PowerShell/andschwa/docs
Update documentation
This commit is contained in:
commit
ff921297a9
|
@ -21,27 +21,21 @@ components. Install the following packages for the toolchain:
|
|||
- `cmake`
|
||||
- `make`
|
||||
- `g++`
|
||||
- `libunwind8`
|
||||
- `libicu52`
|
||||
|
||||
And for debgging:
|
||||
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.
|
||||
|
||||
- `strace`
|
||||
- `lldb-3.6`
|
||||
**To ease this process, just run `./bootstrap.sh` and enter password
|
||||
for `sudo` when prompted.**
|
||||
|
||||
In order to get `dotnet`, we need to add an additional package source:
|
||||
The [bootstrap script](../../bootstrap.sh) does the following:
|
||||
|
||||
```sh
|
||||
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
|
||||
```
|
||||
|
||||
Then install the packages you need:
|
||||
|
||||
```sh
|
||||
sudo apt-get install dotnet cmake make g++ libunwind8 libicu52 strace lldb-3.6
|
||||
```
|
||||
- Adds the LLVM package feed
|
||||
- Installs our dependencies combined with the dependencies of the .NET
|
||||
CLI toolchain via `apt-get`
|
||||
- Installs the .NET CLI host, shared framework, and SDK by downloading
|
||||
the three `.deb` packages to `/tmp` and using `dpkg -i`
|
||||
|
||||
[dotnet-cli]: https://github.com/dotnet/cli#new-to-net-cli
|
||||
[CMake]: https://cmake.org/cmake/help/v2.8.12/cmake.html
|
||||
|
@ -52,21 +46,12 @@ sudo apt-get install dotnet cmake make g++ libunwind8 libicu52 strace lldb-3.6
|
|||
If you have any problems installing `dotnet`, please see their
|
||||
[documentation][cli-docs].
|
||||
|
||||
The version of .NET CLI is very important, you want a recent build of
|
||||
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.
|
||||
|
||||
The drawback of using the feed is that it gets out of date. 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.
|
||||
|
||||
```sh
|
||||
wget https://dotnetcli.blob.core.windows.net/dotnet/beta/Installers/Latest/dotnet-ubuntu-x64.latest.deb
|
||||
sudo dpkg -i ./dotnet-ubuntu-x64.latest.deb
|
||||
```
|
||||
CLI can cause odd failures when running. Please check your version and
|
||||
uninstall prior any prior versions.
|
||||
|
||||
[cli-docs]: https://dotnet.github.io/getting-started/
|
||||
|
||||
|
@ -79,22 +64,22 @@ the submodules:
|
|||
```sh
|
||||
git clone https://github.com/PowerShell/PowerShell.git
|
||||
cd PowerShell
|
||||
git submodule update --init --recursive -- src/windows-build src/libpsl-native src/Microsoft.PowerShell.Linux.Host/Modules/Pester
|
||||
git submodule update --init -- src/windows-build src/Modules/Pester src/libpsl-native/test/googletest
|
||||
```
|
||||
|
||||
Build using our module
|
||||
======================
|
||||
|
||||
We maintain a `PowerShellGitHubDev.psm1` PowerShell module with the
|
||||
function `Start-PSBuild` to build PowerShell. Since this is PowerShell
|
||||
code, it requires self-hosting. Fortunately, this is as easy as
|
||||
downloading and installing the package. Unfortunately, while the
|
||||
repository is still private, the package cannot be downloaded as
|
||||
We maintain a [PowerShell module](../../PowerShellGitHubDev.psm1) with
|
||||
the function `Start-PSBuild` to build PowerShell. Since this is
|
||||
PowerShell code, it requires self-hosting. 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 and obtain the package.
|
||||
|
||||
> You can alternativelly download via a browser and upload it to your
|
||||
> box via some other method
|
||||
> box via some other method.
|
||||
|
||||
```sh
|
||||
GITHUB_TOKEN=<replace with your token> ./download.sh
|
||||
|
@ -106,18 +91,23 @@ 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 and build!
|
||||
|
||||
> 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.
|
||||
|
||||
```powershell
|
||||
Import-Module ./PowerShellGitHubDev.psm1
|
||||
Start-PSBuild
|
||||
```
|
||||
|
||||
Congratulations! If everything went right, PowerShell is now built and
|
||||
executable as `./bin/powershell`.
|
||||
Congratulations! If everything went right, PowerShell is now built.
|
||||
The `Start-PSBuild` script will output the location of the executable:
|
||||
`./src/Microsoft.PowerShell.Host/bin/Linux/netstandardapp1.5/ubuntu.14.04-x64/powershell`.
|
||||
|
||||
> Note that the `./build.sh` script is deprecated and may be removed
|
||||
> Note that the `./build.sh` script is deprecated and will be removed
|
||||
|
||||
You can run our cross-platform Pester tests with `./bin/powershell -c
|
||||
"Invoke-Pester test/powershell"`.
|
||||
You can run our cross-platform Pester tests with `Start-PSPester`, and
|
||||
our xUnit tests with `Start-PSxUnit`.
|
||||
|
||||
Build manually
|
||||
==============
|
||||
|
@ -138,29 +128,36 @@ make test
|
|||
popd
|
||||
```
|
||||
|
||||
This library will be emitted in the
|
||||
`src/Microsoft.PowerShell.Linux.Host` project, where `dotnet` consumes
|
||||
it as "content" and thus automatically deploys it.
|
||||
This library will be emitted in the `src/Microsoft.PowerShell.Host`
|
||||
project, where `dotnet` consumes it as "content" and thus
|
||||
automatically deploys it.
|
||||
|
||||
Build the managed projects
|
||||
--------------------------
|
||||
|
||||
The `Linux.Host`, while poorly named, is the cross-platform host for
|
||||
The `Microsoft.PowerShell.Host` project is the cross-platform host for
|
||||
PowerShell targetting .NET Core. It is the top level project, so
|
||||
`dotnet publish` transitively builds all its dependencies, and emits a
|
||||
`powershell` executable and all necessary libraries (both native and
|
||||
managed) in a flat directory (specified with `--output`, otherwise
|
||||
automatically nested depending on runtime, configuration, and
|
||||
framework, see [issue #685][]). The `--configuration Linux` flag is
|
||||
`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][]).
|
||||
|
||||
```sh
|
||||
dotnet restore
|
||||
dotnet publish --output bin --configuration Linux src/Microsoft.PowerShell.Linux.Host
|
||||
cd src/Microsoft.PowerShell.Host
|
||||
dotnet build --configuration Linux
|
||||
```
|
||||
|
||||
PowerShell and all necessary components should now be in the `bin` folder.
|
||||
The executable will be in
|
||||
`./bin/[configuration]/[framework]/[rid]/[binary name]`, where our
|
||||
configuration is `Linux`, framework is `netstandardapp1.5`, 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.
|
||||
|
||||
[issue #673]: https://github.com/PowerShell/PowerShell/issues/673
|
||||
[issue #685]: https://github.com/PowerShell/PowerShell/issues/685
|
||||
|
|
|
@ -18,8 +18,8 @@ dependencies.
|
|||
brew install openssl cmake wget
|
||||
```
|
||||
|
||||
Instead of using .NET CLI's Ubuntu package feed, you will want to use
|
||||
the official PKG installer.
|
||||
Instead of using Linux `./bootstrap.sh` to install .NET CLI's Ubuntu
|
||||
packages, you will want to use the official PKG installer for OS X.
|
||||
|
||||
```sh
|
||||
wget https://dotnetcli.blob.core.windows.net/dotnet/beta/Installers/Latest/dotnet-dev-osx-x64.latest.pkg
|
||||
|
@ -35,3 +35,11 @@ Instead of installing the Ubuntu package of PowerShell, download the
|
|||
`pkg` from our GitHub releases page using your browser, complete the
|
||||
wizard, start a `powershell` session, and use `Start-PSBuild` from the
|
||||
module.
|
||||
|
||||
The output directory will be slightly different because your runtime
|
||||
identifier is different. PowerShell will be at
|
||||
`./src/Microsoft.PowerShell.Host/bin/Linux/netstandardapp1.5/osx.10.11-x64/powershell`,
|
||||
or `osx.10.10` depending on your operating system version. Note that
|
||||
configration is still `Linux` because it would be silly to make yet
|
||||
another separate configuration when it's used soley to work-around a
|
||||
CLI issue.
|
||||
|
|
|
@ -21,7 +21,7 @@ it to your PowerShell session's path:
|
|||
```powershell
|
||||
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-beta-002198
|
||||
$env:Path += ";$env:LocalAppData\Microsoft\dotnet\cli
|
||||
$env:Path += ";$env:LocalAppData\Microsoft\dotnet\cli"
|
||||
```
|
||||
|
||||
If you have any problems installing `dotnet`, please see their
|
||||
|
@ -52,14 +52,14 @@ the submodules:
|
|||
```sh
|
||||
git clone https://github.com/PowerShell/PowerShell.git
|
||||
cd PowerShell
|
||||
git submodule update --init -- src/windows-build src/Microsoft.PowerShell.Linux.Host/Modules/Pester
|
||||
git submodule update --init -- src/windows-build src/Modules/Pester
|
||||
```
|
||||
|
||||
Build using our module
|
||||
======================
|
||||
|
||||
We maintain a `PowerShellGitHubDev.psm1` PowerShell module with the
|
||||
function `Start-PSBuild` to build PowerShell.
|
||||
We maintain a [PowerShell module](../../PowerShellGitHubDev.psm1) with
|
||||
the function `Start-PSBuild` to build PowerShell.
|
||||
|
||||
```powershell
|
||||
Import-Module ./PowerShellGitHubDev.psm1
|
||||
|
@ -67,9 +67,22 @@ Start-PSBuild
|
|||
```
|
||||
|
||||
Congratulations! If everything went right, PowerShell is now built and
|
||||
executable as `./bin/powershell.exe`.
|
||||
executable as `./src/Microsoft.PowerShell.Host/bin/Debug/netstandardapp1.5/win10-x64/powershell`.
|
||||
|
||||
> The cross-platform host has built-in documentation via `--help`.
|
||||
This location is of the form
|
||||
`./[project]/bin/[configuration]/[framework]/[rid]/[binary name]`, and
|
||||
our project is `Microsoft.PowerShell.Host`, configuration is `Debug`
|
||||
by default, framework is `netstandardapp1.5`, runtime identifier is
|
||||
**probably** `win10-x64` (but will depend on your operating system;
|
||||
don't worry, `dotnet --info` will tell you what it was), 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)`.
|
||||
|
||||
You can run our cross-platform Pester tests with `./bin/powershell.exe
|
||||
-c "Invoke-Pester test/powershell"`.
|
||||
The `Microsoft.PowerShell.Host` project is the cross-platform host for
|
||||
PowerShell targetting .NET Core. It is the top level project, so
|
||||
`dotnet build` transitively builds all its dependencies, and emits a
|
||||
`powershell` executable. The cross-platform host has built-in
|
||||
documentation via `--help`.
|
||||
|
||||
You can run our cross-platform Pester tests with `Start-PSPester`.
|
||||
|
|
|
@ -3,7 +3,7 @@ Build PowerShell on Windows for .NET Full
|
|||
|
||||
This guide supplements the
|
||||
[Windows .NET Core instructions](./windows-core.md), as building the
|
||||
.NET 4.5.1 (desktop) version is nearly identical.
|
||||
.NET 4.5.1 (desktop) version is pretty similar.
|
||||
|
||||
Environment
|
||||
===========
|
||||
|
@ -46,21 +46,43 @@ Build using our module
|
|||
======================
|
||||
|
||||
Use `Start-PSBuild -FullCLR` from the `PowerShellGitHubDev.psm1`
|
||||
module. The bits will be published to `binFull`.
|
||||
module.
|
||||
|
||||
Because the `ConsoleHost` project (*not* the `Host` project) is a
|
||||
library and not an application (in the sense that .NET CLI does not
|
||||
emit a native executable using .NET Core's `corehost`), it targets the
|
||||
framework `netstandard1.5`, *not* `netstandardapp1.5`, and the build
|
||||
output will *not* have a runtime identifier in the path.
|
||||
|
||||
Thus the output location of `powershell.exe` will be
|
||||
`./src/Microsoft.PowerShell.ConsoleHost/bin/Debug/netstandardapp1.5/powershell.exe`
|
||||
|
||||
While building is easy, running FullCLR version is not as simple as
|
||||
CoreCLR version.
|
||||
|
||||
If you just run ~~`.\binFull\powershell.exe`~~, you will get a
|
||||
`powershell` process, but all the interesting DLLs (i.e.
|
||||
`System.Management.Automation.dll`) would be loaded from the GAC, not
|
||||
your `binFull` build directory.
|
||||
If you just run ~~`./powershell.exe`~~, you will get a `powershell`
|
||||
process, but all the interesting DLLs (such as
|
||||
`System.Management.Automation.dll`) would be loaded from the Global
|
||||
Assembly Cache (GAC), not your output directory.
|
||||
|
||||
[@lzybkr](https://github.com/lzybkr) wrote a module to deal with it
|
||||
and run side-by-side.
|
||||
|
||||
```powershell
|
||||
Start-DevPSGithub -binDir $pwd\binFull
|
||||
Start-DevPSGithub
|
||||
```
|
||||
|
||||
This command has a reasonable default to run `powershell.exe` from the build output folder.
|
||||
If you are building an unusual configuration (i.e. not `Debug`), you can explicitly specify path to the bin directory
|
||||
|
||||
```powershell
|
||||
Start-DevPSGithub -binDir .\src\Microsoft.PowerShell.ConsoleHost\bin\Debug\net451
|
||||
```
|
||||
|
||||
Or more programmatically:
|
||||
|
||||
```powershell
|
||||
Start-DevPSGithub -binDir (Split-Path -Parent (Get-PSOutput))
|
||||
```
|
||||
|
||||
The default for `powershell.exe` that **we build** is x86. See
|
||||
|
|
|
@ -1,4 +1,5 @@
|
|||
# xUnit Tests
|
||||
xUnit Tests
|
||||
===========
|
||||
|
||||
These tests are completely Linux specific.
|
||||
|
||||
|
@ -11,3 +12,9 @@ for the AppDomain and cannot be reset.`
|
|||
|
||||
Having every class in the same collection is as close to an xUnit
|
||||
global init hook as can be done.
|
||||
|
||||
Running xUnit Tests
|
||||
-------------------
|
||||
|
||||
Go to the top level of the PowerShell repository and run:
|
||||
`Start-PSxUnit` inside a self-hosted copy of PowerShell.
|
||||
|
|
|
@ -154,4 +154,4 @@ Running Pester Tests
|
|||
--------------------
|
||||
|
||||
Go to the top level of the PowerShell repository and run:
|
||||
`./bin/powershell -c "Invoke-Pester test/powershell"`
|
||||
`Start-PSPester` inside a self-hosted copy of PowerShell.
|
||||
|
|
Loading…
Reference in a new issue