MegaBites-AI/Windows-powershell

1# Visual Studio Code2 3The [Visual Studio Code][vscode] editor supports cross-platform debugging.4This is made possible by the [OmniSharp][] extension for VS Code.5 6Please review their [detailed instructions][core-debug]. In7addition to being able to build PowerShell, you need:8 9- C# Extension for VS Code installed10- .NET Core debugger installed (semi-automatic)11- `powershell` executable in your path (self-host if not on Windows)12 13The .NET CLI tools *must* be on your path for Visual Studio Code.14`Start-PSBootstrap` installs the tools to `~/.dotnet` (non-Windows) or `"$env:LocalAppData\Microsoft\dotnet"` (Windows),15but does not add this to your `PATH`.16You can do this in Bash with `export PATH=$PATH:$HOME/.dotnet` or in PowerShell with `$env:path = $env:path+";$env:LocalAppData\Microsoft\dotnet"`.17 18Once the extension is installed, you have to open a C# file to force VS Code to19install the actual .NET Core debugger (the editor will tell you to do this if20you attempt to debug and haven't already opened a C# file).21 22The committed `.vscode` folder in the root of this repository contains23the `launch.json` and `tasks.json` files which provide Core PowerShell24debugging configurations and a build task.25 26The "build" task will run `Start-PSBuild`, emitting the executable to27`PowerShell/debug/powershell` so that the debugger always knows where to find it28(regardless of platform). If you edit this, please do not commit it, as the29default is meant to "just work" for anyone.30 31The ".NET Core Launch" configuration will build and start a `powershell`32process, with `justMyCode` disabled, and `stopAtEntry` enabled, thus PowerShell33will stop right at `Main`, and you need to click the green arrow to continue.34 35With either Gnome Terminal or XTerm installed, the launch configuration will36launch an external console with PowerShell running interactively. If neither of37these installed, the editor will tell you to do so.38 39Alternatively, the ".NET Core Attach" configuration will start listening for a40process named `powershell`, and will attach to it. If you need more fine-grained41control, replace `processName` with `processId` and provide a PID. (Please be42careful not to commit such a change.)43 44[core-debug]: https://learn.microsoft.com/dotnet/core/tutorials/with-visual-studio-code#debug45[vscode]: https://code.visualstudio.com/46[OmniSharp]: https://github.com/OmniSharp/omnisharp-vscode47 48## PowerShell49 50The `Trace-Command` cmdlet can be used to enable tracing of certain PowerShell51subsystems. Use `Get-TraceSource` for a list of tracers:52 53* CmdletProviderClasses54* CommandDiscovery55* CommandSearch56* ConsoleHost57* ConsoleHostRunspaceInit58* ConsoleHostUserInterface59* ConsoleLineOutput60* DisplayDataQuery61* ETS62* FileSystemProvider63* FormatFileLoading64* FormatViewBinding65* LocationGlobber66* MemberResolution67* Modules68* MshSnapinLoadUnload69* ParameterBinderBase70* ParameterBinderController71* ParameterBinding72* PathResolution73* PSDriveInfo74* PSSnapInLoadUnload75* RunspaceInit76* SessionState77* TypeConversion78* TypeMatch79 80Then trace it like this:81 82```powershell83Trace-Command -Expression { Get-ChildItem . } -Name PathResolution -PSHost84```85 86The `-PSHost` specifies the sink, in this case the console host,87so we can see the tracing messages.88The `-Name` chooses the list of tracers to enable.89 90## LLDB with SOS plug-in91 92The `./tools/debug.sh` script can be used to launch PowerShell inside of LLDB93with the SOS plug-in provided by .NET Core. This provides an additional way to94debug PowerShell on Linux, but VS Code is recommended for a better user95experience (and its single-stepping capabilities).96 97The script is self-documented and contains a link to the98[CoreCLR debugging help][clr-debug] .99 100[clr-debug]: https://github.com/dotnet/coreclr/blob/master/Documentation/building/debugging-instructions.md#debugging-coreclr-on-linux101 102## `corehost`103 104The native executable produced by .NET CLI will produce trace output105if launched with `COREHOST_TRACE=1 ./powershell`.106 107## CoreCLR PAL108 109The native code in the CLR has debug channels to selectively output110information to the console. These are controlled by the111`PAL_DBG_CHANNELS`, e.g., `export PAL_DBG_CHANNELS="+all.all"`, as112detailed in the `dbgmsg.h` [header][].113 114Enabling `+all.all` is *incredibly* noisy;115you will need to narrow your scope.116 117[header]: https://github.com/dotnet/coreclr/blob/release/1.0.0/src/pal/src/include/pal/dbgmsg.h118 119## Debugging .NET Core120 121The .NET Core libraries downloaded from NuGet and shipped with PowerShell are release versions.122This means that `PAL_DBG_CHANNELS` will not work with them,123and instead you must build and deploy .NET Core built in debug mode.124These instructions are not meant to be comprehensive,125but should prove useful.126 127They are currently written for Linux and are meant only as a shortcut means to debug.128 129## Build and deploy CoreCLR130 131* Clone CoreCLR: `git clone -b release/1.0.0 https://github.com/dotnet/coreclr.git`132* Follow [building instructions](https://github.com/dotnet/coreclr/blob/release/1.0.0/Documentation/building/linux-instructions.md)133* Wait for `./build.sh` to finish134* Overwrite PowerShell libraries: `cp bin/Product/Linux.x64.Debug/*{so,dll} /path/to/powershell/`135 136## Build and deploy CoreFX137 138* Clone CoreFX: `git clone -b release/1.0.0 https://github.com/dotnet/corefx.git`139* Follow [building instructions](https://github.com/dotnet/corefx/blob/release/1.0.0/Documentation/building/unix-instructions.md)140* Wait for `./build.sh skiptests` to finish141* Overwrite PowerShell libraries:142 143> This must be done in a particular order to get the most specific build,144> and each phase must be allowed to overwrite both the previous phase145> and any files previously found (hence the use of `-exec cp`).146> The glob cannot go more than one directory deep,147> as subdirectories can have alternative and unwanted implementations148> of libraries with the same name.149 150```sh151dest=/path/to/powershell/152find bin/AnyOS.AnyCPU.Debug/*/*.dll -exec cp -p {} $dest \;153find bin/Unix.AnyCPU.Debug/*/*.dll -exec cp -p {} $dest \;154find bin/Linux.AnyCPU.Debug/*/*.dll -exec cp -p {} $dest \;155find bin/Linux.x64.Debug/ -name *.so -exec cp -p {} $dest \;156```157