2016-01-18 00:25:48 +01:00
|
|
|
# PowerShell on Linux / OS X / Windows
|
2015-07-02 00:06:29 +02:00
|
|
|
|
2016-01-22 20:36:23 +01:00
|
|
|
| |Ubuntu 14.04 |Windows |
|
|
|
|
|---------|:------:|:------:|
|
2016-01-22 22:31:57 +01:00
|
|
|
|master|[![Build Status](https://travis-ci.com/PowerShell/PowerShell-Linux.svg?token=31YifM4jfyVpBmEGitCm&branch=master)](https://travis-ci.com/PowerShell/PowerShell-Linux)|[![Build status](https://ci.appveyor.com/api/projects/status/wb0a0apbn4aiccp1/branch/master?svg=true)](https://ci.appveyor.com/project/PowerShell/powershell-linux/branch/master)|
|
2016-01-22 20:36:23 +01:00
|
|
|
|
2016-01-25 19:38:35 +01:00
|
|
|
## [Waffle.io scrum board](https://waffle.io/PowerShell/PowerShell-Linux)
|
2016-01-22 20:36:23 +01:00
|
|
|
|
2015-10-08 22:44:37 +02:00
|
|
|
## Obtain the source code
|
2015-07-02 00:06:29 +02:00
|
|
|
|
2015-10-08 22:44:37 +02:00
|
|
|
### Setup Git
|
2015-07-02 00:06:29 +02:00
|
|
|
|
2016-01-21 21:25:48 +01:00
|
|
|
Install [Git][], the version control system.
|
|
|
|
|
|
|
|
```sh
|
|
|
|
sudo apt-get install git
|
|
|
|
```
|
|
|
|
|
2016-01-15 20:56:08 +01:00
|
|
|
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
|
|
|
|
```
|
|
|
|
|
2016-01-20 20:33:57 +01:00
|
|
|
See the [Contributing Guidelines](CONTRIBUTING.md) for more Git information.
|
2015-07-02 00:06:29 +02:00
|
|
|
|
2015-10-08 22:25:59 +02:00
|
|
|
[Git]: https://git-scm.com/documentation
|
2016-01-15 20:56:08 +01:00
|
|
|
[token]: https://help.github.com/articles/creating-an-access-token-for-command-line-use/
|
2016-01-12 21:20:54 +01:00
|
|
|
|
2015-10-08 22:44:37 +02:00
|
|
|
### Download source code
|
2015-07-02 00:06:29 +02:00
|
|
|
|
2016-01-20 20:33:57 +01:00
|
|
|
Clone this repository recursively, as it's the superproject with a number of
|
2016-01-15 20:56:08 +01:00
|
|
|
submodules.
|
2015-07-02 00:06:29 +02:00
|
|
|
|
|
|
|
```sh
|
2016-01-15 20:56:08 +01:00
|
|
|
git clone --recursive https://github.com/PowerShell/PowerShell-Linux.git
|
2015-07-02 00:06:29 +02:00
|
|
|
```
|
|
|
|
|
2016-01-20 20:33:57 +01:00
|
|
|
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.
|
|
|
|
|
|
|
|
On Windows, many fewer submodules are needed, so don't use `clone --recursive`.
|
|
|
|
|
2016-01-20 01:10:19 +01:00
|
|
|
Instead run:
|
|
|
|
|
|
|
|
```
|
|
|
|
git clone https://github.com/PowerShell/PowerShell-Linux.git
|
|
|
|
git submodule update --init --recursive -- src/monad src/windows-build test/Pester
|
|
|
|
```
|
|
|
|
|
2015-10-08 22:44:37 +02:00
|
|
|
## Setup build environment
|
2015-07-06 20:56:29 +02:00
|
|
|
|
2016-01-12 21:20:54 +01:00
|
|
|
We use the [.NET Command Line Interface][dotnet-cli] (`dotnet-cli`) to build
|
2016-01-18 00:25:48 +01:00
|
|
|
the managed components, and [CMake][] to build the native components (on
|
2016-01-21 21:25:48 +01:00
|
|
|
non-Windows platforms). Install `dotnet-cli` by following their [documentation][]
|
2016-01-20 20:33:57 +01:00
|
|
|
(make sure to install the `dotnet-nightly` package on Linux to get the latest
|
2016-01-21 21:25:48 +01:00
|
|
|
version).
|
2016-01-18 00:25:48 +01:00
|
|
|
|
|
|
|
> Note that OS X dependency installation instructions are not yet documented,
|
|
|
|
> and Windows only needs `dotnet-cli`.
|
|
|
|
|
2016-01-20 20:33:57 +01:00
|
|
|
> Previous installations of DNX or `dnvm` can cause `dotnet-cli` to fail.
|
|
|
|
|
2016-01-21 21:25:48 +01:00
|
|
|
[dotnet-cli]: https://github.com/dotnet/cli#new-to-net-cli
|
|
|
|
[documentation]: https://dotnet.github.io/getting-started/
|
|
|
|
[CMake]: https://cmake.org/cmake/help/v2.8.12/cmake.html
|
|
|
|
|
2016-01-18 00:25:48 +01:00
|
|
|
### Linux
|
|
|
|
|
2016-01-21 21:25:48 +01:00
|
|
|
Tested on Ubuntu 14.04.
|
2016-01-18 00:25:48 +01:00
|
|
|
|
2016-01-21 21:25:48 +01:00
|
|
|
```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
|
|
|
|
sudo apt-get install dotnet-nightly
|
|
|
|
```
|
|
|
|
|
|
|
|
Then install the following additional build / debug tools:
|
|
|
|
|
2015-12-09 22:38:03 +01:00
|
|
|
```sh
|
2016-01-12 21:20:54 +01:00
|
|
|
sudo apt-get install g++ cmake make lldb-3.6 strace
|
2015-12-09 22:38:03 +01:00
|
|
|
```
|
2015-07-06 20:56:29 +02:00
|
|
|
|
2016-01-18 00:25:48 +01:00
|
|
|
#### OMI
|
2015-07-06 20:56:29 +02:00
|
|
|
|
2016-01-20 20:33:57 +01:00
|
|
|
To develop on the PowerShell Remoting Protocol (PSRP) for Linux, you'll need to
|
|
|
|
be able to compile OMI, which additionally requires:
|
2015-07-06 20:56:29 +02:00
|
|
|
|
2015-12-09 22:38:03 +01:00
|
|
|
```sh
|
2016-01-12 21:20:54 +01:00
|
|
|
sudo apt-get install libpam0g-dev libssl-dev libcurl4-openssl-dev libboost-filesystem-dev
|
2015-12-09 22:38:03 +01:00
|
|
|
```
|
2015-07-06 20:56:29 +02:00
|
|
|
|
2015-10-08 22:44:37 +02:00
|
|
|
## Building
|
2015-07-02 00:06:29 +02:00
|
|
|
|
2016-01-20 20:33:57 +01:00
|
|
|
**The command `dotnet restore` must be done at least once from the top directory
|
|
|
|
to obtain all the necessary .NET packages.**
|
2015-12-17 20:29:12 +01:00
|
|
|
|
2016-01-18 00:25:48 +01:00
|
|
|
Build with `./build.sh` on Linux and OS X, and `./build.ps1` on Windows.
|
2015-12-17 20:29:12 +01:00
|
|
|
|
2016-01-20 21:29:06 +01:00
|
|
|
Specifically:
|
|
|
|
|
|
|
|
### Linux
|
|
|
|
|
2016-01-21 21:25:48 +01:00
|
|
|
In Bash:
|
2016-01-20 21:29:06 +01:00
|
|
|
```sh
|
|
|
|
cd PowerShell-Linux
|
|
|
|
dotnet restore
|
|
|
|
./build.sh
|
|
|
|
```
|
|
|
|
|
|
|
|
### Windows
|
|
|
|
|
2016-01-21 21:25:48 +01:00
|
|
|
In PowerShell:
|
2016-01-20 21:29:06 +01:00
|
|
|
```powershell
|
|
|
|
cd PowerShell-Linux
|
|
|
|
dotnet restore
|
|
|
|
./build.ps1
|
|
|
|
```
|
|
|
|
|
2016-01-18 00:25:48 +01:00
|
|
|
## Running
|
|
|
|
|
2016-01-20 21:33:42 +01:00
|
|
|
If you encounter any problems, see the [known issues](KNOWNISSUES.md),
|
|
|
|
otherwise open a new issue on GitHub.
|
|
|
|
|
2016-01-18 00:25:48 +01:00
|
|
|
### Linux / OS X
|
|
|
|
|
|
|
|
- launch local shell with `./bin/powershell`
|
|
|
|
- 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
|
|
|
|
|
|
|
|
### Windows
|
|
|
|
|
2016-01-20 20:33:57 +01:00
|
|
|
Launch `./bin/powershell.exe`. The console output isn't the prettiest, but the
|
|
|
|
vast majority of Pester tests pass. Run them in the console with `Invoke-Pester
|
|
|
|
test/powershell`.
|
2016-01-18 00:25:48 +01:00
|
|
|
|
2016-01-20 21:29:06 +01:00
|
|
|
## PowerShell Remoting Protocol
|
|
|
|
|
|
|
|
PSRP communication is tunneled through OMI using the `omi-provider`.
|
|
|
|
|
|
|
|
**These build steps are not part of the `./build.sh` script.**
|
|
|
|
|
|
|
|
> PSRP has been observed working on OS X, but the changes made to OMI to
|
|
|
|
> accomplish this are not even beta-ready and need to be done correctly. They
|
|
|
|
> exist on the `andschwa-osx` branch of the OMI repository.
|
|
|
|
|
|
|
|
### Build OMI
|
|
|
|
|
|
|
|
```sh
|
|
|
|
cd src/omi/Unix
|
|
|
|
./configure --dev
|
|
|
|
make -j
|
|
|
|
cd ../../..
|
|
|
|
```
|
|
|
|
|
|
|
|
### Build Provider
|
|
|
|
|
|
|
|
The provider uses CMake to build, link, and register with OMI.
|
|
|
|
|
|
|
|
```sh
|
|
|
|
cd src/omi-provider
|
|
|
|
cmake .
|
|
|
|
make -j
|
|
|
|
cd ../..
|
|
|
|
```
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
### Running
|
|
|
|
|
|
|
|
Some initial setup on Windows is required. Open an administrative command
|
|
|
|
prompt and execute the following:
|
|
|
|
|
|
|
|
```cmd
|
|
|
|
winrm set winrm/config/Client @{AllowUnencrypted="true"}
|
|
|
|
winrm set winrm/config/Client @{TrustedHosts="*"}
|
|
|
|
```
|
|
|
|
|
|
|
|
Then on Linux, launch `omiserver` in the debugger (after building with the
|
|
|
|
instructions above):
|
|
|
|
|
|
|
|
```sh
|
|
|
|
./psrp.sh
|
|
|
|
run
|
|
|
|
```
|
|
|
|
|
|
|
|
> The `run` command is executed inside of LLDB (the debugger) to start the
|
|
|
|
`omiserver` process.
|
|
|
|
|
|
|
|
Now in a PowerShell prompt on Windows (opened after setting the WinRM client
|
|
|
|
configurations):
|
|
|
|
|
|
|
|
```powershell
|
|
|
|
Enter-PSSession -ComputerName <IP address of Linux machine> -Credential $cred -Authentication basic
|
|
|
|
```
|
2016-01-18 00:25:48 +01:00
|
|
|
|
2016-01-20 21:29:06 +01:00
|
|
|
> The `$cred` variable can be empty; a credentials prompt will appear, enter
|
|
|
|
> any fake credentials you wish as authentication is not yet implemented.
|
2016-01-18 00:25:48 +01:00
|
|
|
|
2016-01-21 21:25:48 +01:00
|
|
|
The IP address of the Linux machine can be obtained with:
|
|
|
|
|
|
|
|
```sh
|
|
|
|
ip -f inet addr show dev eth0
|
|
|
|
```
|
|
|
|
|
2016-01-20 21:29:06 +01:00
|
|
|
### Desired State Configuration
|
2016-01-20 20:33:57 +01:00
|
|
|
|
2016-01-20 21:29:06 +01:00
|
|
|
> DSC support is in its infancy.
|
2016-01-20 20:33:57 +01:00
|
|
|
|
2016-01-20 21:29:06 +01:00
|
|
|
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.
|
2016-01-20 20:33:57 +01:00
|
|
|
|
2016-01-20 21:29:06 +01:00
|
|
|
```sh
|
|
|
|
ln -s ../omi/Unix/ omi-1.0.8
|
|
|
|
./configure --no-rpm --no-dpkg --local
|
|
|
|
make -j
|
|
|
|
```
|
2016-01-20 20:33:57 +01:00
|
|
|
|
2016-01-20 21:29:06 +01:00
|
|
|
## Detailed Build Script Notes
|
2016-01-18 00:25:48 +01:00
|
|
|
|
2016-01-20 21:29:06 +01:00
|
|
|
> This explains `./build.sh`.
|
2016-01-18 00:25:48 +01:00
|
|
|
|
|
|
|
The variable `$BIN` is the output directory, `bin`.
|
2015-12-16 22:57:13 +01:00
|
|
|
|
2016-01-15 20:56:08 +01:00
|
|
|
### Managed
|
|
|
|
|
|
|
|
Builds with `dotnet-cli`. Publishes all dependencies into the `bin` directory.
|
2016-01-16 01:56:55 +01:00
|
|
|
Emits its own native host as `bin/powershell`.
|
2016-01-15 20:56:08 +01:00
|
|
|
|
|
|
|
```sh
|
|
|
|
cd src/Microsoft.PowerShell.Linux.Host
|
|
|
|
dotnet publish --framework dnxcore50 --output $BIN
|
|
|
|
# Copy files that dotnet-publish doesn't currently deploy
|
|
|
|
cp *.ps1xml *_profile.ps1 $BIN
|
|
|
|
```
|
|
|
|
|
2015-12-09 22:38:03 +01:00
|
|
|
### Native
|
|
|
|
|
2016-01-20 20:33:57 +01:00
|
|
|
- `libpsl-native.so`: native functions that `CorePsPlatform.cs` P/Invokes
|
2015-12-16 22:57:13 +01:00
|
|
|
- `api-ms-win-core-registry-l1-1-0.dll`: registry stub to prevent missing DLL error on shutdown
|
|
|
|
|
2016-01-15 20:56:08 +01:00
|
|
|
#### libpsl-native
|
2015-12-16 22:57:13 +01:00
|
|
|
|
|
|
|
Driven by CMake, with its own unit tests using Google Test.
|
|
|
|
|
2015-12-09 22:38:03 +01:00
|
|
|
```sh
|
2016-01-15 20:56:08 +01:00
|
|
|
cd src/libpsl-native
|
2015-12-09 22:38:03 +01:00
|
|
|
cmake -DCMAKE_BUILD_TYPE=Debug .
|
2015-12-16 22:57:13 +01:00
|
|
|
make -j
|
2015-12-09 22:38:03 +01:00
|
|
|
ctest -V
|
2016-01-15 20:56:08 +01:00
|
|
|
# Deploy development copy of libpsl-native
|
|
|
|
cp native/libpsl-native.* $BIN
|
2015-12-16 22:57:13 +01:00
|
|
|
```
|
|
|
|
|
2016-01-20 20:33:57 +01:00
|
|
|
The output is a `.so` on Linux and `.dylib` on OS X. It is unnecessary for Windows.
|
|
|
|
|
2015-12-16 22:57:13 +01:00
|
|
|
#### registry-stub
|
|
|
|
|
|
|
|
Provides `RegCloseKey()` to satisfy the disposal of `SafeHandle` objects on shutdown.
|
|
|
|
|
|
|
|
```sh
|
|
|
|
cd src/registry-stub
|
|
|
|
make
|
|
|
|
cp api-ms-win-core-registry-l1-1-0.dll $BIN
|
2015-12-09 22:38:03 +01:00
|
|
|
```
|