Debug Macros in Vs Code

Debug Macros

• Debug Macros
  • Prerequisites
  • Getting Started
  • Debug Macro
  • Ending Session
  • Togging Debugger
  • Quick Start
  • Debug console
  • Trouble Shooting

It is possible to debug LibreOffice macros in VS Code Using debugpy with Live LibreOffice Python.

Prerequisites

There is a python script in the macro folder.

dbs.py Python Script:

NOTE: ooodev_ex should be replaced with the name of the module that contains the macro that you want to debug.

import importlib
import debugpy

debugpy.listen(8550)
debugpy.wait_for_client()  # blocks execution until client is attached
print("Debug Proceeding ...")

# replace ooodev_ex with the name of your module here
from macro import ooodev_ex as my_macro

def mod():
    return my_macro

def rl():
    importlib.reload(my_macro)

# make sure this is not run as macro in LibreOffice
g_exportedScripts = ()

This is the entry point for debugging. It will listen on port 8550 for a connection from VS Code.

The dbs.py script has several parts.

import debugpy

debugpy.listen(8550)
debugpy.wait_for_client()  # blocks execution until client is attached
# ...

This above section is what allows VS Code to connect to the script. Note that the port, 8550, is the same a found in the launch.json file.

from macro import ooodev_ex as my_macro

This above section import the current module being debugged ooodev_ex should be the name of the module that contains the macro that you want to debug.

def mod():
    return my_macro

def rl():
    importlib.reload(my_macro)

The mod() method gives an easy way to get access to your macro module during debug.

Example:

from macro import dbs
mod = dbs.mod()
mod.say_hello()

The rl() method is for convenience to reload your module without having to reload the console.

After making changes to your module:

dbs.rl() # reload module

Getting Started

Open Macro

Open the your macro up in VS Code Editor and set a break point.

A break point is set by left clicking on the in the code editor to the left of the line number.

Load Office Program

First start VS Browser. This can be done by click on VS Browser in the lower right corner of Vs Code.

The opened window will look something the following.

Next, click a button to open a LibreOffice Program, Writer in this case.

This will start the app in the browser window.

Note:

When running in Codespace (remote Development Container) the URL to connect to LibreOffice will be different.

To get Remote address:

Find the Forward address in the PORTS of VS Code. Copy the address that for port 3002 and paste it into the browser window.

Remote URL Connection.

Load Console

Load the console built into Live LibreOffice Python . In the terminal:

console

This will start a specially configure python console.

See Also: Console

Import

Import dbs from macro folder. This will prime the macro for debugging.

Remember the wait_for_client() call. When dbs is imported it will wait for VS Code to connect before continuing.

import debugpy

debugpy.listen(8550)
debugpy.wait_for_client()  # blocks execution until client is attached
# ...

Run the import line:

>>> from macro import dbs

Click the Run and Debug button in Vs Code.

Select the Macro Attach option.

Click the Start Debugging button or pres the F5 key.

This will attach Vs Code debugger to the dbs module.

The VS Code toolbar will pop up.

Debug Macro

Okay, now that the debugger is attached the macro can be invoked from the command line.

Get access to your macro module.

>>> mod = dbs.mod()

Remember in dbs.py we set:

from macro import ooodev_ex as my_macro

def mod():
    return my_macro

So mod will now be an instance of your macro module, ooodev_ex in this case. Alternatively we could just use from macro import ooodev_ex and use ooodev_ex instead of mod; However, now each time a change is made to the ooodev_ex module the console and debugging session would need to be restarted to pick up the changes.

By using the mod = dbs.mod() we can make changes without restarting the console and debugging session.

After changing you macro module call:

>>> dbs.rl()

This will re-import the module and your changes will be reflected.

Ending Session

To end the session type exit() in the terminal window. This will terminate the python session and stop Vs Code Debugging session.

Togging Debugger

The debugger can be turned on and off while the dbs script is running. To turn off debugging use Shift + F5 keys or the toolbar.

To turn on use F5 key.

Quick Start

Once the above steps have been taken set the debug configuration starting new sessions is quicker.

With LibreOffice running in browser.

• start console by typing console in the terminal
• run the import from macro import dbs
• Press the F5 key to instruct Code to attach to the debug instance.
• Import your module via mod = dbs.mod(), mod can be any var name of your choosing.

Debug console

After a break point has been hit you can use the debug console to interact with the code.

You can interact with the current state of code by typing in the debug console. The result above is from typing ft into the debug console when the code was run to line 44.

Trouble Shooting

If you see the following error:

RuntimeError: Can't listen for client connections: [Errno 98] Address in use

This usually means there is another console session running in the background.

The solution is, exit the current console

exit()

Running the jobs command will show other running jobs.

(libreoffice python template-py3.11) root ➜ /workspace/libreoffice_python_app (develop) 
$ jobs
[1]+  Stopped                 console

Run the fg command with the job number to enter back into the process. You may have to press enter after console appears to get back the >>> prompt. At the >>> prompt type exit(), this will end the session. Now starting a new session should work.

$ fg 1
console

>>> exit()

See Also

• Console
• Debug Macros in Terminal
• Linux Linking Paths for Development
• Guide on embedding python macros in a LibreOffice Document