This page describes Debug Information that you may wish to provide to the developers when submitting a BugReport.
- 1 This is ADVANCED Stuff
- 2 Debugging Information by OS
- 3 GNU/Linux
- 4 Windows
- 5 Mac OSX
This is ADVANCED Stuff
Please don't feel obligated to provide any of this information, unless
- You're a developer/programmer and know what this stuff means
- A developer or someone in QA has explicitly asked you to provide this information
- You're on the QA Team
Debugging Information by OS
These instructions are all pretty OS-specific, so we'll split up the rest of this page by OS
In order to produce these various debugging logs, you should first install the debugging packages. The debugging package for (older) Debian, Ubuntu or their derivatives is libreoffice-dbg, while for newer Debian, Ubuntu it is libreoffice-*-dbgsym. For other distributions it is libreoffice*-debuginfo, while in some RPM distributions it is libreoffice-gdb-debug-support. Please be aware that these packages may require 2.5GB+ space to install.
Another option is to roll your own debug build using
--enable-symbols. The latter doesn't change program logic, disable optimizations, and doesn't enable additional assertions/checks that the
--enable-debug switch does.
A third option is to download a daily built debug build and run it. They can be found here, in folders that ends with -dbg. Please be aware that the download will be 1.6GB+ and when extracted it takes up ~5GB.
GNU/Linux: How to get a backtrace
The backtrace is useful for analysing the reasons why an application crashes or freezes. The backtrace can be run without the debugging packages, but it wont be as useful, but still could potentially provide at least some information. You might use the following steps:
NOTE: Before you launch LibreOffice in debug mode, make sure gdbtrace.log doesn't exist in the folder where you are launching LibreOffice from, otherwise, delete it!
- start a terminal / shell (in some distros you can press Ctrl+Alt+T to do this)
- run `$ soffice --backtrace`
- if you see the cursor blink on a line that starts with `(gdb)`, then type 'run' and then enter (this happens when a user profile isn't present)
- reproduce the crash or hang. If its a hang, you will need to force a crash, so open another console and type `$ pkill -15 soffice.bin` or alternatively type `$ xkill` and click on the hung libreoffice window.
- if you are not returned back to the default prompt and are on a line with a blinking cursor, type 'bt' and then enter. If instead you are at a line that starts with `(gdb)`, type 'quit' to return to the prompt.
- a gdbtrace.log file will be created in the same folder.
- attach gdbtrace.log to the bug report.
Alternatively, you can attach gdb to the soffice.bin process after starting LibreOffice. If you have only one LibreOffice process running, you can attach to it quickly like this: gdb --pid `pgrep soffice`
GNU/Linux: How to get an strace log
strace traces the system calls that a process makes. If there is some problem around file-I/O this can be a great way of detecting exactly what is going on at an operating-system level. It's also a fast way to see whether the program continues executing and/or has hung, and finding information about the system LibreOffice is run on.
- start a terminal
- soffice --strace
- reproduce your problem
- compress the log: bzip2 strace.log
- now attach the strace.log.bz2 file that is produced to the bug report.
GNU/Linux: How to get a Valgrind log
The valgrind log is invaluable for tracing obscure memory corruption errors that can be extremely difficult to find otherwise. It achieves this by emulating a CPU. The slight downside of that is that the code runs around eighty (80x) slower, which will seem slow to you. The plus side is that it shows us problems that are un-findable in any other way, and that the traces produced very often pinpoint the issue in such a way that it is rather easy for a developer to fix: your patience is much appreciated. Valgrind can also produce a number of false-positives.
- install the valgrind package
- start a terminal
- soffice --valgrind >& /tmp/valgrind.log
- be patient ... 80x is a lot slower ... reproduce the problem.
- attach /tmp/valgrind.log to the bug report.
If you want to specify some additional options for valgrind, you can use VALGRIND_OPTS environment variable.
GNU/Linux: How to get a callgrind trace
A callgrind trace will immediately point the finger at poorly performing pieces of code and uses valgrind to model a CPU, so requires the installation of the valgrind package. This type of trace provides a hierarchical, navigable histogram view of where the time is spent in the code, which can be viewed in apps like kcachegrind. Callgrind traces are a CPU intensive process and LibreOffice will run many times slower than it normally does, so it shouldnt be undertaken by a user with a slow PC. In addition to a fast PC, LibreOffice will need to be built with
--enable-symbols and not
--enable-debug, as debug builds behave very abnormally with respect to performance.
- start a terminal in the LibreOffice program folder (e.g. ~/core/instdir/program)
- `$ unset MALLOC_CHECK_`
- `$ unset MALLOC_PERTURB_`
- `$ unset G_SLICE` # these three stop us getting poor performance from unusual allocators
- `$ export SAL_DISABLE_FLOATGRAB=1` # if we wedge at least we don't do it while grabbing the mouse
- `$ export OOO_DISABLE_RECOVERY=1` # turns off recovery dialog which can be a pain
- `$ export SAL_DISABLE_GL_WATCHDOG=1` # turns off GL watchdog. It normally kills the application, if it seems to hang in a GL block
- `$ valgrind --tool=callgrind --simulate-cache=yes --dump-instr=yes ./soffice.bin --splash-pipe=0`
If the problem you are tracing is the slow opening time of a document, you might want to include this environment variable to immediately exit after opening:
`$ export OOO_EXIT_POST_STARTUP=1`
After running the trace and exiting cleanly (in extremes press ctrl+c only once! in the terminal), you will find a large file called: callgrind.out.12345 where 12345 is the PID. Compress this file and attach it to the bug report or upload it somewhere for a developer to access. A
--enable-symbols build of LibreOffice will add an extra ~10GB to an existing build system as the symbols will be added to .so files in the instdir folder and .o files in the workdir. The symbols can be removed these files by running strip on the files or by removing the instdir and workdir folders and rebuilding.
Windows: How to get a backtrace
If you have LibreOffice 4.2.0 or higher installed and your version includes debugging functionality, there is a test symbol server containing the corresponding debugging symbols. Read How to get a backtrace with WinDbg to set up the debugging environment and you can also watch this video to help understand the process.
Windows: how to get OpenGL debug output
- Download and install a build with debugging features, eg.: http://dev-builds.libreoffice.org/daily/master/Win-x86@39/current/
- In the Windows command line, give this command to set a logging environment variable: set SAL_LOG=+INFO.vcl.opengl+WARN
- From the same command line window, launch LibreOffice with this command (add the full path, if launching outside the program folder): soffice.exe --calc 2>soffice.log
Now try to reproduce your OpenGL problem. Debug output will be written to the soffice.log file, which you can then attach to a bug report.
Windows: how to get OpenCL debug output
See above, except use set SAL_LOG=+INFO.opencl+INFO.sc.opencl+WARN as the environment variable.
You can also use this program to print OpenCL information to a file: http://dev-www.libreoffice.org/opencl/Windows/Opencl%20Info.exe
Windows: Debugging a GDI Resource Leak ( vcl::Window::dispose() )
By default, the limit of unique GDI objects in memory at the same time is 10.000 and if LibreOffice reaches it we might experience a vcl::Window::dispose() crash. It might be specially problematic at save time, when LibreOffice might create thousands of VirtualDevices. In order to check whether we have reach the limit of GDI object in memory we can follow step 1 in this page or use an application called GDI handles.
In case we confirm the limit has been reached, we can follow steps 2, 3 and 4 from this page to provide further debugging information.
Example: Bug 102688
Windows: how to trace a memory corruption with DrMemory
Mac OSX: How to get debug information
The debug information is useful for analyzing the reasons why an application crashes or freezes. On Mac OS X, you can receive the standard debug information very simply, without installing any additional software. (This information even includes a simple stack trace, which misses full symbols, but can nevertheless be very useful.)
The exact steps vary depending on your Mac OS X version and setup, but in general you get the debug information as follows:
- When an application crashes, Mac OS X prompts you with a dialog window saying “LibreOffice quit unexpectedly.” and asks you if you want to send a report to Apple. Click on the button labelled “Report…”. Now a larger window with the title “Problem Report for LibreOffice” opens; under “Problem Details and System Configuration”, you find an edit field with a long text containing much technical details. You can just click into this long text, press ⌘ Cmd+a to select all the text, then press ⌘ Cmd+c to copy it and then switch to any text editor (e.g. Apple's TextEdit) and press ⌘ Cmd+v to insert the text. Then you can save the text as a new file; the best would be to use a plain text (.txt) format. Please attach that file to your bug report. (You do not need to send the report to Apple, so click on the “Don't Send” in the “Problem Report” window.)
- When an application hangs or freezes, you can force quit it by pressing ⌘ Cmd+Alt+Esc. Mac OS X prompts you with a dialog window entitled “Force Quit Applications”, asking which application(s) you want to quit; in that list, you can recognize the application which hangs or freezes often by the hint “(not responding)”. Select it and click the button “Force quit”. Depending on your system configuration, you will be asked if you want to send a report about that to Apple; if you confirm this, you will get the same “Problem Report” window as described above, and can copy and save the debug information text in the same way.
NB: Depending on your system configuration and user setup, you may or may not be asked about sending a report to Apple; you may need to be logged in as an admin user to see these dialogs.