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.

Note:
Before using an IDE you need to do a complete build from a terminal with the usual "./autogen.sh && make check".

Visual Studio Code (VSCode)

Running make vscode-ide-integration will create a workspace configuration you can load in VSCode. Use File ▸ Open Workspace… 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.

Editing a .cxx file using Visual Studio Code

Running and Debugging

The workspace definition already has a basic debugging configuration defined, but you might want to tweak it for your needs (Run ▸ Open Configurations… → 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 Run ▸ Start Debugging. 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

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "(gdb) odfexport",
            "type": "cppdbg",
            "request": "launch",
            "program": "${workspaceFolder}/workdir/LinkTarget/Executable/cppunittester",
            "args":
            [
                "${workspaceFolder}/workdir/LinkTarget/CppunitTest/libtest_sw_odfexport.so",
                "--headless",
                "-env:BRAND_BASE_DIR=file://${workspaceFolder}/instdir",
                "-env:BRAND_SHARE_SUBDIR=share",
                "-env:BRAND_SHARE_RESOURCE_SUBDIR=program/resource",
                "-env:UserInstallation=file://${workspaceFolder}/workdir/CppunitTest/sw_odfexport.test.user",
                "-env:CONFIGURATION_LAYERS=xcsxcu:file://${workspaceFolder}/instdir/share/registry xcsxcu:file://${workspaceFolder}/workdir/unittest/registry",
                "-env:UNO_TYPES=file://${workspaceFolder}/instdir/program/types.rdb file://${workspaceFolder}/instdir/program/types/offapi.rdb",
                "-env:UNO_SERVICES=file://${workspaceFolder}/workdir/Rdb/ure/services.rdb file://${workspaceFolder}/workdir/Rdb/services.rdb",
                "-env:URE_INTERNAL_LIB_DIR=file://${workspaceFolder}/instdir/program",
                "-env:LO_LIB_DIR=file://${workspaceFolder}/instdir/program",
                "-env:LO_JAVA_DIR=file://${workspaceFolder}/instdir/program/classes",
                "--protector",
                "${workspaceFolder}/workdir/LinkTarget/Library/unoexceptionprotector.so",
                "unoexceptionprotector",
                "--protector",
                "${workspaceFolder}/workdir/LinkTarget/Library/unobootstrapprotector.so",
                "unobootstrapprotector",
                "--protector",
                "${workspaceFolder}/workdir/LinkTarget/Library/libvclbootstrapprotector.so",
                "vclbootstrapprotector",
                "-env:CPPUNITTESTTARGET=${workspaceFolder}/workdir/CppunitTest/sw_odfexport.test",
            ],
            "stopAtEntry": false,
            "cwd": "${workspaceFolder}/workdir/CppunitTest/sw_odfexport.test.core",
            "additionalSOLibSearchPath": "${workspaceFolder}/instdir/program;${workspaceFolder}/workdir/UnpackedTarball/cppunit/src/cppunit/.libs",
            "environment":
            [
                {"name":"LD_LIBRARY_PATH","value":"${workspaceFolder}/instdir/program:${workspaceFolder}/workdir/UnpackedTarball/cppunit/src/cppunit/.libs"},
                {"name":"MALLOC_CHECK_","value":2},
                {"name":"MALLOC_PERTURB_","value":153},
                {"name":"SRC_ROOT","value":"${workspaceFolder}"},
                {"name":"WORKDIR_FOR_BUILD","value":"${workspaceFolder}/workdir/CppunitTest/sw_odfexport.test.core"},
            ],
            "externalConsole": false,
            "MIMode": "gdb",
            "setupCommands": [
                {
                    "description": "Enable pretty-printing for gdb",
                    "text": "-enable-pretty-printing",
                    "ignoreFailures": true
                }
            ]
        }
    ]
}

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.

Also, please note that these instructions may not work with vscodium, as extension availability for code completion and debugging is different in that product compared to vscode on platforms like macOS.

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

Note:
You need to build with --enable-debug or --enable-dbgutil in order to generate the Visual Studio IDE integration.

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.

Editing a .cxx file using KDevelop

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

See Development/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 File ▸ Settings, and then Project: ... ▸ Python Interpreter, then ⚙ ▸ Add 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 File ▸ Open, and then add a new run configuration using Run ▸ Edit Configurations 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 Run ▸ Run .... 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 Run ▸ Run ..., or debug with Run ▸ Debug ....

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