diff options
| -rw-r--r-- | docs/SUMMARY.md | 3 | ||||
| -rw-r--r-- | docs/development/debugging/README.md | 10 | ||||
| -rw-r--r-- | docs/development/debugging/visualstudio.md | 19 | ||||
| -rw-r--r-- | docs/development/debugging/x64dbg.md | 42 | ||||
| -rw-r--r-- | docs/images/debugger-visualstudio-debug-menubar.png | bin | 0 -> 10096 bytes | |||
| -rw-r--r-- | docs/images/debugger-visualstudio-installer-workloads-cpp.png | bin | 0 -> 6514 bytes | |||
| -rw-r--r-- | docs/images/debugger-visualstudio-launcher.png | bin | 0 -> 62400 bytes | |||
| -rw-r--r-- | docs/images/debugger-visualstudio-menu-solution.png | bin | 0 -> 21757 bytes | |||
| -rw-r--r-- | docs/images/debugger-x64dbg-engine.png | bin | 0 -> 29615 bytes | |||
| -rw-r--r-- | docs/images/debugger-x64dbg-events.png | bin | 0 -> 19673 bytes | |||
| -rw-r--r-- | docs/images/debugger-x64dbg-exceptions.png | bin | 0 -> 23182 bytes | |||
| -rw-r--r-- | docs/images/debugger-x64dbg-launcher.png | bin | 0 -> 6414 bytes |
12 files changed, 74 insertions, 0 deletions
diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 2befa78..039459d 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 0000000..bf8a47d --- /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 0000000..8811544 --- /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 + + +* Open Visual Studio +* Select `Open a project or solution` + + * If you already have a solution open you can open a new project through the menu bar + +* Open `NorthstarLauncher.exe` +* You can now debug Northstar + + * 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 0000000..7506754 --- /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 + + +* Do make debugging easier it is suggested to change your settings to the following: + * Keeping System Breakpoint enabled is optional but useful + + + * Skipping INT3 stepping is recommended to prevent generic breakpoints from stopping the program + + + * 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 + + +* 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 Binary files differnew file mode 100644 index 0000000..071e5b3 --- /dev/null +++ b/docs/images/debugger-visualstudio-debug-menubar.png diff --git a/docs/images/debugger-visualstudio-installer-workloads-cpp.png b/docs/images/debugger-visualstudio-installer-workloads-cpp.png Binary files differnew file mode 100644 index 0000000..95255b5 --- /dev/null +++ b/docs/images/debugger-visualstudio-installer-workloads-cpp.png diff --git a/docs/images/debugger-visualstudio-launcher.png b/docs/images/debugger-visualstudio-launcher.png Binary files differnew file mode 100644 index 0000000..40dcfda --- /dev/null +++ b/docs/images/debugger-visualstudio-launcher.png diff --git a/docs/images/debugger-visualstudio-menu-solution.png b/docs/images/debugger-visualstudio-menu-solution.png Binary files differnew file mode 100644 index 0000000..d3dfc07 --- /dev/null +++ b/docs/images/debugger-visualstudio-menu-solution.png diff --git a/docs/images/debugger-x64dbg-engine.png b/docs/images/debugger-x64dbg-engine.png Binary files differnew file mode 100644 index 0000000..b001359 --- /dev/null +++ b/docs/images/debugger-x64dbg-engine.png diff --git a/docs/images/debugger-x64dbg-events.png b/docs/images/debugger-x64dbg-events.png Binary files differnew file mode 100644 index 0000000..0928c5f --- /dev/null +++ b/docs/images/debugger-x64dbg-events.png diff --git a/docs/images/debugger-x64dbg-exceptions.png b/docs/images/debugger-x64dbg-exceptions.png Binary files differnew file mode 100644 index 0000000..3dfa820 --- /dev/null +++ b/docs/images/debugger-x64dbg-exceptions.png diff --git a/docs/images/debugger-x64dbg-launcher.png b/docs/images/debugger-x64dbg-launcher.png Binary files differnew file mode 100644 index 0000000..3595ae9 --- /dev/null +++ b/docs/images/debugger-x64dbg-launcher.png |
