Troubleshooting
Before filing a issue, please go through the following simple steps to narrow down the problem you are encountering.
Due to the nature of GammaRay it can happen that something in GammaRay interferes with your application, the more complex a target application gets the more likely this becomes. GammaRay tries to be as little intrusive as possible, but sometimes target applications do things we did not anticipate, resulting in failure to launch or attach GammaRay. The following steps help to distinguish this case from local setup issues.
GammaRay injects a DLL into the target process (the so-called probe), and therefor that DLL must match the ABI of the target process. The ABI is dependent on architecture (relevant on mixed 32/64 bit systems), Qt version, compiler version, and debug/release mode (Windows only).
If GammaRay refuses to launch/attach to a target due to mismatching probe ABI, it is quite likely you have built GammaRay in a different configuration than your target. The graphical launcher will show you a list of GammaRay probes and their ABIs, and it will show the detected ABI of processes in the attach tab in their tooltips.
Simple Qt examples work well for this, the tools that come with Qt (Assistant, Designer, etc) are also known to work well. QtCreator works too (although it doesn't exactly qualify as simple), unless you have the GammaRay integration plug-in installed (GammaRay cannot inspect processes using GammaRay libraries themselves). The GammaRay source code also contains a number of simple test targets you can use for this.
If any of these work, your setup is correct and you might have a target application that is incompatible with GammaRay. The following steps further narrow this down.
Launching (and thus injecting GammaRay right from the start) is much more robust on most platforms, and produces higher quality results. You can do this both with the graphical launcher or the command line interface.
If launching works but attaching fails, this at least gives you a workaround for now. If you are on an platform other than Windows, check the "Self Test" tab in the graphical launcher, at least one of the gdb and lldb injectors should be passing their tests.
GammaRay supports different ways of getting into the target process, depending on the operating system. By default, the method producing the highest quality results (ie. "seeing" the most objects) and achieving the best performance is used. However, these tend to also be the most fragile ones, as they rely on specific behavior of the dynamic linker. It's therefore useful to try with one of the much more robust fallbacks, such as the "style" injector. This can only be done with the command line interface though, not the graphical launcher, using the "-i style" argument.
See Known Issues.
We run a continuous integration system for a large number of Qt version/platform combinations, but due its very platform specific code and its use of internal/unstable Qt API, it is possible you might run into build errors. Please look through the following simple steps to ensure it's not a local setup issue, before reporting the build error.
See Building From Source.
Make sure you have the latest version (master, or latest stable branch), the problem might have been fixed already.
When reporting issues in the Github issue tracker, please always include:
- The exact GammaRay version, preferably the Git revision if you have that, version number otherwise.
- The exact Qt version you are building GammaRay for. If you have a customized Qt build with e.g. a non-standard configuration, that's also valuable information.
- The operating system you are on, including its version. If you are cross-compiling GammaRay, host and target operating system matter.
- The compiler you are using and its version.
When reporting build errors, please include the actual compile error with enough context to see the corresponding compiler/linker call. The CMake output is also useful. If you have it, the full build log is actually best.
When reporting runtime errors, the best case scenario is a test case we can reproduce. If you can trigger the problem you are seeing with publicly available software (Qt examples, open source software, a test case you can share), this makes things a lot easier for us. If this isn't possible, at least include all information you see (stdout, error messages, backtraces in case of a crash).
As part of commercial support, KDAB can also investigate problems on a non-public target applications under NDA, if we have no other way of reproducing your issue. Please contact us at info@kdab.com for this.
