Updated doc to build arm/arm64 versions of psrp.windows and PowerShell.Core.Instrumentation.dll libraries (#5668)

This commit is contained in:
Steve Lee 2017-12-11 13:48:24 -08:00 committed by Dongbo Wang
parent 34ddf425c2
commit 64647c25f4
2 changed files with 47 additions and 72 deletions

View File

@ -21,6 +21,7 @@ AppImage
AppVeyor
argumentlist
arm32
arm64
artifact
artifacts
ASP.NET
@ -484,14 +485,18 @@ nanoserver-insider-powershell
#region docs/building/internals.md Overrides
- docs/building/internals.md
_arm
_arm64
Catalog
flavor
libpsl
MSBuild
nuget.exe
plugin
powershell-unix
psrp.windows
src
v141
#endregion
#region docs/building/macos.md Overrides

View File

@ -113,24 +113,41 @@ and then reuse the produced binaries for many builds subsequently.
The NuGet package for `pwrshplugin.dll` is `psrp.windows`,
and the NuGet package for `libpsl-native` is `libpsl`.
### psrp.windows
### Windows packages: PSRP.Windows and PowerShell.Core.Instrumentation
To build `pwrshplugin.dll` and `PowerShell.Core.Instrumentation.dll`, you need to install Visual Studio 2017 and run `Start-PSBootstrap -BuildWindowsNative` to install the prerequisites.
Ensure the following individual components are selected:
- [ ] VC++ 2017 v141 toolset (x86, x64)
- [ ] Visual C++ compilers and libraries for ARM
- [ ] Visual C++ compilers and libraries for ARM64
- [ ] Visual C++ tools for CMake
- [ ] Visual C++ ATL Support
- [ ] Windows 10 SDK (10.0.16299.0) for Desktop C++ (ARM and ARM64)
- [ ] Windows 10 SDK (10.0.16299.0) for Desktop C++ (x86 and x64)
Ensure [CMake](https://cmake.org/download/) 3.10.0 or newer is installed which supports VS2017 and ARM64 generator.
To build `pwrshplugin.dll`, you need to install Visual Studio 2015 and run `Start-PSBootstrap -BuildWindowsNative` to install the prerequisites.
Then run `Start-BuildNativeWindowsBinaries` to build the binary.
For example, the following builds the release flavor of the binary targeting x64 architecture.
For example, the following builds the release flavor of the binary targeting arm64 architecture.
```powershell
Start-BuildNativeWindowsBinaries -Configuration Release -Arch x64
Start-BuildNativeWindowsBinaries -Configuration Release -Arch x64_arm64
```
After that, the binary `pwrshplugin.dll` and its PDB file will be placed under 'src/powershell-win-core'.
Be sure to build and test for all supported architectures: x86, x64, x64_arm, and x64_arm64.
The `x64_arm` and `x64_arm64` architectures mean that the host system needs to be x64 to cross-compile to ARM.
When building for multiple architectures, be sure to use the `-clean` switch as cmake will cache the previous run and the wrong compiler will be used to generate the subsequent architectures.
After that, the binary `pwrshplugin.dll`, its PDB file, and `powershell.core.instrumentation.dll` will be placed under 'src\powershell-win-core'.
To create a new NuGet package for `pwrshplugin.dll`, first you need to get the `psrp.windows.nuspec` from an existing `psrp.windows` package.
You can find it at `~/.nuget/packages/psrp.windows` on your windows machine if you have recently built PowerShell on it.
Or you can download the existing package from [powershell-core feed](https://powershell.myget.org/feed/powershell-core/package/nuget/psrp.windows).
Once you get `psrp.windows.nuspec`, copy it to an empty folder.
Once you get `psrp.windows.nuspec`, copy it to an empty folder and update the `<version>` element.
Then you need to build `pwrshplugin.dll` targeting both `win-x64` and `win-x86` on Windows 10.
After building successfully, copy the produced files to the same folder,
and create the same layout of files as in the existing package.
The layout of files should look like this:
@ -142,13 +159,29 @@ The layout of files should look like this:
| pwrshplugin.dll
| pwrshplugin.pdb
|
\---win-x86
+---win-x86
| \---native
| pwrshplugin.dll
| pwrshplugin.pdb
+---win-arm
| \---native
| pwrshplugin.dll
| pwrshplugin.pdb
\---win-arm64
\---native
pwrshplugin.dll
pwrshplugin.pdb
```
Lastly, run `nuget pack .` from within the folder. Note that you may need the latest `nuget.exe`.
Have the DLLs signed with `authenticode dual` certificate and run `nuget pack` from the parent of the `runtimes` folder where `psrp.windows.nuspec` resides.
Be sure to use the latest recommended version of [nuget.exe](https://www.nuget.org/downloads).
Publish latest nupkg to https://powershell.myget.org/feed/powershell-core/package/nuget/psrp.windows.
`PowerShell.Core.Instrumentation.dll` NuGet package is created the same way, but in a separate directory following the same layout above.
To create a new NuGet package for `PowerShell.Core.Instrumentation.dll`, you will need the `PowerShell.Core.Instrumentation.nuspec` found in the repo under `src\PowerShell.Core.Instrumentation`.
Publish latest nupkg to https://powershell.myget.org/feed/powershell-core/package/nuget/PowerShell.Core.Instrumentation.
### libpsl
@ -197,66 +230,3 @@ The layout of files should look like this:
```
Lastly, run `nuget pack .` from within the folder. Note that you may need the latest `nuget.exe`.
### PowerShell.Core.Instrumentation
To successfully decode PowerShell Core ETW events, the manifest and resource binary need to be registered on the system.
To create a new NuGet package for `PowerShell.Core.Instrumentation.dll`, you will need the `PowerShell.Core.Instrumentation.nuspec` found in the repo under `src\PowerShell.Core.Instrumentation`.
Update the version information for the package.
```none
<version>6.0.0-RC</version>
```
Next, create the directory structure needed for the contents of the nuget package structure. The final directory and file layout is listed below.
```powershell
if (Test-Path -Path c:\mypackage)
{
Remove-Item -Recurse -Force -Path c:\mypackage
}
$null = New-Item -Path c:\mypackage\runtimes\win-x64\native -ItemType Directory
$null = New-Item -Path c:\mypackage\runtimes\win-x86\native -ItemType Directory
```
You will need to build `PowerShell.Core.Instrumentation.dll` targeting both `win-x64` and `win-x86` on Windows 10.
The output files will be placed under src\powershell-win-core.
Build the `win-x64` platform and copy the `PowerShell.Core.Instrumentation.dll` to the win-x86 portion of the tree.
```powershell
## Build targeting win-x64
Start-BuildNativeWindowsBinaries -Configuration Release -Arch x64
Copy-Item -Path .\src\powershell-win-core\PowerShell.Core.Instrumentation.dll -Destination c:\mypackage\runtimes\win-x64\native
```
Next, build the `win-x86` platform and copy `PowerShell.Core.Instrumentation.dll` to the win-x86 portion of the tree.
```powershell
## Build targeting win-x86
Start-BuildNativeWindowsBinaries -Configuration Release -Arch x86
Copy-Item -Path .\src\powershell-win-core\PowerShell.Core.Instrumentation.dll -Destination c:\mypackage\runtimes\win-x86\native
```
The layout of files looks like this:
```none
└── runtimes
├── win-x64
│ └── native
│ └── PowerShell.Core.Instrumentation.dll
├── win-x86
│ └── native
│ └── PowerShell.Core.Instrumentation.dll
```
NOTE: Since these are native binaries used on Windows, they need to be `authenticode dual signed` before creating the nuget package.
Lastly, run the following command from the root of the repo to create the nuget package. The nuget package is placed at `.\src\powershell-win-core`. Note that you may need the latest `nuget.exe`.
```powershell
nuget pack .\src\PowerShell.Core.Instrumentation\PowerShell.Core.Instrumentation.nuspec -BasePath c:\mypackage -OutputDirectory .\src\powershell-win-core
```