Linux Linking Paths for Development

When developing on Linux, you may need to link to libraries that are not part of LibreOffice. This guide is one of several ways that develop environments can be set up to work with LibreOffice. See also Live LibreOffice Python for a Codespace that is ready to go.

This guide is for Ubuntu 22.04, but should work for other versions of Ubuntu and other Linux distributions.

This guide requires that the Include Python Path for LibreOffice extension is installed into LibreOffice.

Setting up Virtual Environment

First, create a virtual environment for your project.

The path for the project root directory is ~/Documents/Projects/Python/LibreOffice/demo_env for this demo.

python3 -m venv venv
source venv/bin/activate

Install ooo-dev-tools. This will install the ooo-dev-tools package, which has many useful tools for developing with LibreOffice and includes full typing (auto-complete) support for the LibreOffice API. The OOO Development Tools Extension can be installed into LibreOffice to provide access to the ooo-dev-tools package for when not in development mode. If the extension is installed, then the ooo-dev-tools package should still be installed in the virtual environment for development purposes.

pip install ooo-dev-tools

Add a module to your project

Create a new folder in your project called my_mod. In this folder create a file called __init__.py. This file can be empty. Create a file called hello.py and add the following code.

from __future__ import annotations
from ooodev.loader import Lo

def main():
    doc = Lo.current_doc
    doc.msgbox('Hello, world!')

if __name__ == '__main__':
    main()

This is simple code that will display a message box with the text “Hello, world!”.

Linking to LibreOffice

Using Include Python Path for LibreOffice is the easiest way to link to LibreOffice.

Start LibreOffice and open the extension manager Tools -> Extension Manager... Select LibreOffice Python Path Extension. Click on Options.

Fig. 1203 Extension Manager

Select the Python Paths option page.

Fig. 1204 Python Paths

Choose Add Folder and navigate to the Location of the site-packages for the virtual environment that was set up previously. Also add the root directory for your project, demo_env in this case.

Fig. 1205 Add Folder

After the folders have been added, click OK to close the dialog. Restart LibreOffice to apply the changes.

Note

The path for the project root directory is ~/Documents/Projects/Python/LibreOffice/demo_env for this demo. The site-packages folder is located in the virtual environment that was created earlier. The path to the site-packages folder is venv/lib/python3.10/site-packages.

Running the hello module.

Open the APSO console. See Install APSO LibreOffice Extension.

Import your module and run the main function.

Fig. 1206 APSO Console

from my_mod import hello
hello.main()

Add Macro Support

It may be useful to add macro support to your project. This can be done by creating a symbolic link to the project macros folder in the LibreOffice Script/python folder.

Create a folder called macros in the root of your project. This folder will contain the macro files. Like the example above we will write a simple macro that will display a message box with the text “Hello, world!”.

Create a file called say_hello.py in the macros folder and add the following code.

from __future__ import annotations
from ooodev.loader import Lo


def say_hello(*args):
    doc = Lo.current_doc
    doc.msgbox("Hello, world!")

g_exportedScripts = (say_hello,)

LibreOffice uses the ~/.config/libreoffice/4/user/Scripts/python folder to store Python macros. Create a symbolic link to the project macros folder in the ~/.config/libreoffice/4/user/Scripts/python folder.

Make sure that the python folder exists in the ~/.config/libreoffice/4/user/Scripts folder. If it does not exist, create it.

Run the following command to create the symbolic link.

ln -s ~/Documents/Projects/Python/LibreOffice/demo_env/macros ~/.config/libreoffice/4/user/Scripts/python/my_macro

Now start LibreOffice and run the Macro.

Tools -> Macros -> Run Macro...

Fig. 1207 Run Macro

Conclusion

This guide has shown how to link to LibreOffice on Linux for development purposes. With a link to the virtual environment site-packages and the project root directory, it is possible to develop and test Python code that uses the LibreOffice API. The addition of a symbolic link to the project macros folder in the LibreOffice Script/python folder allows for the development and testing of Python macros. While this is not the only way to set up a development environment for LibreOffice, it is a simple and effective way to get started. When ever possible Live LibreOffice Python is recommended for development.

See Also

• Debug Macros in Vs Code.

• Live LibreOffice Python.

• Guide on embedding python macros in a LibreOffice Document

Note

This guide is for development purposes only. It is not recommended to use this method for production.