Merge pull request #768 from PowerShell/andschwa/docs

Update documentation

docs/building/linux.md

@@ -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`
+**To ease this process, just run `./bootstrap.sh` and enter password
-- `lldb-3.6`
+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
+- Adds the LLVM package feed
-sudo sh -c 'echo "deb [arch=amd64] http://apt-mo.trafficmanager.net/repos/dotnet/ trusty main" > /etc/apt/sources.list.d/dotnetdev.list'
+- Installs our dependencies combined with the dependencies of the .NET
-sudo apt-key adv --keyserver apt-mo.trafficmanager.net --recv-keys 417A0893
+  CLI toolchain via `apt-get`
-sudo apt-get update
+- Installs the .NET CLI host, shared framework, and SDK by downloading
-```
+  the three `.deb` packages to `/tmp` and using `dpkg -i`
-
-Then install the packages you need:
-
-```sh
-sudo apt-get install dotnet cmake make g++ libunwind8 libicu52 strace lldb-3.6
-```
 
 [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.
+CLI can cause odd failures when running. Please check your version and
-
+uninstall prior any prior versions.
-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-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
+We maintain a [PowerShell module](../../PowerShellGitHubDev.psm1) with
-function `Start-PSBuild` to build PowerShell. Since this is PowerShell
+the function `Start-PSBuild` to build PowerShell. Since this is
-code, it requires self-hosting. Fortunately, this is as easy as
+PowerShell code, it requires self-hosting. Fortunately, this is as
-downloading and installing the package. Unfortunately, while the
+easy as downloading and installing the package. Unfortunately, while
-repository is still private, the package cannot be downloaded as
+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
+Congratulations! If everything went right, PowerShell is now built.
-executable as `./bin/powershell`.
+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
+You can run our cross-platform Pester tests with `Start-PSPester`, and
-"Invoke-Pester test/powershell"`.
+our xUnit tests with `Start-PSxUnit`.
 
 Build manually
 ==============
@@ -138,29 +128,36 @@ make test
 popd
 ```
 
-This library will be emitted in the
+This library will be emitted in the `src/Microsoft.PowerShell.Host`
-`src/Microsoft.PowerShell.Linux.Host` project, where `dotnet` consumes
+project, where `dotnet` consumes it as "content" and thus
-it as "content" and thus automatically deploys it.
+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
+`dotnet build` transitively builds all its dependencies, and emits a
-`powershell` executable and all necessary libraries (both native and
+`powershell` executable. The `--configuration Linux` flag is
-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
 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

docs/building/osx.md

@@ -18,8 +18,8 @@ dependencies.
 brew install openssl cmake wget
 ```
 
-Instead of using .NET CLI's Ubuntu package feed, you will want to use
+Instead of using Linux `./bootstrap.sh` to install .NET CLI's Ubuntu
-the official PKG installer.
+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.

docs/building/windows-core.md

@@ -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
+We maintain a [PowerShell module](../../PowerShellGitHubDev.psm1) with
-function `Start-PSBuild` to build PowerShell.
+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
+The `Microsoft.PowerShell.Host` project is the cross-platform host for
--c "Invoke-Pester test/powershell"`.
+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`.

docs/building/windows-full.md

@@ -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
+If you just run ~~`./powershell.exe`~~, you will get a `powershell`
-`powershell` process, but all the interesting DLLs (i.e.
+process, but all the interesting DLLs (such as
-`System.Management.Automation.dll`) would be loaded from the GAC, not
+`System.Management.Automation.dll`) would be loaded from the Global
-your `binFull` build directory.
+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

test/csharp/README.md

@@ -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.

test/powershell/README.md

@@ -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.