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 macOS
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.
gdbtrace.logfile 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
- reproduce your problem
- compress the log:
- now attach the
strace.log.bz2file 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
- start a terminal
soffice --valgrind >& /tmp/valgrind.log
- be patient ... 80x is a lot slower ... reproduce the problem.
/tmp/valgrind.logto 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.
$ unset MALLOC_CHECK_ MALLOC_PERTURB_ 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.
There is a way to speed up the tracing and make it only include relevant data:
- Launch with
valgrind --tool=callgrind --simulate-cache=yes --dump-instr=yes --instr-atstart=no ./soffice.bin --splash-pipe=0
- Prepare to do the thing that you want to trace in LibreOffice
- In another terminal, give the command
callgrind_control -i on
- Do the thing you want to trace
- In the other terminal, give the command
- Stop the tracing and kill LibreOffice by
An alternative to callgrind is perf. Its output is not as detailed as callgrind's, but as it runs much faster, you might prefer it over callgrind in many cases.
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.: https://dev-builds.libreoffice.org/daily/master/Win-x86@39/current/
- Download and install cygwin (only the minimum default base): https://cygwin.com/setup-x86_64.exe
- In the cygwin command line, give this command to set a logging environment variable:
- You might want to change directory to the LibreOffice program folder like so:
cd "/cygdrive/c/Program Files (x86)/LibreOfficeDev 6/program"
- 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
macOS: How to get debug information
The debug information is useful for analyzing the reasons why an application crashes or freezes. On macOS, 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 macOS version and setup, but in general you get the debug information as follows:
- When an application crashes, macOS 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. macOS 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.