From 343b42c8a40298596dc83fdc8147b2a992ce7fb4 Mon Sep 17 00:00:00 2001 From: Jan Date: Fri, 20 Oct 2023 01:52:57 +0200 Subject: Add basic debugging documentation (#243) Adds basic debugging documentation for Visual Studio and x64dbg --- docs/development/debugging/README.md | 10 +++++++ docs/development/debugging/visualstudio.md | 19 ++++++++++++++ docs/development/debugging/x64dbg.md | 42 ++++++++++++++++++++++++++++++ 3 files changed, 71 insertions(+) create mode 100644 docs/development/debugging/README.md create mode 100644 docs/development/debugging/visualstudio.md create mode 100644 docs/development/debugging/x64dbg.md (limited to 'docs/development') 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 +![](../../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 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 +![](../../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` -- cgit v1.2.3