admin/PowerShell-PowerShell
1
0
Fork 0
mirror of https://github.com/PowerShell/PowerShell synced 2026-06-08 12:12:50 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update readme

Browse Source
This commit is contained in:
Andrew Schwartzmeyer
2016-01-12 12:25:25 -08:00
parent ec49e37de6
commit 864d9bec01
1 changed files with 65 additions and 18 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+65 -18
View File
@@ -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).