diff --git a/docs/building/linux.md b/docs/building/linux.md index 2027a20fb..f459c8207 100644 --- a/docs/building/linux.md +++ b/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` -- `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= ./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 diff --git a/docs/building/osx.md b/docs/building/osx.md index f23a0694c..e5f2523b0 100644 --- a/docs/building/osx.md +++ b/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 -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. diff --git a/docs/building/windows-core.md b/docs/building/windows-core.md index b50571c3f..479d3cf37 100644 --- a/docs/building/windows-core.md +++ b/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 -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`. diff --git a/docs/building/windows-full.md b/docs/building/windows-full.md index 3e31160a8..806dc1594 100644 --- a/docs/building/windows-full.md +++ b/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 -`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 diff --git a/test/csharp/README.md b/test/csharp/README.md index b39ceda2a..18979b055 100644 --- a/test/csharp/README.md +++ b/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. diff --git a/test/powershell/README.md b/test/powershell/README.md index 9a24f8014..98f0f0771 100644 --- a/test/powershell/README.md +++ b/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.