Development/IDE

From The Document Foundation Wiki
Jump to navigation Jump to search

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.

Im-jabber.svg

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 autogen.sh will create a workspace configuration you can load in VSCode. Use File ▸ Open Workspace… and open the vs-code-template.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

As the workspace file is recreated from a template whenever configure is run, it is suggested to save it to a different file to prevent your edits from being overwritten. Do so using File ▸ Save Workspace as… and save, and replace the currently opened workspace with the one you just saved when prompted.

Editing a .cxx file using Visual Studio Code

In order for the extension to know where the include files are located/to get the proper auto-completion and hover-info, run the task to create the compile-commands.json, either by running make vim-ide-integration manually or by using the task that does the same thing (Terminal ▸ Run Taskcreate compile-commands.json)

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):

{
    "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.

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.

Microsoft Visual Studio

Im-jabber.svg

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.

For Visual Studio 2019:

make vs2019-ide-integration

For Visual Studio 2017:

make vs2017-ide-integration

For Visual Studio 2015:

make vs2015-ide-integration

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: http://nabble.documentfoundation.org/Error-building-Visual-Studio-2013-project-file-for-LibreOffice-on-Windows-tp4140307p4140941.html

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 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.

Qt Creator Run Settings

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 which are managed by the LibreOffice build system). If you have pulled the latest changes, but you 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 in 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:

  1. Add new debug configuration (libreoffice).
  2. 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).
  3. In the project field, add libreoffice project.
  4. Click on "Select other" in the Debug configurations window.
  5. Check "Use configuration specific settings" and select "Standard Attach to Process Launcher".
  6. 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".
  1. Click on apply and close.
  2. 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.
  3. 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.

  1. 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.

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