Troubleshooting EDuke32

The first step in troubleshooting EDuke32 is testing the most recent unstable version, automatically generated every 20 minutes if changes have been made to the source code.

Basic Assistance

If you have a problem with EDuke32 or Mapster32, READ THE THREADS HERE FIRST, as well as THE ISSUES PAGE ON THE GITLAB to see if anyone else has experienced the same issue. Do not post a new thread or a new issue if a similar problem has already been reported.

Always do a search for your problem before posting. Any new topics/issues should clearly describe the problem in the title/summary.

If you find no previous reports of your issue, prepare to submit a bug report to the forum. For general help, follow the instructions below in a new thread at the forum link above. For a problem with a particular TC or mod, it may be better to contact its author directly depending on the circumstances and the nature of the error.

Please add the following information to any bug report:

1. You need to locate a file in your EDuke32 data called eduke32.log or mapster32.log depending on which program encountered the error. This file is overwritten every time the programs are run, so it is vital that the log file comes from an occasion when you encountered the problem and have not run the program again afterwards. Any log files should be posted as attachments or loaded on to http://pastebin.com/. Absolutely do NOT post logs as part of your post text itself!
2. Your system specifications (OS, GPU, CPU, etc) may be helpful, especially with OpenGL graphics- or performance-related reports. CPUID CPU-Z is useful for details.
3. What version of EDuke32 you are running.
4. What you were doing at the time.
5. Be ready to upload or private message any modified con/sound/art/maps etc related to the above in the event an easy solution cannot be found.
6. Go to http://dukeworld.duke4.net/eduke32/synthesis and find the first build that exhibits the problem, and post the build numbers of the last working version and the first broken version. See the Bisecting subsection below for how to do this efficiently.

tips for quicker bug handling

The following points will help us and help you find solutions much more quickly and effectively, which should be in the interest of all parties involved.

• When in doubt whether a log is useful or not, attach it regardless. This means that time can be spent on actually fixing the bug instead of asking for the log and waiting... and waiting... and waiting...
• Show, don't merely tell. For example, if it is an editor bug, attach a small test map with the bug report or PM it in case you don't want it to be public.
• When reporting a bug for the first time, assume that you're the first to encounter it, that is, don't leave out details just because you think they're "well known".
• Assume vanilla Duke unless known otherwise. For example, if developing a new mod containing new art and reporting an editor or game effect bug, load the map in a vanilla installation and replace all now-void tiles using [']+[F] -> replace invalid tiles. Similarly, when filing a CON bug, try to present it such that it can be loaded as a stand-alone module (-mx switch to EDuke32). Of course, for released mods, it's OK to do otherwise if it's known that the developer(s) have that particular mod installed.
• When referring to locations in a map, don't assume that the developers have played them unless it's a vanilla map or a classic "must play" plain user map (what constitutes such a map is somewhat subjective, of course). Instead, provide coordinates for the location, obtainable by pressing LShift in Mapster32, or with the DNCOORDS cheat in the game. Feel free to round the numbers for prettier appearance, as long as it's reasonably clear what place is meant.

Crashes

If you encounter an actual program crash, try running the debug executables (eduke32.debug.exe or mapster32.debug.exe) included in the EDuke32 builds available from synthesis. Put the according backtrace DLL (32/64 bit) alongside the debug executable. If you encounter the crash again, look for a file named eduke32.crash.log or mapster32.crash.log and include it when following the directions in the Basic Assistance section.

If you cannot find this file, please proceed to the Debugging section.

Bisecting

A very useful piece of information when reporting a bug is the particular revision that introduced the bug, or at least range of revisions. Finding it does not require searching all revisions in sequence. First, a revision needs to be found that doesn't show the buggy behavior. Either you might have a suspicion when it occured, otherwise you can try the earliest revisions from synthesis, old synthesis, or snapshots prior to automated builds for really ancient bugs. (For certain bugs, it may also be worthwhile to check whether the original Duke3D 1.5 exhibits it, too). At this point, it also helps to have constructed a small test case, so that one can decide "faulty/working" relatively quickly (for example by starting a map in a particular position and doing something). Having found this "base" bad revision -- let's call it N_bad --, the idea now is to search the one revision that introduced the bug by cutting the search space roughly by half with each step. Calling the current revision N_good, one would now proceed by testing the one that lies roughly between the two, N_test := round((N_bad+N_good)/2). After carrying out the test, one either lets N_bad:=N_test or N_good:=N_test, always such that the bug-introducing revision will be between these two "anchor" revisions. Finally, one repeats this procedure until arriving at a revision difference of one (or giving up early, which still leaves a revision range as a result).

It should be noted that this procedure should be best carried out in an isolated directory, because the generated configuration files of earlier revisions might produce conflicts or remove options from ones of newer builds.

Depending on the setup, this procedure takes about 15 to 30 minutes.

example

Here's a log of synthesis builds tested when searching for the revision that introduced a certain bug with viewscreens. For this, a test map was constructed that started near such a viewscreen.

0. (current revision) r2781 -- BAD
1. (first guess) r2000 -- GOOD

Now, we know that the bug must have been introduced between r2000 and r2781, so we pick one in between:

2. r2300 -- BAD
(now, r2000 vs. r2300)

3. r2155 -- GOOD
(now, r2155 vs. r2300)

4. r2239 -- BAD
(now, r2155 vs. r2239)

... and so on, until one arrives at the bug-introducing revision in around log₂(N_bad0-N_good0) (for the current example, 10) steps.

Debugging

To help the developers in tracking down crashes, you could try running a debug version of the executable under GDB, the GNU debugger, until the crash happens.

If you are running Windows and do not already have GDB set up, follow the instructions to set up Building EDuke32 on Windows and it will be included. You do not have to compile EDuke32 yourself if you have a debug build already, instead you just have to install the compiler.

building with debug symbols

If you are using a synthesis build on Windows, use *.debug.exe

If you are building from source, append RELEASE=0 to your make invocation. If you have already built, you will need to make clean first.

running the debugger

To debug the program, we will use GDB.

On Windows, open a command prompt and run this command, using Mapster32 as an example:

gdb --args mapster32.debug.exe [additional arguments...]

On Linux, run this command from a terminal:

gdb --args ./mapster32 [additional arguments...]

On macOS, use LLDB.

lldb -- ./Mapster32.app [additional arguments...]

using the debugger

and enter

r

(run) at the GDB prompt. When the program crashes, you will be taken back to the prompt. Enter

bt

(backtrace) there. This will print out the location where the crash occurred and serve as a first diagnostic to the developers.

If the program terminates mysteriously without a crash, you can try the following command and then run again:

b exit

advanced debugging

There are specific circumstances where you can use breakpoints and watchpoints if you know where they would be applicable.

submitting the output

Copy and paste the output gdb displays and send it to the developers so they can work on a fix. Pastebin.com is useful for this purpose.