From 5515c23854a7aaf229993151fe375595d5878d87 Mon Sep 17 00:00:00 2001 From: Andrew Schwartzmeyer Date: Mon, 14 Mar 2016 11:18:44 -0700 Subject: [PATCH 1/9] Move repo permissions note to contributing docs And remove the skip CI note, as it is already noted in CONTRIBUTING.md. --- CONTRIBUTING.md | 13 +++++++++++++ README.md | 9 --------- 2 files changed, 13 insertions(+), 9 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 675342f4f..b39d95d7d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -34,6 +34,19 @@ git config --global user.email "alias@microsoft.com" [hello world]: https://guides.github.com/activities/hello-world/ [guides]: https://guides.github.com/activities/hello-world/ +## Permissions + +If you have difficulty in pushing your changes, there is a high +probability that you actually don't have permissions. + +Be sure that you have write access to corresponding repo (remember +that submodules have their own privilege). + +You do *not* necessarily need to have write permissions to the main +repositories, as you can also just [fork a repo][]. + +[fork a repo]: https://help.github.com/articles/fork-a-repo/ + ## Rebase and Fast-Forward Merge Pull Requests Because GitHub's "Merge Pull Request" button merges with `--no-ff`, an extra diff --git a/README.md b/README.md index 0210ad252..d461e754c 100644 --- a/README.md +++ b/README.md @@ -418,12 +418,3 @@ We publish an archive with FullCLR bits on every CI build with [AppVeyor][]. [appveyor]: https://ci.appveyor.com/project/PowerShell/powershell-linux -#Troubleshooting -### Difficulty with push -If you have difficulty in pushing your changes, there is a high probability that you actually don't have permissions. -Be sure that you have write access to corresponding repo (remember that submodules have their own privilege). - -#Generally Useful Info -### Skipping build in ci -If you want to skip the CI process (for example, updating docs only), just add `[skip ci]` to your commit change comments - From dd25c4c50b61644554b74c34c797dce10b6e4717 Mon Sep 17 00:00:00 2001 From: Andrew Schwartzmeyer Date: Mon, 14 Mar 2016 11:19:22 -0700 Subject: [PATCH 2/9] Remove DSC build notes This should have been removed with the DSC submodule. --- README.md | 14 -------------- 1 file changed, 14 deletions(-) diff --git a/README.md b/README.md index d461e754c..c74470661 100644 --- a/README.md +++ b/README.md @@ -258,20 +258,6 @@ The IP address of the Linux machine can be obtained with: ip -f inet addr show dev eth0 ``` -### Desired State Configuration - -> DSC support is in its infancy. - -DSC also uses OMI, so build it first, then build DSC against it. Unfortunately, -DSC cannot be configured to look for OMI elsewhere, so for now you need to -symlink it to the expected location. - -```sh -ln -s ../omi/Unix/ omi-1.0.8 -./configure --no-rpm --no-dpkg --local -make -j -``` - ## Detailed Build Script Notes > This sections explains the build scripts. From 9d709e8eaac031a302a2613e8e26d3d09c2732b6 Mon Sep 17 00:00:00 2001 From: Andrew Schwartzmeyer Date: Mon, 14 Mar 2016 11:19:56 -0700 Subject: [PATCH 3/9] Update note on PowerShellGitHubDev module --- README.md | 13 ++++--------- 1 file changed, 4 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index c74470661..9ac7f4ad9 100644 --- a/README.md +++ b/README.md @@ -154,7 +154,8 @@ to obtain all the necessary .NET packages.** Build with `./build.sh` on Linux and OS X. -`Start-PSBuild` from module `.\PowerShellGitHubDev.psm1` on Windows and Linux / OS X, if you self-hosting PowerShell. +`Start-PSBuild` from module `./PowerShellGitHubDev.psm1` on Windows +and Linux / OS X, if you self-hosting PowerShell. Specifically: @@ -178,14 +179,8 @@ Start-PSBuild # build CoreCLR version Start-PSBuild -FullCLR # build FullCLR version ``` -**Tip:** use `Start-PSBuild -Verbose` switch to see more information about build process. - -### PowerShellGitHubDev - -Alternatively, the `PowerShellGitHubDev.psm1` module contains a `Start-PSBuild` -function to build Core PowerShell on both Linux and Windows. This module can be -imported into the built-in PowerShell on Windows, and a self-hosting copy of -PowerShell can be installed using our packages under the releases tab. +**Tip:** use `Start-PSBuild -Verbose` switch to see more information +about build process. ## Running From f3f4fa281da04e3b1d0ff98344e345c8ef3e07b0 Mon Sep 17 00:00:00 2001 From: Andrew Schwartzmeyer Date: Mon, 14 Mar 2016 11:20:46 -0700 Subject: [PATCH 4/9] Fix PSRP build notes These got split up. Moved them all to detailed build notes section. --- README.md | 26 +++++++++++++++++--------- 1 file changed, 17 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 9ac7f4ad9..6e8a10013 100644 --- a/README.md +++ b/README.md @@ -113,13 +113,11 @@ wget https://dotnetcli.blob.core.windows.net/dotnet/beta/Installers/Latest/dotne sudo dpkg -i ./dotnet-ubuntu-x64.latest.deb ``` -#### OMI - -To develop on the PowerShell Remoting Protocol (PSRP) for Linux, you'll need to -be able to compile OMI, which additionally requires: +Additionally, PowerShell on Linux builds a native library, so install +the following additional build / debug tools. ```sh -sudo apt-get install libpam0g-dev libssl-dev libcurl4-openssl-dev libboost-filesystem-dev +sudo apt-get install g++ cmake make lldb-3.6 strace ``` ### Windows @@ -208,11 +206,10 @@ PSRP communication is tunneled through OMI using the `omi-provider`. > accomplish this are not even beta-ready and need to be done correctly. They > exist on the `andschwa-osx` branch of the OMI repository. -### Building +### PowerShell Remoting Protocol -**PSRP support is not built by `./build.sh`** - -Build with `./omibuild.sh`. +PSRP support is *not* built automatically. See the detailed notes on +how to enable it. ### Running @@ -296,6 +293,17 @@ The output is a `.so` on Linux and `.dylib` on OS X. It is unnecessary for Windo #### OMI +**PSRP support is not built by `./build.sh`** + +To develop on the PowerShell Remoting Protocol (PSRP) for Linux, you'll need to +be able to compile OMI, which additionally requires: + +```sh +sudo apt-get install libpam0g-dev libssl-dev libcurl4-openssl-dev libboost-filesystem-dev +``` + +Note that the OMI build steps can be done with `./omibuild.sh`. + Build OMI from source in developer mode: ```sh From 724f9c4d4e64b0df22ae914f228c91f2db27d1d9 Mon Sep 17 00:00:00 2001 From: Andrew Schwartzmeyer Date: Mon, 14 Mar 2016 11:21:16 -0700 Subject: [PATCH 5/9] Remove PsModulePath step from Windows instructions This gets automatically set correctly thanks to #646. --- README.md | 1 - 1 file changed, 1 deletion(-) diff --git a/README.md b/README.md index 6e8a10013..37d4eedcb 100644 --- a/README.md +++ b/README.md @@ -194,7 +194,6 @@ The local managed host has built-in documentation via `--help`. ### Windows -- set the module path `$env:PsModulePath = "$pwd\bin\Modules"` - launch `./bin/powershell.exe` - run tests with `./bin/powershell.exe -c "Invoke-Pester test/powershell"` From a2974fa7fe0fd6c2625852d52aee1cbd25647dc1 Mon Sep 17 00:00:00 2001 From: Andrew Schwartzmeyer Date: Mon, 14 Mar 2016 12:03:04 -0700 Subject: [PATCH 6/9] Move Git installation instructions to contributing The readme is getting quite large, so in an effort to shorten it, the Git installation instructions (which have nothing to do with PowerShell, but are helpful for new users), are now in `CONTRIBUTING.md`. Thus, if someone is totally new to Git, they will be far more likely to review our contributing guidelines, and so read our rules and best practices. Cloning the source code was cleaned up so that initializing the submodules is done in a separate step. This simplifies the first step, making it more likely to succeed (and narrowing the possible failures). --- CONTRIBUTING.md | 39 ++++++++++++++++++++++++++++++++ README.md | 59 ++++++++++++++++++------------------------------- 2 files changed, 60 insertions(+), 38 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b39d95d7d..c998bb8f1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -15,6 +15,45 @@ Please add `[ci skip]` to commits that should be ignored by the CI systems All pull requests **must** pass both CI systems before they will be approved. +## Installation + +#### Windows + +Install [Git for Windows][]. + +During the install process, choose these recommended settings: + +* Use Git from the Windows Command Prompt +* Use OpenSSH +* Checkout Windows-style, commit Unix-style line endings +* Use Windows' default console window +* Enable file system caching + +#### Linux + +Install via the package manager: + +```sh +sudo apt-get install git +``` + +#### Authentication + +If you do not have a preferred method of authentication, enable the storage +credential helper, which will cache your credentials in plaintext on your +system, so use a [token][]. + +```sh +git config --global credential.helper store +``` + +Alternatively, on Windows, you can try the +[Git Credential Manager for Windows][manager]. + +[manager]: https://github.com/Microsoft/Git-Credential-Manager-for-Windows +[Git for Windows]: https://git-scm.com/download/win +[token]: https://help.github.com/articles/creating-an-access-token-for-command-line-use/ + ## New to Git? If you're new to Git, learn the following commands: `checkout`, `branch`, diff --git a/README.md b/README.md index 37d4eedcb..06c462b0d 100644 --- a/README.md +++ b/README.md @@ -10,64 +10,47 @@ ### Setup Git - Install [Git][], the version control system. -#### Windows - -Install git from [official web-site](https://git-scm.com/download/win) - -During install process pick this recommended settings: - -* Use git and optional unix tools from windows prompt -* Checkout windows style, checking unix style -* Use windows default console windows - -Install [windows git credential helper](https://github.com/Microsoft/Git-Credential-Manager-for-Windows) - -#### Linux - -```sh -sudo apt-get install git -``` - -If you do not have a preferred method of authentication, enable the storage -credential helper, which will cache your credentials in plaintext on your -system, so use a [token][]. - -```sh -git config --global credential.helper store -``` - -See the [Contributing Guidelines](CONTRIBUTING.md) for more Git information. +See the [Contributing Guidelines](CONTRIBUTING.md) for more Git +information, such as our installation instructions, contributing +rules, and Git best practices. [Git]: https://git-scm.com/documentation -[token]: https://help.github.com/articles/creating-an-access-token-for-command-line-use/ ### Download source code -Clone this repository recursively, as it's the superproject with a number of -submodules. +Clone this repository. It is a "superproject" and has a number of +other repositories embedded within it as submodules. *Please* see the +contributing guidelines and learn about submodules. ```sh -git clone --recursive https://github.com/PowerShell/PowerShell.git +git clone https://github.com/PowerShell/PowerShell.git +cd PowerShell +``` + +#### Linux + +Linux will need every submodule, so update them recursively: + +```sh +git submodule update --init --recursive ``` The `src/omi` submodule requires your GitHub user to have joined the Microsoft organization. If it fails to check out, Git will bail and not check out further submodules either. Please follow the instructions on the [Open Source Hub][]. -On Windows, many fewer submodules are needed, so don't use `clone --recursive`. +[Open Source Hub]: https://opensourcehub.microsoft.com/articles/how-to-join-microsoft-github-org-self-service -Instead run: +#### Windows -``` -git clone https://github.com/PowerShell/PowerShell.git +On Windows, many fewer submodules are needed, so specify them: + +```sh git submodule update --init --recursive -- src/monad src/windows-build src/Microsoft.PowerShell.Linux.Host/Modules/Pester ``` -[Open Source Hub]: https://opensourcehub.microsoft.com/articles/how-to-join-microsoft-github-org-self-service - ## Setup build environment We use the [.NET Command Line Interface][dotnet] (`dotnet`) to build From 342a7530c7f1913ee499ad0f4d2090f3dafa4737 Mon Sep 17 00:00:00 2001 From: Andrew Schwartzmeyer Date: Mon, 14 Mar 2016 12:07:19 -0700 Subject: [PATCH 7/9] Update FullCLR detailed build instructions This was left out of date as of #655. It is also needed to be a subsection of the detailed build notes section. Some typos and superfluous information were fixed. --- README.md | 24 ++++++++++-------------- 1 file changed, 10 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index 06c462b0d..6a6967cd7 100644 --- a/README.md +++ b/README.md @@ -72,7 +72,6 @@ The version of .NET CLI is very important, you want a recent 1.0.0 beta Tested on Ubuntu 14.04. - This installs the .NET CLI package feed. The benefit to this is that installing `dotnet` using `apt-get` will also install all of its dependencies automatically. @@ -107,8 +106,6 @@ sudo apt-get install g++ cmake make lldb-3.6 strace Tested on Windows 10 and Windows Server 2012 R2. -An MSI installer also exists, but this script avoids touching your system. - ```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.001718 -channel beta @@ -136,13 +133,14 @@ to obtain all the necessary .NET packages.** Build with `./build.sh` on Linux and OS X. `Start-PSBuild` from module `./PowerShellGitHubDev.psm1` on Windows -and Linux / OS X, if you self-hosting PowerShell. +and Linux / OS X, if you are self-hosting PowerShell. Specifically: ### Linux In Bash: + ```sh cd PowerShell dotnet restore @@ -152,6 +150,7 @@ dotnet restore ### Windows In PowerShell: + ```powershell cd PowerShell dotnet restore @@ -188,8 +187,6 @@ PSRP communication is tunneled through OMI using the `omi-provider`. > accomplish this are not even beta-ready and need to be done correctly. They > exist on the `andschwa-osx` branch of the OMI repository. -### PowerShell Remoting Protocol - PSRP support is *not* built automatically. See the detailed notes on how to enable it. @@ -307,11 +304,11 @@ make -j The provider also maintains its own native host library to initialize the CLR, but there are plans to refactor .NET's packaged host as a shared library. -# FullCLR PowerShell +### FullCLR PowerShell On Windows, we also build Full PowerShell for .NET 4.5.1 -## Setup environment +#### Setup environment * You need Visual Studio to compile the native host `powershell.exe`. @@ -338,19 +335,19 @@ choco install cmake.portable [chocolately]: https://chocolatey.org/packages/cmake.portable [manually]: https://cmake.org/download/ -## Building +#### Building ```powershell -.\build.FullCLR.ps1 +Start-PSBuild -FullCLR ``` **Troubleshooting:** the build logic is relatively simple and contains following steps: -- building managed DLLs: `dotnet publish --runtime dnx451` +- building managed DLLs: `dotnet publish --runtime net451` - generating Visual Studio project: `cmake -G "$cmakeGenerator"` - building `powershell.exe` from generated solution: `msbuild powershell.sln` -All this steps can be run separately from `.\build.FullCLR.ps1`, don't hesitate -to experiment. +All this steps can be run separately from `Start-PSBuild`, don't +hesitate to experiment. ## Running @@ -388,4 +385,3 @@ We publish an archive with FullCLR bits on every CI build with [AppVeyor][]. * `Start-DevPSGithub -binDir $bin` [appveyor]: https://ci.appveyor.com/project/PowerShell/powershell-linux - From 2beb92ce43d882689f2b64c69b02cde07405d80c Mon Sep 17 00:00:00 2001 From: Andrew Schwartzmeyer Date: Mon, 14 Mar 2016 12:08:19 -0700 Subject: [PATCH 8/9] Add note on writing good commit messages --- CONTRIBUTING.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c998bb8f1..94dfb0364 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -15,6 +15,15 @@ Please add `[ci skip]` to commits that should be ignored by the CI systems All pull requests **must** pass both CI systems before they will be approved. +Write *good* commit messages. Follow Tim Pope's [guidelines][]: + +* The first line *must* be a short, capitalized summary +* The second line *must* be blank +* The rest should be a wrapped, detailed explanation of the what and why +* The tone should be imperative + +[guidelines]: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html + ## Installation #### Windows From 5d81f12b4953f7b3457291660938140ec4520c9c Mon Sep 17 00:00:00 2001 From: Zach Folwick Date: Fri, 11 Mar 2016 13:01:58 -0800 Subject: [PATCH 9/9] Add Experimental .NET Core Debugging in VS Code [skip ci] --- README.md | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/README.md b/README.md index 6a6967cd7..6e4765992 100644 --- a/README.md +++ b/README.md @@ -179,6 +179,38 @@ The local managed host has built-in documentation via `--help`. - launch `./bin/powershell.exe` - run tests with `./bin/powershell.exe -c "Invoke-Pester test/powershell"` +## Debugging + +To enable debugging on Linux, follow the installation instructions for +[Experimental .NET Core Debugging in VS Code][VS Code]. You will also +want to review their [detailed instructions][vscclrdebugger]. + +VS Code will place a `.vscode` directory in the PowerShell folder. +This contains the `launch.json` file, which you will customize using +the instructions below. You will also be prompted to create a +`tasks.json` file. + +Currently, debugging supports attaching to a currently running +powershell process. Assuming you've created a `launch.json` file +correctly, within the "configuration" section, use the below settings: + +```json +"configurations": [ + { + "name": "powershell", + "type": "coreclr", + "request": "attach", + "processName": "powershell" + } +] +``` + +VS Code will now attach to a running `powershell` process. Start +powershell, then (in VS Code) press `F5` to begin the debugger. + +[VS Code]: https://blogs.msdn.microsoft.com/visualstudioalm/2016/03/10/experimental-net-core-debugging-in-vs-code/ +[vscclrdebugger]: http://aka.ms/vscclrdebugger + ## PowerShell Remoting Protocol PSRP communication is tunneled through OMI using the `omi-provider`.