Debugging PMDO

From PMDOWiki
Revision as of 19:35, 11 November 2024 by IDK (talk | contribs) (attach debugger instructions)

See also: Contributing Code, Building PMDO

Windows Setup

  1. Recursively clone the PMDO repository using git clone --recurse-submodules -j8 https://github.com/audinowho/PMDODump.git.
  2. Download the .NET 8.0 SDK. You want to download the x64 version for windows. Confirm that it is installed using the command dotnet --list-runtimes.
  3. Download Visual Studio 2022 or later.
  4. Open PMDOData.sln using Visual Studio 2022.
  5. Set your configuration to Debug, Any CPU. Build the entire solution
  6. Set PMDC as the startup project and hit Debug.

Linux Setup

Currently, only x64 architecture is supported for Linux.

  1. Recursively clone the PMDO repository using git clone --recurse-submodules -j8 https://github.com/audinowho/PMDODump.git.
  2. Download the .NET 8.0 SDK. You want to download the x64 version for Linux. Confirm that it is installed using the command dotnet --list-runtimes.
  3. Download and install Visual Studio Code for Linux. We recommend using the .deb installer.
  4. Install the C# Dev Kit. This can be found in the Extensions tab.
  5. Open the PMDOData folder with VSCode. You can do this by starting with a blank VSCode window, open a folder, select the PMDODump folder.
  6. With the C# Dev Kit installed, you now have the option to open the PMDOData.sln: check the Solution Explorer tab, then right click PMDOData.sln and choose "Open Solution".
  7. With the C# Dev Kit installed, you also have the option to open the Command Palette Ctrl+Shift+P. In the command palette, type/choose Debug: Select and Start Debugging.
    1. Choose "C#" from the dropdown. If you've properly opened the PMDOData.sln solution, you should have several Launch Configurations available. Choose "C#: PMDC".
  8. Debug will start.
    1. If the console complains about not being able to find the correct file from path, you may need to change the relative paths specified for the -asset argument in the PMDC/PMDC/Properties/launchSettings.json file.
  9. Once this debug configuration is chosen, you can start debugging quickly by going to the Debug tab and selecting the green button next to "Run and Debug".

Mac Setup

Apple machines made a transition from x64 to ARM64 with Apple Silicon in 2020-2024, with any Macs running on M1 Chips or later using ARM64. PMDO runs and deploys on x64 only; this normally means that PMDO entirely would not be able to run on M1+ Macs, but Rosetta 2 translates applications meant for x64 to run on ARM64. This works normally when attempting to play published versions of PMDO, but makes things tricky for debugging.

Visual Studio Code

If your machine predates the ARM64 transition (IE, predates M1 Macs), it uses x64 architecture, and there should be no issues debugging. The setup for Visual Studio Code should work exactly as it did for Linux. Use the instructions there if so. Otherwise, you have two options:

  1. Use x64 Installation of VS Code on your Arm64 Mac
  2. Use Arm64 Installation of VS code and Attach Debugger on a separately built PMDO

x64 Install on Arm64 Mac

  1. Recursively clone the PMDO repository using git clone --recurse-submodules -j8 https://github.com/audinowho/PMDODump.git.
  2. Download the .NET 8.0 SDK. You want to download the x64 (Not Arm64!) version for MacOS. Confirm that it is installed using the command dotnet --list-runtimes.
    1. Check if your dotnet installation is pointing to the x64 version. Do this with type dotnet and see if it points to /usr/local/share/dotnet/x64/dotnet. If not, you will need to specify the path of dotnet to point to the x64 installation of dotnet: check /etc/paths.d/dotnet and make sure it points to /usr/local/share/dotnet/x64.
  3. Download and install Visual Studio Code for MacOS. Specifically choose the zip for Intel Chip.
    1. If you have an existing VSCode installation under Arm64, it must be uninstalled. You should be able to do this by sending the VSCode app to the trash.
  4. Install the C# Dev Kit. This can be found in the Extensions tab.
    1. If you had a previous installation of VSCode under Arm64, it's likely that the extension was also installed as an arm64 version. You will need to uninstall it and reinstall to get the x64 version. Do this for both the C# Dev Kit as well as the C# extension it depends on.
  5. Open the PMDOData folder with VSCode. You can do this by starting with a blank VSCode window, open a folder, select the PMDODump folder.
  6. With the C# Dev Kit installed, you now have the option to open the PMDOData.sln: check the Solution Explorer tab, then right click PMDOData.sln and choose "Open Solution".
  7. With the C# Dev Kit installed, you also have the option to open the Command Palette Ctrl+Shift+P. In the command palette, type/choose Debug: Select and Start Debugging.
    1. Choose "C#" from the dropdown. If you've properly opened the PMDOData.sln solution, you should have several Launch Configurations available. Choose "C#: PMDC".
  8. Debug will start.
    1. If the console complains about not being able to find the correct file from path, you may need to change the relative paths specified for the -asset argument in the PMDC/PMDC/Properties/launchSettings.json file.
    2. If the console complains about missing FNA libs such as SDL2, copy all of the .dylib files in PMDC/PMDC/runtimes/osx-x64/native to PMDC/PMDC/bin/Debug/net8.0, the build output location.
  9. Once this debug configuration is chosen, you can start debugging quickly by going to the Debug tab and selecting the green button next to "Run and Debug".

Arm64 Install with Attach Debugger

