Update Linux building 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