What to do when SCP coders cannot reproduce your fs2 open crashes?

From FreeSpace Wiki
Jump to: navigation, search
Note: If you already have gone through the article for checking out the code, or already have an established IDE, you can skip to step 25. This guide is meant to be a 'absolute zero' start to finish for people to be able to follow

(copied from the original post created by Fury)

So you have encountered frequent problems with fs2_open that leads to crashes? You have already provided debug log for support people and coders, but it wasn't enough and no coder can reproduce these crashes to fix the problem? Don't worry, you can help the coders out by providing important information needed to track it down.

This however involves downloading and installing Visual Studio 2015 Community Edition, and the fs2_open repository. All of this has been instructed in detail below, so be sure to follow them to letter and ask for help when needed. It's not hard at all, but it does require some time and effort.

What you however can't do is track down non-crash related problems. Such problems will require more or less knowledge about the code and coding itself.

  1. Go to [1], click "Download Community Free" and install it. The newer Visual Studio include tools for Android development, you don't need this for this guide so deselect that to speed up the installation a bit.
  2. Download the source code and unpack it into a directory of your choice.
  3. Create a new user environment value where variable name is FS2PATH and variable value is full path to your Freespace 2 folder, by default C:\Games\FreeSpace2. This applies too all Windows OS', not just XP.
  4. Restart your computer. This step is REQUIRED for step 3 to take effect! Visual Studio also requires a restart so you could add this variable before doing that restart to save a bit of time.
  5. This step is only relevant if you have been instructed to apply a patch file, if you are unsure, skip this step.
    If you have received a patch-file from a coder then this process is a bit more complicated. First you need to clone the FSO repository, see Getting the source: Tortoise Git for instructions on how to do that. Then apply the patch(es) by following Applying patches.
  6. Go to fs2_open folder (or the clone of it if you followed step 5), open projects\MSVC_2015 folder. From there open file called Freespace2.sln. Select Visual Studio 2015 as the application to open it in if asked to choose an application.
  7. On left side you see a small window called solution explorer. Right click on "Freespace2" and select Properties.
  8. Again on left of the newly opened window you see "common properties" and "configuration properties", under "configuration properties" select "debugging".
  9. Change "Command" to: $(FS2PATH)\$(TargetFileName)
  10. Click OK.
  11. Look up to the toolbar row. Under "Help" you see a green triangle and to right a dropdown menu. Select "Debug SSE2" from the dropdown menu.
  12. Press F7 on your keyboard. A small "Output" window opens. Wait until it finishes, this probably takes a few minutes on most computers.
  13. When text in the "Output" window stops rolling, last three lines should be more or less as follows:
6>  Freespace2.vcxproj -> C:\Games\FreeSpace2\fs2_open\projects\MSVC_2010\Debug SSE2\fs2_open_3_7_2_SSE2.exe
6>          1 file(s) copied.
========== Build: 6 succeeded, 1 failed, 0 up-to-date, 0 skipped ==========

Note: If a coder advises you to do a clean build, you can do this by following steps 6-10. Make sure the Visual Studio window is active, press Ctrl + Alt + F7. Then follow instructions from step 11 onwards. Even if this is not your first time, normally clean build is not needed.

In third to last line you will see the name of the exe file that has been copied to your Freespace2 folder. If a file of same name already existed, it has been overwritten.

In second to last line you will see whether copying has been succeeded or failed, this needs to say succeeded for us to continue. If this says failed, seek assistance on the forums or irc, alternatively browser based irc link.

Note: If you need to seek assistance, select the "Output" window and then press Ctrl + A, this selects all text from the window. Now, copy and paste the text to Pastebin and include a link to your pasted text for coders to read.

Now we need to change a few settings in the launcher before debugging:

  1. From your Freespace2 folder, open launcher. We need to run FSO in windowed mode, so first lower your resolution from video tab. Then go to features tab, select dev tool from under list type. Select windowed mode. Also ensure other settings such as active mod are suitable for your bug hunting. Click OK.
  2. Go back to the Visual Studio window and make sure it is active. Press F5.
  3. In a moment you will see FSO window opening up. Note that running FSO in this mode is significantly slower than it would be normally, you just have to bear with it.
  4. Now play FSO normally until you encounter the crash bug.

Note: If you missed something in the launcher, like selected wrong mod or your resolution is too large or too small for windowed use, exit FSO. Change required settings in the launcher, then select window of Visual Studio to activate it. Press F5 again.

Now we can actually do the important part of this guide:

  1. You have encountered the crash you were looking for. Now, there are two types or crashes. First is straight crash to desktop (CTD) which doesn't produce anything more than regular Windows error message about "this application has closed". Second is an error or assert message given by fs2_open and it gives you two options - OK and Cancel. Click OK.
  2. Now regardless of whether you got a CTD or fs2_open error/assert message, you should now have "fs2_open_3_7_2_DEBUG_SSE2.exe has triggered a breakpoint" message in your Visual Studio window. Click Break.
  3. You see a small window in lower right corner, it has three tabs - call stack, break point and output. Select call stack.
  4. After selecting call stack tab, make sure the small window is active. Press Ctrl + A to select all text, then copy and paste that text to Pastebin.
  5. Now you need to give a link to your pastebinned text to a coder, either in the forums or irc, alternatively browser based irc link.
  6. Follow instructions a coder may give you to further troubleshoot your crash if it is needed.

Note: To repeat these steps at a later date:
  • Download the newest zip of the FSO source or follow Pulling if you already have a clone of the source repository
  • Continue from either step 5 or 6. Steps 5 is an optional step and should only be done if instructed so by a coder. Skip to step 6 if you're unsure.