diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 2befa783..039459d4 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -58,6 +58,9 @@ * [Testing](development/testing.md) * [Reviewing](development/reviewing.md) * [Releases](development/releases.md) + * [Debugging](development/debugging/README.md) + * [Visual Studio](development/debugging/visualstudio.md) + * [x64dbg](development/debugging/x64dbg.md) ## Other diff --git a/docs/development/debugging/README.md b/docs/development/debugging/README.md new file mode 100644 index 00000000..bf8a47d9 --- /dev/null +++ b/docs/development/debugging/README.md @@ -0,0 +1,10 @@ +# Debugging + +{% hint style="warning" %} +Debugging Northstar is only recommended to experienced developers. +If you need help figuring out an issue feel free to visit the Northstar Discord. +{% endhint %} + +## Contents +* [Visual Studio](visualstudio.md) +* [x64dbg](x64dbg.md) \ No newline at end of file diff --git a/docs/development/debugging/visualstudio.md b/docs/development/debugging/visualstudio.md new file mode 100644 index 00000000..88115444 --- /dev/null +++ b/docs/development/debugging/visualstudio.md @@ -0,0 +1,19 @@ +# Visual Studio + +Northstar is easiest to debug through Visual Studio due to its cmake support. + + +* If you do not already have Visual Studio download it https://visualstudio.microsoft.com/ + * Its recommended that you install the Community version because it is freely availalbe. + * You need to install the `Desktop development with C++` workflow to debug native programs +![](../../images/debugger-visualstudio-installer-workloads-cpp.png) + +* Open Visual Studio +* Select `Open a project or solution` +![](../../images/debugger-visualstudio-launcher.png) + * If you already have a solution open you can open a new project through the menu bar +![](../../images/debugger-visualstudio-menu-solution.png) +* Open `NorthstarLauncher.exe` +* You can now debug Northstar +![](../../images/debugger-visualstudio-debug-menubar.png) + * You can find relevant debug symbols in [NorthstarLauncher releases](https://github.com/R2Northstar/NorthstarLauncher/releases) \ No newline at end of file diff --git a/docs/development/debugging/x64dbg.md b/docs/development/debugging/x64dbg.md new file mode 100644 index 00000000..7506754e --- /dev/null +++ b/docs/development/debugging/x64dbg.md @@ -0,0 +1,42 @@ +# x64dbg + +{% hint style="warning" %} +If you are not experienced with x64dbg it its recommended to use [Visual Studio](visualstudio.md). +{% endhint %} + + +## Windows + +* Download [x64dbg](https://x64dbg.com/) +* Extract the `release` folder somewhere on your PC +* Download the latest relase of [SycllaHide](https://github.com/x64dbg/ScyllaHide/releases/latest) +* Merge the contents of the `x64dbg` folder into the previously extracted `release` folder +* Run `x96dbg.exe` + * You may receive a Windows SmartScreen prompt, x64dbg snapshots are not signed and will always cause these prompts + * When running for the first time it will ask you some questions. After this is complete rerun the executable. +* Select `x64dbg` in the Launcher +![](../../images/debugger-x64dbg-launcher.png) + +* Do make debugging easier it is suggested to change your settings to the following: + * Keeping System Breakpoint enabled is optional but useful +![](../../images/debugger-x64dbg-events.png) + + * Skipping INT3 stepping is recommended to prevent generic breakpoints from stopping the program +![](../../images/debugger-x64dbg-engine.png) + + * Make sure to select the exception before disabling breaking. If you are debugging a C++ Exception you need to ignore common exceptions that occur during runtime +![](../../images/debugger-x64dbg-exceptions.png) + +* Open `NorthstarLauncher.exe` in x64dbg +* You are now free to debug Northstar + +## Linux + +{% hint style="warning" %} +Debugging Northstar under Linux is not trivial due to the direct dependency on Origin, unless you know your way around wine its recommended to debug on Windows. +{% endhint %} + +To simplify the use of x64dbg and automate running Origin a community member has created a script: [ns-linux-dbg](https://github.com/R2NorthstarTools/ns-linux-dbg) + +To run it simply invoke it: `./nsdbg.py` +It supports a variety of options as well as vanilla wine and Proton, use the help flag to see all possible options: `./nsdbg.py --help` diff --git a/docs/images/debugger-visualstudio-debug-menubar.png b/docs/images/debugger-visualstudio-debug-menubar.png new file mode 100644 index 00000000..071e5b30 Binary files /dev/null and b/docs/images/debugger-visualstudio-debug-menubar.png differ diff --git a/docs/images/debugger-visualstudio-installer-workloads-cpp.png b/docs/images/debugger-visualstudio-installer-workloads-cpp.png new file mode 100644 index 00000000..95255b55 Binary files /dev/null and b/docs/images/debugger-visualstudio-installer-workloads-cpp.png differ diff --git a/docs/images/debugger-visualstudio-launcher.png b/docs/images/debugger-visualstudio-launcher.png new file mode 100644 index 00000000..40dcfda8 Binary files /dev/null and b/docs/images/debugger-visualstudio-launcher.png differ diff --git a/docs/images/debugger-visualstudio-menu-solution.png b/docs/images/debugger-visualstudio-menu-solution.png new file mode 100644 index 00000000..d3dfc076 Binary files /dev/null and b/docs/images/debugger-visualstudio-menu-solution.png differ diff --git a/docs/images/debugger-x64dbg-engine.png b/docs/images/debugger-x64dbg-engine.png new file mode 100644 index 00000000..b0013598 Binary files /dev/null and b/docs/images/debugger-x64dbg-engine.png differ diff --git a/docs/images/debugger-x64dbg-events.png b/docs/images/debugger-x64dbg-events.png new file mode 100644 index 00000000..0928c5f9 Binary files /dev/null and b/docs/images/debugger-x64dbg-events.png differ diff --git a/docs/images/debugger-x64dbg-exceptions.png b/docs/images/debugger-x64dbg-exceptions.png new file mode 100644 index 00000000..3dfa8204 Binary files /dev/null and b/docs/images/debugger-x64dbg-exceptions.png differ diff --git a/docs/images/debugger-x64dbg-launcher.png b/docs/images/debugger-x64dbg-launcher.png new file mode 100644 index 00000000..3595ae97 Binary files /dev/null and b/docs/images/debugger-x64dbg-launcher.png differ