There is currently no known way to change the build settings in VSCode. If you install the Arm64 version of VS Code, you cannot build the x64 version. Instead, you will need to build PMDO in the command line, run PMDO, and then attach the debugger from VS Code.

  1. Recursively clone the PMDO repository using git clone --recurse-submodules -j8 https://github.com/audinowho/PMDODump.git.
  2. Download the .NET 8.0 SDK. You want to download the Arm64 version for MacOS. Confirm that it is installed using the command dotnet --list-runtimes.
    1. Check if your dotnet installation is pointing to the arm64 version. Do this with type dotnet and see if it points to /usr/local/share/dotnet/dotnet. If not, you will need to specify the path of dotnet to point to the arm64 installation of dotnet: check /etc/paths.d/dotnet and make sure it points to /usr/local/share/dotnet.
  3. Download and install Visual Studio Code for MacOS. Specifically choose the zip for Apple Silicon.
    1. If you have an existing VSCode installation under x64, it must be uninstalled. You should be able to do this by sending the VSCode app to the trash.
  4. Install the C# Dev Kit. This can be found in the Extensions tab.
    1. If you had a previous installation of VSCode under x64, it's likely that the extension was also installed as an x64 version. You will need to uninstall it and reinstall to get the arm64 version. Do this for both the C# Dev Kit as well as the C# extension it depends on.
  5. Open the PMDOData folder with VSCode. You can do this by starting with a blank VSCode window, open a folder, select the PMDODump folder.
  6. With the C# Dev Kit installed, you now have the option to open the PMDOData.sln: check the Solution Explorer tab, then right click PMDOData.sln and choose "Open Solution".
  7. In the command line, cd to PMDC/PMDC and run dotnet build -c Debug -r osx-x64. This should output an x64 debug build of PMDO to PMDC/PMDC/bin/Debug/net8.0/osx-x64.
    1. Copy all of the .dylib files in PMDC/PMDC/runtimes/osx-x64/native to the output directory PMDC/PMDC/bin/Debug/net8.0/osx-x64. This will prevent the program from complaining about missing SDL2 dependencies.
  8. cd to PMDC/PMDC/bin/Debug/net8.0/osx-x64 and run ./PMDC -dev -asset ../../../../../DumpAsset/. The program should run successfully.
  9. With the C# Dev Kit installed, you also have the option to open the Command Palette Ctrl+Shift+P. In the Command Palette Ctrl+Shift+P and running the Debug: Attach to a .NET 5+ or .NET Core process. In the command palette, type/choose Debug: Select and Start Debugging. Find the process of your currently running PMDO instance and choose it in the dropdown. Once selected, the UI will enter debug and you can set breakpoints as normal.
  10. Each time you want to debug a change, you must rebuild the project using dotnet build -c Debug -r osx-x64, run the resulting program, and then attach the debugger.

Further research: It may be possible to start and attach in a single step using launch configurations:

https://stackoverflow.com/questions/60440765/how-can-i-attach-to-a-specific-process-in-visual-studio-code

Visual Studio Code Issues

Various issues arise when attempting to use the ARM64 version of dotnet with the ARM64 version VS Code.

Whenever the user clicks "debug", the IDE will build PMDO using the Any CPU setting. If the x64 dotnet is installed, this defaults to an x64 build. But if the Arm64 dotnet is installed, the Arm64 version is built. (Note: check if this is just the responsibility of dotnet installation itself, as opposed to both it and the IDE)

THE ARM64 VERSION OF PMDO DOES NOT WORK. IT IS MISSING ARM64 DEPENDENCIES FOR LUA, SKIASHARP.

We must avoid building the Arm64 version and only build for x64.

It's unknown if there is a way to configure the build step such that it uses the x64 dotnet to build PMDO under x64. Can this be specified in launchSettings.json? In tasks.json?

Resources:


Jetbrains Rider

Jetbrains Rider requires a paid subscription.

Jetbrains Rider on x64

This option works for Macs running on x64. However, issues have been seen when running on Arm64.

  1. Download .NET 8.0. You want to download the x64 version. Confirm that it is installed using the command dotnet --list-runtimes.
  2. Recursively clone the PMDO repository using git clone --recurse-submodules -j8 https://github.com/audinowho/PMDODump.git.
  3. Copy all of the .dylib files in PMDC/PMDC/runtimes folders to PMDC/PMDC. Here’s what your file structure should look like:
  4. Debug should run out of the box. Set the configuration to PMDC and click "Debug", and you should be all ready to go!

Jetbrains Rider on arm64

  1. Recursively clone the PMDO repository using git clone --recurse-submodules -j8 https://github.com/audinowho/PMDODump.git.
  2. Download the .NET 8.0 SDK. You want to download the Arm64 version for MacOS. Confirm that it is installed using the command dotnet --list-runtimes.
  3. In the command line, cd to PMDC/PMDC and run dotnet build -c Debug -r osx-x64. This should output an x64 debug build of PMDO to PMDC/PMDC/bin/Debug/net8.0/osx-x64.
    1. Copy all of the .dylib files in PMDC/PMDC/runtimes/osx-x64/native to the output directory PMDC/PMDC/bin/Debug/net8.0/osx-x64. This will prevent the program from complaining about missing SDL2 dependencies.
  4. cd to PMDC/PMDC/bin/Debug/net8.0/osx-x64 and run ./PMDC -dev -asset ../../../../../DumpAsset/. The program should run successfully.
  5. With Rider installed, attach a debugger to the currently running PMDO process.
  6. Each time you want to debug a change, you must rebuild the project using dotnet build -c Debug -r osx-x64, run the resulting program, and then attach the debugger.

Gitignore considerations

In your ~/.gitignore_global file, add the following files for git to ignore: 

# Debug logs (npm, yarn)
*.log

# Editor artifacts
.*.sw[a-z]
*~
.#*
.vscode
.idea

# OS files
Thumbs.db
.DS_Store

You may want to include more. Modified from here.

Retrieved from "https://wiki.pmdo.pmdcollab.org/index.php?title=Debugging_PMDO&oldid=2588"