diff --git a/docs/building/linux.md b/docs/building/linux.md index 2e51afb8e0..492b2ffdf1 100644 --- a/docs/building/linux.md +++ b/docs/building/linux.md @@ -1,33 +1,30 @@ Build PowerShell on Linux ========================= -This guide will walk you through building PowerShell on Linux. We'll -start by showing how to set up your environment from scratch. +This guide will walk you through building PowerShell on Linux. +We'll start by showing how to set up your environment from scratch. Environment =========== -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. +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. Git Setup --------- -Using Git requires it to be setup correctly; refer to the -[Working With the PowerShell Repository](../git/powershell-repository-101.md), -[README](../../README.md) and -[Contributing Guidelines](../../.github/CONTRIBUTING.md). +Using Git requires it to be set up correctly; +refer to the [Working with the PowerShell Repository](../git/powershell-repository-101.md), +[README](../../README.md), and [Contributing Guidelines](../../.github/CONTRIBUTING.md). -**This guide assumes that you have recursively cloned the PowerShell -repository and `cd`ed into it.** +**This guide assumes that you have recursively cloned the PowerShell repository and `cd`ed into it.** Toolchain Setup --------------- -We use the [.NET Command Line Interface][dotnet-cli] (`dotnet`) to -build the managed components, and [CMake][] to build the native -components. Install the following packages for the toolchain: +We use the [.NET Command-Line Interface][dotnet-cli] (`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 the `Start-PSBootstrap` module as described below. - `cmake` @@ -35,22 +32,19 @@ components. Install the following packages for the toolchain: - `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. +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. +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. +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 +> You can alternatively download by using a browser, upload it to your > box via some other method, and manually install it. In Bash: @@ -62,9 +56,8 @@ GITHUB_TOKEN= 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! +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: @@ -76,13 +69,11 @@ 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` +- 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 want to use `dotnet` outside of `Start-PSBuild`, add `~/.dotnet` to your `PATH` environment variable. [dotnet-cli]: https://github.com/dotnet/cli#new-to-net-cli [CMake]: https://cmake.org/cmake/help/v2.8.12/cmake.html @@ -90,25 +81,21 @@ If you want to use `dotnet` outside of `Start-PSBuild`, add `~/.dotnet` to your .NET CLI -------- -If you have any problems installing `dotnet`, please see their -[documentation][cli-docs]. +If you have any problems installing `dotnet`, please see their [documentation][cli-docs]. -The version of .NET CLI is very important, you need a recent build of -1.0.0 (**not** 1.0.1). +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. +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. [cli-docs]: https://dotnet.github.io/getting-started/ Build using our module ====================== -We maintain a [PowerShell module](../../build.psm1) 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. +We maintain a [PowerShell module](../../build.psm1) 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 @@ -123,9 +110,8 @@ 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`. +You should now be running the `powershell` that 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`. Build manually ============== @@ -135,8 +121,7 @@ The following goes into detail about what `Start-PSBuild` does. Build the native library ------------------------ -The `libpsl-native.so` library consists of native functions that -`CorePsPlatform.cs` P/Invokes. +The `libpsl-native.so` library consists of native functions that `CorePsPlatform.cs` P/Invokes. ```sh pushd src/libpsl-native @@ -146,16 +131,15 @@ make test popd ``` -This library will be emitted in the `src/powershell` project, where `dotnet` -consumes it as "content" and thus automatically deploys it. +This library will be emitted in the `src/powershell` project, +where `dotnet` consumes it as "content" and thus automatically deploys it. Build the managed projects -------------------------- -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][]). +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][]). ```sh dotnet restore @@ -163,16 +147,14 @@ 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)`. +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. +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, for example, `/usr/local/share/powershell` or packaged. [issue #673]: https://github.com/PowerShell/PowerShell/issues/673