Difference between revisions of "Troubleshooting EDuke32" - EDukeWiki

# Difference between revisions of "Troubleshooting EDuke32"

From EDukeWiki

Revision as of 03:28, 7 July 2012 (view source) Helixhorned (talk | contribs) (→‎example: fix it) ← Older edit | Revision as of 04:54, 22 July 2012 (view source) Helixhorned (talk | contribs) (→‎tips for a quicker bug handling) Newer edit →
Line 21: | Line 21:
| * '''Show, don't merely tell.''' For example, if it's an editor bug, attatch a small test map with the bug report or PM it in case you don't want it to be public. |  | * '''Show, don't merely tell.''' For example, if it's an editor bug, attatch a small test map with the bug report or PM it in case you don't want it to be public.
| * '''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. |  | * '''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 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"
| This will help us and help you find solutions much more quickly and effectively. |  | This will help us and help you find solutions much more quickly and effectively.

## Revision as of 04:54, 22 July 2012

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 to see if anyone else has experienced the same issue. Do not post a new thread if a thread for a similar problem already exists.

Always do a search for your problem before posting. Any new topics 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).
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.

### tips for a quicker bug handling

- Show, don't merely tell. For example, if it's an editor bug, attatch a small test map with the bug report or PM it in case you don't want it to be public.
- 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 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"

This will help us and help you find solutions much more quickly and effectively.

## 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. If you encounter the crash again, look for a file named eduke32_or_mapster32.crashlog 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 Nbad --, 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 Ngood, one would now proceed by testing the one that lies roughly between the two, Ntest := round((Nbad+Ngood)/2). After carrying out the test, one either lets Nbad:=Ntest or Ngood:=Ntest, 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.

### 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 log2(Nbad0-Ngood0) (for the current example, 10) steps.

## Debugging

The most insidious types of bugs are those that occur randomly and with no apparent pattern. To help the developers in tracking down crashes happening this way, 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, instead you just have to install the compiler.

To debug the program, (synthesis build recommended) open a command prompt or terminal window and run this command, using Mapster32 as an example:

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

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.

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.

Retrieved from "http://wiki.eduke32.com/w/index.php?title=Troubleshooting_EDuke32&oldid=11052"