Debug on MS Windows

Debugging compiled code on MS Windows ® can be challenging if you do not have the time or inclination to Set up a Development Environment. This page is to give instructions for Freeciv21 developers to offer a custom compiled package to a player who wants to help troubleshoot a bug, but needs a better capability than the released package.

The problem here is two-fold:

  1. The released package does not have debugging symbols compiled into the code, since it is not a good practice to do so.

  2. Qt’s console access has been removed from the Window’s binaries, which makes getting stdout or stderr from a command prompt impossible.

There is good news! We have infrastructure in place that makes it easy for us to provide a special debug enabled Windows package to a player. Here is how to do it:

  1. On a development platform of choice, create a new branch following our How to Submit a Pull Request process called something like test/windows-debug-console.

  2. Open cmake/FreecivDependencies.cmake and comment the lines for the if() block below this comment: # Removes the console window that pops up with the GUI app.

  3. Open .github/workflows/build.yaml and change the MSYS2 build step to use Debug instead of Release for the DCMAKE_BUILD_TYPE=... cmake configure flag.

  4. (Optional) Change the value for the package name to update to the action’s attachment section from Windows-exe to WindowsDebug-exe

  5. Push the change to our GitHub repo and let the CI/CD Actions run. When finished there will be a Debug enabled installer package available.

Tip

You can see a sample by reviewing https://github.com/longturn/freeciv21/pull/2564.

Steps for Debugging on Windows

The player will need a GitHub account. They are free of charge, so there should not be any issue there. Give the link to the build action’s main page after it has completed from the pushed PR above.

These are the steps for the player on their Windows computer:

  1. Download WindowsDebug-exe and uncompress the ZIP file.

  2. Run the installer package exe and install to a throw away location such as C:\Temp.

  3. Right click Start Menu and select Windows PowerShell (Admin).

  4. At the PS C:\WINDOWS\System32> prompt, type cmd and press Enter.

  5. At the C:\WINDOWS\System32> prompt, type setx /M QT_ASSUME_STDERR_HAS_CONSOLE "1" and press Enter.

  6. You should get the following message: SUCCESS: Specified value was saved.

  7. Type setx /M QT_FORCE_STDERR_LOGGING "1" and press Enter.

  8. You should get the following message: SUCCESS: Specified value was saved.

  9. Type setx /M QT_LOGGING_RULES "freeciv.stacktrace*=true" and press Enter.

  10. You should get the following message: SUCCESS: Specified value was saved.

  11. Type exit and press Enter twice to close the command shell.

  12. Right click Start Menu and select Windows PowerShell (Admin).

  13. At the PS C:\WINDOWS\System32> prompt, type cmd and press Enter.

  14. At the C:\WINDOWS\System32> prompt, type set and look for the 3 QT_ values set earlier.

  15. Type cd C:\Temp\Freeciv21 and press Enter.

  16. Type freeciv21-client.exe -d debug -l output.log and press Enter.

At this point the player running the test will will see tons of output to the console window, all of it is also being sent to the log file. Launching the game will be slow in debug mode, so it is probably a good idea to let the player know and to be patient.

Have the player do the tests to get to the crash. Open the log file in Notepad++ or any good text file reader. The log file will be quite large. Go to the bottom of the contents and have the player paste the last 100 or so lines to Discord to aid troubleshooting.

Cleaning Up

The player can uninstall the debug package by double-clicking the Uninstall icon in the installed location. They will want to reinstall the regular package to the regular location to fix any shortcuts that get deleted by the uninstall process.

The environment variables can be left as they cause no problems. If the player wants to remove them, they can be found in Start Menu -> Settings -> System -> About -> Advanced System Settings -> Environment Variables.

The PR can be closed at will as we do not merge the change.