diff --git a/README.md b/README.md index 4a63593072..73306d3bb8 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,10 @@ ### Setup Git -Install [Git][], the version control system. If you're new to Git, peruse the documentation and go through some tutorials; I recommend familiarizing yourself with `checkout`, `branch`, `pull`, `push`, `merge`, and after a while, `rebase` and `cherry-pick`. Please commit early and often. +Install [Git][], the version control system. If you're new to Git, peruse the +documentation and go through some tutorials; I recommend familiarizing yourself +with `checkout`, `branch`, `pull`, `push`, `merge`, and after a while, `rebase` +and `cherry-pick`. Please commit early and often. The user name and email must be set to do just about anything with Git. @@ -13,7 +16,8 @@ git config --global user.name "First Last" git config --global user.email "alias@microsoft.com" ``` -I highly recommend these configurations to help deal with whitespace, rebasing, and general use of Git. +I highly recommend these configurations to help deal with whitespace, rebasing, +and general use of Git. > Auto-corrects your command when it's sure (`stats` to `status`) ```sh @@ -58,35 +62,58 @@ To use Git's `https` protocol with VSO, you'll want to setup tokens, and have Gi 10. Click "Create Token" (you may want to copy this token somewhere safe, as VSO will not show it again!) 11. Use this token as the password when cloning (and your username for the username) +### Setup GitHub authentication + +We are working to move all our repositories to GitHub. Unfortunately, this +transition is incomplete, but in progress. The DSC and OMI submodules are +hosted on GitHub, and while the former is a public repository, the latter is +private, thus requiring authentication. + +You should already have your credential helper setup to "store," and so should +use a token with GitHub (instead of your plaintext password). Follow [their +instructions](https://help.github.com/articles/creating-an-access-token-for-command-line-use/). + ### Download source code -Clone our [monad-linux][] source from Visual Studio Online, it's the superproject with a number of submodules. +Clone our [monad-linux][] source from Visual Studio Online, it's the +superproject with a number of submodules. ```sh git clone --recursive https://msostc.visualstudio.com/DefaultCollection/PS/_git/monad-linux ``` -Please read the documentation on [submodules][] if you're not familiar with them. Note that because VSO's "Complete Pull Request" button merges with `--no-ff`, an extra merge commit will always be created. This can be annoying when trying to commit updates to submodules. When a submodule PR is approved, you can "complete" it without a merge commit by merging it to develop manually and pushing the updated head. +Please read the documentation on [submodules][] if you're not familiar with +them. Note that because VSO's "Complete Pull Request" button merges with +`--no-ff`, an extra merge commit will always be created. This can be annoying +when trying to commit updates to submodules. When a submodule PR is approved, +you can "complete" it without a merge commit by merging it to develop manually +and pushing the updated head. -Our convention is to create feature branches `dev/feature` off our integration branch `develop`. We then merge `develop` to `master` every few weeks when it is stable. +Our convention is to create feature branches `dev/feature` off `master`, except +in `src/monad` where we branch off `develop`. [monad-linux]: https://msostc.visualstudio.com/DefaultCollection/PS/_git/monad-linux [submodules]: https://www.git-scm.com/book/en/v2/Git-Tools-Submodules ## Setup build environment -We use the [.NET Command Line Interface][dotnet-cli] (`dotnet-cli`) to build the managed components, and [CMake][] to build the native components. Install `dotnet-cli` by following their documentation (make sure to install the `dotnet-dev` package to get the latest version). Then install the following dependencies (assuming Ubuntu 14.04): +We use the [.NET Command Line Interface][dotnet-cli] (`dotnet-cli`) to build +the managed components, and [CMake][] to build the native components. Install +`dotnet-cli` by following their documentation (make sure to install the +`dotnet-dev` package to get the latest version). Then install the following +dependencies (assuming Ubuntu 14.04): ```sh -sudo apt-get install g++ cmake make libboost-filesystem-dev lldb-3.6 strace +sudo apt-get install g++ cmake make lldb-3.6 strace ``` ### OMI -To develop on the PowerShell Remoting Protocol (PSRP), you'll need to be able to compile OMI, which additionally requires: +To develop on the PowerShell Remoting Protocol (PSRP), you'll need to be able +to compile OMI, which additionally requires: ```sh -sudo apt-get install libpam0g-dev libssl-dev libcurl4-openssl-dev +sudo apt-get install libpam0g-dev libssl-dev libcurl4-openssl-dev libboost-filesystem-dev ``` [dotnet-cli]: https://github.com/dotnet/cli#new-to-net-cli @@ -94,7 +121,8 @@ sudo apt-get install libpam0g-dev libssl-dev libcurl4-openssl-dev ## Building -The command `dotnet restore` must be done at least once from the top directory to obtain all the necessary .NET packages; unfortunately, we also have to temporarily patch `System.Console.dll` until the API is officially updated, so run `./patch.sh`. +The command `dotnet restore` must be done at least once from the top directory +to obtain all the necessary .NET packages. Build with `./build.sh`, which does the following steps. @@ -103,8 +131,6 @@ Build with `./build.sh`, which does the following steps. ### Native - `libpsnative.so`: native functions that `CorePsPlatform.cs` P/Invokes -- `libpshost.a`: native CLR host library -- `powershell`: native CLR host executable (for local shell) - `api-ms-win-core-registry-l1-1-0.dll`: registry stub to prevent missing DLL error on shutdown #### monad-native @@ -133,6 +159,7 @@ cp api-ms-win-core-registry-l1-1-0.dll $BIN ### Managed Builds with `dotnet-cli`. Publishes all dependencies into the `bin` directory. +Emits its own native host as `bin/Microsoft.PowerShell.Linux.Host`. ```sh cd src/Microsoft.PowerShell.Linux.Host @@ -143,28 +170,45 @@ cp *.ps1xml *_profile.ps1 $BIN ### PowerShell Remoting Protocol -PSRP communication is tunneled through OMI using the `monad-omi-provider`. These build steps are not part of the `./build.sh` script. +PSRP communication is tunneled through OMI using the `monad-omi-provider`. +These build steps are not part of the `./build.sh` script. #### OMI ```sh cd src/omi/Unix -./configure --dev --enable-debug +./configure --dev make -j ``` #### Provider -The provider has its own `./build.sh` script which does the second step documented here. +The provider uses CMake to build, link, and register with OMI. ```sh cd src/monad-omi-provider -make clean && make -j && make reg +cmake . +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. + +### DSC + +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 ``` ## Running -- launch local shell with `./run.sh`. +- launch local shell with `./bin/Microsoft.PowerShell.Linux.Host` - launch local shell in LLDB with `./debug.sh` - launch `omiserver` for PSRP (and in LLDB) with `./prsp.sh`, and connect with `Enter-PSSession` from Windows @@ -172,4 +216,7 @@ make clean && make -j && make reg ### xUnit -Sadly, `dotnet-test` is not fully supported on Linux, so our xUnit tests do not currently run. We may be able to work around this, or get the `dotnet-cli` team to fix their xUnit runner. GitHub [issue](https://github.com/dotnet/cli/issues/407). +Sadly, `dotnet-test` is not fully supported on Linux, so our xUnit tests do not +currently run. We may be able to work around this, or get the `dotnet-cli` team +to fix their xUnit runner. GitHub +[issue](https://github.com/dotnet/cli/issues/407).