Development/IDE
TDF LibreOffice Document Liberation Project Community Blogs Weblate Nextcloud Redmine Ask LibreOffice Donate
Introduction
An integrated development environment (IDE) helps developers to have a better coding experience. Considering the fact that LibreOffice has a very large code base, you may use an IDE to simplify coding, building and debugging LibreOffice. You can use several IDEs to work on LibreOffice, including Visual Studio, Visual Studio Code, Qt Creator, KDevelop, Vim, Eclipse CDT and several others. This page describes how to use the IDE of your choice.
For a video walkthrough, you can check out Christian Lohmaier's presentation from FOSDEM 2021, Using IDEs for LibreOffice development.
Visual Studio Code (VSCode)
Running make vscode-ide-integration
will create a workspace configuration you can load in VSCode. Use ▸ and open the vs-code.code-workspace
file. Opening the file will suggest to install the C/C++ extension provided by Microsoft (required to use the debugging features). Other useful extensions include ones that add advanced git functionality such as gitlens
or others that provide syntax highlighting for make files like autoconf
Running make vscode-ide-integration
or autogen.sh
will not overwrite an existing workspace file. If there are differences, it will print a message to manually check for changes.
Running and Debugging
The workspace definition already has a basic debugging configuration defined, but you might want to tweak it for your needs (
▸ → look for the "launch" section)In case your desktop-environment is Gnome, you may want to add this:
"environment": [{"name":"SAL_USE_VCLPLUGIN","value":"gen"}]
Look here for context.
To launch LibreOffice in the debugger, click ▸ . Pretty printing should work, if you configured it for gdb
in the terminal correctly (in other words if you added add add-auto-load-safe-path /path/to/instdir/program/
to your .gdbinit
)
You can add a configuration similar to this one for debugging a unit test module (odfexport
in this case):
Sample configuration for testing odfexport
|
---|
|
Note that the provided example configuration was created on a Linux-system, the steps to create a debug-configuration on Windows and macOS are very similar, as long as you use gdb
/lldb
. Furthermore read up on debugging C++ code with vscode and how to configure the launch.json configuration. For debugging with VSCode on Windows, see this paragraph.
Useful Extensions
Office Open XML format files (.docx, .pptx, .xlsx, etc.) are essentially zip archives containing XML files that describe the corresponding document. To debug manipulating these files in read and write, it is possible to unzip the files, check the contents and then make a new zip archive or update the previous one, but this is tedious and error-prone.
OOXML Viewer is a Visual Studio Code extension that can simplify the modification of these files. It also helps one to see the differences caused by changing and saving Office Open XML format files in LibreOffice and elsewhere. This extension can be installed from "Extensions" section of the Visual Studio Code, and can be used by using right click on the OOXML files and then choosing "Open OOXML Package". In this way, the list of XML files inside the file will be shown in the "OOXML VIEWER" section of the "Explorer" sidebar. By choosing the desired file, it will be opened, and upon change, differences can be shown by using the right-clicking on the XML file and then selecting "Compare with Previous".
Microsoft Visual Studio
Generator script can create solutions for the versions of Microsoft Visual Studio that are supported in the given development branch, and it is known to work fine. In fact, it is one the better supported IDEs. Microsoft Visual Studio Community Edition which is free of charge, is enough to build all LibreOffice features. Invoke appropriate command.
Starting from master toward LO 7.3:
make vs-ide-integration
Debugging a WSL process
To be able to attach to a native (GDB) code type, `cap_sys_ptrace` capability is required:
sudo setcap cap_sys_ptrace=eip /usr/bin/gdb
But with only that, it is impossible to continue the process. The following line enables normal debugging, but is obviously an overkill, and more fine-grained capability assignment is desirable:
sudo setcap all=eip /usr/bin/gdb
Issues
Some problems with some "make" versions have been reported, it would be great if somebody had time to investigate that and figure out how it can be avoided and add instructions here: https://lists.freedesktop.org/archives/libreoffice/2015-February/066607.html
If you use --enable-mergelibs, the generated solution will for unclear reason contain less projects, and have problems finding many symbols. Until that is fixed, it's advisable to avoid --enable-mergelibs when using IDE integration.
Tips
- To avoid a delay when pressing Run button in Visual Studio IDE (useful when you e.g. debug startup code), which is caused by building dependencies (run each time, even when they are up to date), it may be useful to set On Run, when projects are out of date under Options→Projects and Solutions→Build And Run to Never build.
- To enable syntax highlighting for custom extensions, use Visual Studio's Options→Text Editor→File Extension. E.g., add hdl there with "Microsoft Visual C++" Editing Experience, to be able to work conveniently with files generated from IDL files.
Qt Creator
After ensuring that you have a working build of the LibreOffice, invoke this command:
make qtcreator-ide-integration
This will create lo.pro
which can be opened in Qt Creator, and several other dependent project files for the different source folders.
Running and Debugging
You should be able to see these build profiles in Qt Creator:
01-Global Build 02-Global tests -- quick tests (unitcheck) 03-Global tests -- slow tests (unitcheck, slowcheck, screenshot) 04-Global tests -- integration tests (unitcheck, slowcheck, screenshot, subsequentcheck) 05-Global tests -- performance tests (perfcheck) 06-Global tests -- tests (check) 07-Global build -- nocheck 08-Global build -- build-l10n-only 09-Global build -- build-non-l10n-only 10-Global build -- clean 11-Global build -- clean-build 12-Global build -- clean-host
You can use Run and Debug buttons to run and debug LibreOffice. Please note that you should be able to see the executable instdir/program/soffice.bin
in the Run Settings in Projects > Build settings to be able to run LibreOffice directly from Qt Creator.
Issues
Known Issues
If you are building LibreOffice with distro configuration LibreOfficeLinux
./autogen.sh --with-distro=LibreOfficeLinux
you may experience problems with your build, and also with generating the IDE integration files. This issue is being studied, but for now you can avoid the above option.
qmake Based Build Process
LibreOffice has its own build system, and if your project is created successfully, you should not see qmake
based build process happening. But if not, after opening lo.pro, you should remove qmake
from Build Steps in Projects > Build settings. This is because LibreOffice does not use qmake
as a build tool.
Shadow Build
If you are building the LibreOffice Core inside its directory, you should remove Shadow build.
Old Build Configuration
If you change the build configuration, i.e. enable more features by re-running ./autogen.sh
, you may have to repeat this step for additional sources to become part of the Qt Creator project (Otherwise, the warning "This file is not part of any project" may show up even for files that are managed by the LibreOffice build system). If you have pulled the latest changes, but have not changed the configurations, make qtcreator-ide-integration
would be enough.
Debugger Issues
When running your debug builds in the integrated gdb debugger, you may see warnings like:
File "/path/to/workdir/libreoffice/instdir/program/libuno_sal.so.3-gdb.py" auto-loading has been declined by your `auto-load safe-path' set to "$debugdir:$datadir/auto-load".
To allow gdb to load the configuration in your working directory, add both your LibreOffice working directory and the system path for gdb configuration to either your .gdbinit
file or in Qt Creator under Tools > Options > Debugger > Additional Startup Commands like so:
set auto-load safe-path /path/to/workdir/libreoffice:/usr/share/gdb/auto-load
On Windows you should use ;
as path separator instead of :
.
For pretty-printing of certain data types, you can enable it in Qt Creator by setting the checkbox at Tools > Options > Debugger > Load system GDB pretty printers
KDevelop
Currently, the integration for KDevelop is not quite good. It supports KDevelop 4, but not KDevelop 5, so not everything is perfect here.
make kdevelop-ide-integration
Then open one of the *.kdev4 projects with KDevelop.
The tutorial video explains the KDevelop IDE Integration. Also, a shorter teaser version of this video (for sharing on social media, etc.) is also available.
In KDevelop 5, you can create a new project and choose gbuild for the project build configuration.
Issues
Parsing C/C++ headers in KDevelop takes a long time, so be prepared. You will see the progress in the tiny progress bar at the bottom of the KDevelop IDE.
Vim
make vim-ide-integration
This generates a clang compilation database that can be used for YouCompleteMe.
Eclipse CDT
Work has started to generate Eclipse CDT project files, but not yet finished. Feel free to continue this.
In the meantime you can setup Eclipse CDT manually:
- Add new debug configuration (libreoffice).
- In Main tab-> C/C++ Application, browse soffice.bin file that should be in : {your build path}/libreoffice/instdir/program/soffice.bin. (Make sure you enabled debug in your build).
- In the project field, add libreoffice project.
- Click on "Select other" in the Debug configurations window.
- Check "Use configuration specific settings" and select "Standard Attach to Process Launcher".
- Make sure you have these parameters in the Debugger tab:
- Debugger: gdb/mi
- GDB debugger: gdb
- GDB command file: .gdbinit.
- GDB command set: Standard (Linux).
- Protocol: mi.
- Check "Use full file path to set breakpoints".
- Click on apply and close.
- Modify the debugger timeout to prevent this message when debugging: "Target is not responding (timed out)". Go to Window -> Preferences -> C/C++ -> Debug -> GDB MI and set the debugger timeout to 200000 ms and launch timeout to 300000 ms.
- If you're using Ubuntu, the last step before debugging LibreOffice is modifying the ptrace_scope to make it less restrictive. That would prevent this message:
"Could not attach to process. If your uid matches the uid of the target process, check the setting of /proc/sys/kernel/yama/ptrace_scope, or try again as the root user. For more details, see /etc/sysctl.d/10-ptrace.conf". All you need is just setting ptrace_scope to 0 in /etc/sysctl.d/10-ptrace.conf.
- Enjoy the debug and add breakpoints in eclipse as well as you want.
Xcode
make xcode-ide-integration
SlickEdit
Voltron
See Development/Voltron.
PyCharm
PyCharm is an IDE for Python programming language, created by JetBrains. It is possible to write, edit and debug Python code that is part of the LibreOffice core, or Python scripts that work with UNO API inside PyCharm. It should be noted that UITests in LibreOffice is written in Python, and can be used in this IDE.
Here, it is assumed that you have built the LibreOffice core from source code, and you want to work with the Python files from core, but it should be also possible to work with the LibreOffice Python binary. To get started with editing, running and debugging LibreOffice related Python files in PyCharm, follow these steps.
First, you should add the internally built Python for LibreOffice. This can be done in
▸ , and then ▸ , then ▸ from the top right. You can add system or virtualenv Python interpreter that will be used for running your Python files. You can name this new interpreter as Python (LibreOffice).You have to open the Python file in PyCharm using
▸ , and then add a new run configuration using ▸ or the same settings from the toolbar. There, you have to add a new configuration with button on the top left, and then fill the text boxes with correct values. You have to fill these parts: (these are tailored for running a UITest)- Script path:
$SRCDIR/uitest/test_main.py
- Parameters:
--soffice=path:$SRCDIR/instdir/program/soffice --userdir=file:///tmp/libreoffice/4 --file=$FilePath$
- Environment variables: As discussed in running UITests; For example, by assuming source directory for core is
/home/user/libreoffice/core
, it would be:
PYTHONUNBUFFERED=1;LC_ALL=C;SRCDIR=/home/user/libreoffice/core;PYTHONPATH=/home/user/libreoffice/core/instdir/program/:/home/user/libreoffice/core/unotest/source/python/;SAL_USE_VCLPLUGIN=gen;TDOC=/home/user/libreoffice/core/sw/qa/uitest/data;TestUserDir=file:///tmp;URE_BOOTSTRAP=file:///home/user/libreoffice/core/instdir/program/fundamentalrc
- Python interpreter: Python (LibreOffice)
.../instdir/program/python
As you can see, $FilePath$
is used instead of a specific Python file name; thus, you should be able to open different Python UITests. Then, you can run each with ▸ . Currently, debugging UITests is not possible in this way.
For running or debugging other Python file from LibreOffice project, or Python files that work with UNO API, you should change the Script path to the Python file name, or $FilePath$
to run every opened Python file directly. you can run each with ▸ , or debug with ▸ .
Others
There are other IDEs like Netbeans and CLion. Feel free to add support for them to gbuild-to-ide.
Issues
mergelib option
Note that --enable-mergelibs
autogen option affects IDE integration, since all merged libs are excluded from gbuild-to-ide
.
Debugging with a Graphical IDE on gnome
If you happen to work on Linux with gnome as your desktop environment and you are using a graphical IDE for debugging, you may run into the following issue: Gnome will popup a dialog, that LibreOffice has become unresponsive and present you with the option to either "Force Quit" or "Wait". However, after clicking "Wait", after a short time, the dialog will pop-up again. Additionally, the moment the dialog appears, your graphical IDE will become unresponsive to mouse-clicks until you click "Wait". This bug has been reported, but so far no fix has been provided, unfortunately. There is a little workaround, however:
Build LibreOffice with --enable-debug
and set SAL_USE_VCLPLUGIN = gen
in your environment, before you start debugging. This should do the trick and let you debug to your heart's content.
Internals
The script to generate these IDE projects is in bin/gbuild-to-ide, which is a Python script. You are welcome to adopt the script to support more IDEs!
Running the Generator Script Manually
If you want to run the generator script directly, you should first set several environment variables: GPERF
, SRCDIR
, BUILDDIR
, WORKDIR
and INSTDIR
. This can be done by invoking these commands from the source folder root of the LibreOffice core:
export GPERF=gperf
export SRCDIR=$PWD
export BUILDDIR=$PWD
export WORKDIR=$PWD/workdir
export INSTDIR=$PWD/instdir
An then you can build the desired integration manually. for example, this creates project file for Qt Creator:
./bin/gbuild-to-ide --ide qtcreator --make make
Debugging the IDE Project Generator
You can dump the parse result of the the gbuild-to-ide
script for debug reasons. After setting environment variables as before, invoke this command:
./bin/gbuild-to-ide --ide debug --make make