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

Move Linux instructions to docs/building/linux.md

Browse Source
This commit is contained in:
Andrew Schwartzmeyer
2016-03-30 21:33:57 -07:00
parent 19e870aad2
commit 1937ad5784
2 changed files with 166 additions and 114 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
-114
View File
@@ -38,20 +38,6 @@ 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][].
[Open Source Hub]: https://opensourcehub.microsoft.com/articles/how-to-join-microsoft-github-org-self-service
#### Windows
On Windows, many fewer submodules are needed, so specify them:
@@ -62,56 +48,6 @@ git submodule update --init --recursive -- src/windows-build src/Microsoft.Power
## Setup build environment
We use the [.NET Command Line Interface][dotnet-cli] (`dotnet`) to
build the managed components, and [CMake][] to build the native
components (on non-Windows platforms). Install `dotnet` by following
their [documentation][cli-docs].
The version of .NET CLI is very important, you want a recent 1.0.0 beta
(**not** 1.0.1). The following instructions will install precisely
1.0.0.001888, though any 1.0.0 version *should* work.
> Previous installations of DNX, `dnvm`, or older installations of .NET CLI
> can cause odd failures when running. Please check your version.
[dotnet-cli]: https://github.com/dotnet/cli#new-to-net-cli
[cli-docs]: https://dotnet.github.io/getting-started/
[CMake]: https://cmake.org/cmake/help/v2.8.12/cmake.html
### Linux
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.
```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=1.0.0.001675-1
```
The drawback of using the feed is that it gets out of date. The pinned
version is the most recent package published to the feed, but newer
packages are available. 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
```
Additionally, PowerShell on Linux builds a native library, so install
the following additional build / debug tools.
```sh
sudo apt-get install g++ cmake make lldb-3.6 strace
```
### Windows
Tested on Windows 10 and Windows Server 2012 R2.
@@ -141,23 +77,11 @@ test on OS X, but some developers use PowerShell on 10.10 and 10.11.
**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` on Linux and OS X.
`Start-PSBuild` from module `./PowerShellGitHubDev.psm1` on Windows
and Linux / OS X, if you are self-hosting PowerShell.
Specifically:
### Linux
In Bash:
```sh
cd PowerShell
dotnet restore
./build.sh
```
### Windows
In PowerShell:
@@ -180,11 +104,6 @@ otherwise open a new issue on GitHub.
The local managed host has built-in documentation via `--help`.
### Linux / OS X
- launch local shell with `./bin/powershell`
- run tests with `./pester.sh`
### Windows
- launch `./bin/powershell.exe`
@@ -278,39 +197,6 @@ ip -f inet addr show dev eth0
The variable `$BIN` is the output directory, `bin`.
### Managed
Builds with `dotnet`. Publishes all dependencies into the `bin` directory.
Emits its own native host as `bin/powershell`. Uses a `Linux` configuration to
add a preprocessor definition. The `CORECLR` definition is added only when
targeting the `netstandard1.5` framework. The `LINUX` definition is added only
when `--configuration Linux` is used.
```sh
cd src/Microsoft.PowerShell.Linux.Host
dotnet publish --configuration Linux
```
### Native
The `libpsl-native.so` library consists of native functions that
`CorePsPlatform.cs` P/Invokes.
#### libpsl-native
Driven by CMake, with its own unit tests using Google Test.
```sh
cd src/libpsl-native
cmake -DCMAKE_BUILD_TYPE=Debug .
make -j
ctest -V
# Deploy development copy of libpsl-native
cp native/libpsl-native.* $BIN
```
The output is a `.so` on Linux and `.dylib` on OS X. It is unnecessary for Windows.
### PSRP
#### OMI
docs/building/linux.md
+166
View File
@@ -0,0 +1,166 @@
Build PowerShell on Linux
=========================
This guide will walk you through building PowerShell on Linux. We'll
start by showing how to set up your environment from scratch.
Environment
===========
These instructions are written assuming the Ubuntu 14.04 LTS, since
that's the distro the team uses.
Toolchain Setup
---------------
We use the [.NET Command Line Interface][dotnet-cli] (`dotnet`) to
build the managed components, and [CMake][] to build the native
components. Install the following packages for the toolchain:
- `dotnet`
- `cmake`
- `make`
- `g++`
- `libunwind8`
- `libicu52`
And for debgging:
- `strace`
- `lldb-3.6`
In order to get `dotnet`, we need to add an additional package source:
```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
```
[dotnet-cli]: https://github.com/dotnet/cli#new-to-net-cli
[CMake]: https://cmake.org/cmake/help/v2.8.12/cmake.html
.NET CLI
--------
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
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-docs]: https://dotnet.github.io/getting-started/
Git Setup
---------
Please clone the superproject (this repo) and initialize a subset of
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
```
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
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
```sh
GITHUB_TOKEN=<replace with your token> ./download.sh
sudo dpkg -i ./powershell.deb
powershell
```
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!
```powershell
Import-Module ./PowerShellGitHubDev.psm1
Start-PSBuild
```
Congratulations! If everything went right, PowerShell is now built and
executable as `./bin/powershell`.
> Note that the `./build.sh` script is deprecated and may be removed
You can run our cross-platform Pester tests with `./bin/powershell -c
"Invoke-Pester test/powershell"`.
Build manually
==============
The following goes into detail about what `Start-PSBuild` does.
Build the native library
------------------------
The `libpsl-native.so` library consists of native functions that
`CorePsPlatform.cs` P/Invokes.
```sh
pushd src/libpsl-native
cmake -DCMAKE_BUILD_TYPE=Debug .
make -j
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.
Build the managed projects
--------------------------
The `Linux.Host`, while poorly named, 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
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
```
PowerShell and all necessary components should now be in the `bin` folder.
[issue #673]: https://github.com/PowerShell/PowerShell/issues/673
[issue #685]: https://github.com/PowerShell/PowerShell/issues/685