18 Apr 2024

Crash fixes part 3 – Testing crashes

I have previously discussed fixing crashes in 2 parts (segfaults, aborts). Here I discuss testing crashes to avoid creating re-creating regressions.

Why testing crashes?

When you fix a crash, you have to make sure that it does not happen again in the future. The key to achieve such a goal is to write a suitable test. The test should do the exact steps to reproduce the problem on the program in order to detect the known crash before the new code is merged.

This can be done using either UITests, or CppUnitTests. UITests are written in Python. They are easier to write, but they do not run on each and every platform, and they are usually slower. CppUnitTests, on the other hand, are written in C++. They are much faster, and they run on every platform that CI runs to make sure that everything is built and can be run correctly.

An Example Crash Testing

Consider the below issue around footnotes:

This problem was happening when someone created a footnote, deleted the reference, and then hovered the mouse on the removed footnote reference. To reproduce that, one could use keyboard to generate a key sequence that repeats the required steps:

Write something, add footnote, select all the footnotes and remove them, then go back to the text, and hover the footnote reference.

Using keyboard-only is not always enough, but here it was possible. To implement the UITest, you should first find the appropriate place to put the test file, and then write a Python script for that. Here, the test was written in sw/qa/uitest/writer_tests2/deleteFootnotes.py. The UITest test can be found alongside the bug fix, in the class class tdf150457(UITestCase):

If you look into the code, the test_delete_footnotes() function consists of many invocations of postKeyEvent calls, that emulate key input events:

pTextDoc->postKeyEvent(LOK_KEYEVENT_KEYINPUT, 'a', 0);

To insert footnotes, UNO commands are used.

dispatchCommand(mxComponent, ".uno:InsertFootnote", {});

Just doing the same steps would be enough, as if the crash happens with the fix in place, or in a bad commit in the future, the test would fail. This test failure will prevent the same problem in the future.

The nice thing is that it turned out the same test could have been written using C++ and CppUnitTest, which is considered superior.

The new CppUnitTest can be found in the below change:

The new test resides in sw/qa/extras/uiwriter/uiwriter3.cxx, and essentially uses postKeyEvent and dispatchCommand as similar functions.

If you look at the current version of the test, you can see that it was simplified in later commits, but the idea is the same: “repeat the same steps that lead to crash in the code”.

Final Words

It is expected that every bug fix is accompanied with a test, to avoid seeing the same problem in the future. If you want to know more about UITests and CppUnitTests, please take a look at this TDF Wiki pages:

Also, keep in mind that looking into the existing tests is the best way to understand how to write a new test. Therefore, make sure that you look into qa/ folders of the modules when you want to add a new test.

18 Mar 2024

Test improvement – More and better tests for LibreOffice

One of the areas that can help LibreOffice, but may not directly be visible to the users even though it has a big impact is the quality assurance, is automated testing.  Here, I discuss some areas and notes around improving tests for LibreOffice. First, I start with regressions and bug fixes without a test.

Missing Unit Tests

This is the description from the GSoC ideas page:

While there are some automated tests for LibreOffice, there are not nearly enough. Adding more and better tests helps developers who work on the code to be more productive by allowing them to find regressions as early as possible.

To elaborate more, I should say there are many regressions and bugs in general that are fixed, but lack testing. It is important to have tests for those bug fixes, to avoid such problems in the future. You can see a list of those fixed issues that lack tests here:

If you want to add some new tests for the bug fixes, first you should read the bug report very carefully to understand what is it about, and try to test the fix yourself. You can either use git revert command to revert the fix, and see the problem in action, or try changing back the fix in the code, if it is not too big.

That is important, because you have to see that the test fails without the fix in place, but succeeds when it is applied. This is an essential step when writing the test.

To know more about unit tests, you may look into these Wiki pages:

Porting Existing Test to C++ or Python

Some tests are written in the past, but now have issues because of the way they are written. In this case, porting them can provide improvement.

Tests can be written in multiple languages. At least, C++, Python, Java and BASIC are currently in use for different tests across the LibreOffice code base. Again in the GSoC ideas page, you can read:

There is some support in LibreOffice for automated tests, both at the level of unit tests, and at the level of system tests that drive a full LibreOffice instance. Currently tests can be written in C++, Java, or Python. Various new automated tests should be developed to improve the test coverage.

Tests written exclusively for Java (e.g. the JUnit framework) should be ported to C++ so that they can execute much more rapidly. Similarly, tests that do remote control of an existing LibreOffice instance, should be re-factored to run inside that instance to make debugging much easier.

Almost all JUnitTests and UITests, and also some smoke tests, run as an outside process. To verify, the trick is to remove the soffice(.exe) binary, or to remove its execute permission (on Linux). In this way, out-of-process tests should fail, as they need to run the soffice binary. After a successful build, you can see if this works. For example, try this:

make -d JunitTest_framework_complex

As an example, we have this issue around complex tests that should be ported to Python:

You may find many examples of the previously ported test in the issue page. Keep in mind that usually old Java tests should be removed in the same patch that provides the CppUnitTest port.

Also, you may find examples of UITests ported to C++ from Python. For example, see this patch:

It ports a previously implemented UITest from Python to C++. The result is a faster test, which is more robust.

Focusing on a Specific Area

If you want to add or port some tests, please focus on a specific area of the code. The LibreOffice code base is huge, and consists of more than 200 modules. It is not easy, and in fact not suggested, to work across different applications and modules. It is much better that you pick a specific application, and even inside that application, like Writer, Calc, Impress, etc., focus on a specific module. In this way, it would be much easier to understand the ideas and the way tests are implemented.

How Hard is it to Write / Port a Test?

One important question is around the complexity of writing or porting tests. The answer is not straightforward, as it depends on the area that the test is written. But one can take a look at what others did in the past. By looking into Gerrit or git log, you can find what other people, including GSoC applicants, were able to achieve during their work.

After writing a few tests, or porting a few tests, it may become easier for you to write more tests. Another thing is that you don’t have to write tests from scratch. There are many tests available in the LibreOffice code base, and you can create your new test based on existing tests and customize it to match the purpose of the issue you are working on.

29 Feb 2024

Writer tables converted to plain text – difficultyInteresting EasyHack

If you copy contents from LibreOffice Writer to a plain text editor like gedit or Notepad, you will see that it does a straightforward thing: It copies the text and some basic formatting like converting bullets to ‘•’. For the Writer tables, the conversion is very simple right now: every cell is written in a separate line.

For example, if you have a table like this:

A | B
--|--
C | D

When you copy the table from LibreOffice Writer and paste it into a plain text editor, it will become something like this, which is not always desirable.

A
B
C
D

It is requested that like LibreOffice Calc, or Microsoft Word, and many other programs, the copy/paste mechanism should create a text like this:

A	B
C	D

The columns are separated by <tab>.

This feature request is filed in Bugzilla as tdf#144576:

Code pointers for Handling Writer tables

There are many steps in copy/pasting, including the data/format conversion and clipboard format handling. Here, you have to know that the document is converted to plain text via “text” filter.

The plaintext (ASCII) filter is located here in the LibreOffice core source code:

Therefore, to change the copy/paste output, you have to fix the ASCII filter. That would also provide the benefit that plain text export will be also fixed as requested here.

In this folder, there are a few files:

$ ls sw/source/filter/ascii/
ascatr.cxx parasc.cxx wrtasc.cxx wrtasc.hxx

To change the output, you have to edit this file:

In this file, there is a loop dedicated to create the output.

// Output all areas of the pam into the ASC file
do {
    bool bTstFly = true;
    ...
}

Inside this loop, the code iterates over the nodes inside the document structure, and extracts text from them. To check for yourself, add the one line below to the code, build LibreOffice, and then test. You will see that a * is appended before each node.

SwTextNode* pNd = m_pCurrentPam->GetPoint()->GetNode().GetTextNode();
if( pNd )
{
+   Strm().WriteUChar('*');
    ...
}

For example, having this table, with 1 blank paragraph up and down:

A | B
--|--
C | D

You will get this after copy/paste into a plain text editor:

*
*a
*b
*c
*d
*

To fix the bug, you have to differentiate between table cells and other nodes. Then, you should take care of the table columns and print tab between them.

To go further, you can only add star before table cells:

if( pNd )
{
    SwTableNode *pTableNd = pNd->FindTableNode();
+   if (pTableNd)
+   {
+       Strm().WriteUChar('*');
+    }
    ...
}

You can look into how other filters handled tables. For example, inside sw/source/filter/html/htmltab.cxx you will see how table is managed, first cell is tracked and appropriate functions to handle HTML table are called.

For the merged cells, the EasyHacker should first checks the behavior in other software, then design and implement the appropriate behavior.

Final Words

To gain a better understanding of the Writer document model / layout, please see this document:

This presentation is also very helpful to gain a good understanding of Writer development:

Introduction to Writer Development – LibreOffice 2023 Conference Workshop, Miklos Vajna

Please accept YouTube cookies to play this video. By accepting you will be accessing content from YouTube, a service provided by an external third party.

YouTube privacy policy

If you accept this notice, your choice will be saved and the page will refresh.

22 Feb 2024

Make Impress master slides copyable – difficulty interesting EasyHack

When working with LibreOffice Impress, “Slide Master” is the place where you can change the templates used for different types of the slides used in your presentation. Here we discuss a possible improvement for the “Slide Master” by making the copy from master slides possible.

Copying the Master Page in Impress

To see the problem and the room for enhancement, open LibreOffice Impress, then choose “View->Master->Slide Master” from the menus. Then, try to copy the master page on the left in the slide sorter. Unfortunately, it is not possible.

Impress slide master

Impress slide master

Having this feature is helpful, because different page types have many things in common, and being able to copy/paste helps creating templates much faster.

Impress Code Pointers

Looking into sd/source/core/drawdoc3.cxx, you can see a huge function SdDrawDocument::InsertBookmarkAsPage, which is relevant here. It contains ~600 lines of code. This huge function is in itself a problem. Therefore, to implement the enhancement, on should try to first refactor the function, then add a unit test in sd/qa/unit, find and then separate all the ~6 use cases, and fix the style/name merging.

After the cleanup, the main fix should be implemented. The suggested path to implement this comes from Jean-Francois. He suggest to improve the duplicate() method, which is described in the documentation:

As described in the above documentation, its role is to duplicate a page:

Creates a duplicate of a DrawPage or MasterPage, including the Shapes on that page and inserts it into the same model.

However, the implementation does not work for master slides, as the macros in the attachment file implies. The solution should add the needed implementation for master slides.

The implementation is inside sd/source/ui/unoidl/unomodel.cxx inside duplicate function:

// XDrawPageDuplicator
uno::Reference< drawing::XDrawPage > SAL_CALL SdXImpressDocument::duplicate( const uno::Reference< drawing::XDrawPage >& xPage )
{

...

}

Final Words

The above issue is filed as tdf#45617. If you like to work on it, just follow the Bugzilla link to see more information.

To implement this feature, first you have to build LibreOffice from the sources. If you have not done that yet, please refer to this guide first:

Getting Started (Video Tutorial)

4 Feb 2024

gbuild for Java tests – LibreOffice build system part 3

In this blog post, I discuss gbuild for Java tests. The goal is to write a Makefile to compile and run a JUnit test for LibreOffice. You can also refer to part 1 and part 2 for a brif overiew on gbuild, the LibreOffice build system.

Macro Examples from gbuild for Java Tests

In the first post on gbuild, I have mentioned some macro examples including gb_Output_announce which was used to print nice messages like the ones including “[CXX]”. Now let’s explain some more macros related to Java tests.

Consider that you want to compile and run a JUnitTest. To do that, you need to write the test in a Java file, and create a Makefile to run that.

This is an example for running a test defined in Java file sw/qa/complex/indeterminateState/CheckIndeterminateState.java.

$(eval $(call gb_JunitTest_JunitTest,sw_complex))

$(eval $(call gb_JunitTest_add_sourcefiles,sw_complex,\
sw/qa/complex/indeterminateState/CheckIndeterminateState \
))

$(eval $(call gb_JunitTest_use_unoapi_jars,sw_complex))

$(eval $(call gb_JunitTest_add_classes,sw_complex,\
complex.indeterminateState.CheckIndeterminateState \
))

The make file for running this Java test consists of calling multiple macros. It starts with gb_JunitTest_JunitTest macro, which defines the test by its name, sw_complex. This macro is defined in solenv/gbuild/JunitTest.mk. If you grep for define in the same file, you will see this result:

$ grep -w define solenv/gbuild/JunitTest.mk
define gb_JunitTest_JunitTest
define gb_JunitTest_set_defs
define gb_JunitTest_add_classes
define gb_JunitTest_add_class
define gb_JunitTest_add_sourcefile
define gb_JunitTest_add_sourcefiles
define gb_JunitTest_use_jar
define gb_JunitTest_use_jars
define gb_JunitTest_use_jar_classset
define gb_JunitTest_add_classpath
define gb_JunitTest_use_system_jar
define gb_JunitTest_use_system_jars
define gb_JunitTest_use_external
define gb_JunitTest_use_externals
define gb_JunitTest_use_customtarget
define gb_JunitTest_use_customtargets
define gb_JunitTest_use_unoapi_jars
define gb_JunitTest_use_unoapi_test_class
define gb_JunitTest_set_unoapi_test_defaults
define gb_JunitTest_JunitTest

To stick to the macros used in the above example, I describe these macros:

gb_JunitTest_add_sourcefiles: This macro adds a Java source file to the test. It defines the code that adds the sw/qa/complex/indeterminateState/CheckIndeterminateState.java to the test. But please note that you should drop the .java extension:

$(eval $(call gb_JunitTest_add_sourcefiles,sw_complex,\
sw/qa/complex/indeterminateState/CheckIndeterminateState \
))

The other macro gb_JunitTest_use_unoapi_jars, adds the UNO API JAR files to be used with the test.

And in the end, you need to add the test class name using gb_JunitTest_add_classes macro. The class name is visible in the end.

The result can be quite complex, but it works. 🙂

java.exe -Xmx64M -classpath "$W/JavaClassSet/JunitTest/sw_complex;C:/cygwin64/home/user/lode/opt/share/java/junit.jar;$I/program;$W/Jar/OOoRunner.jar;$I/program/classes/libreoffice.jar;$W/Jar/test.jar" -Dorg.openoffice.test.arg.soffice="path:$I/program/soffice" -Dorg.openoffice.test.arg.env=PATH="$PATH" -Dorg.openoffice.test.arg.user=file:///$W/JunitTest/sw_complex/user org.junit.runner.JUnitCore complex.indeterminateState.CheckIndeterminateState

The above is the actual command that runs the test. Please note that if you forget the gb_JunitTest_add_classes macro to define the class name, the test may compile, but it will not run.

As an example, you can see the below patch. This patch fixes the problem of the JUnit test not running:

Final Words

Many macros are available in gbuild, making easier to create Makefiles to compile and run tests, build libraries and executable applications and many other relevant tasks. The best way to find and understand these macros is to look at the Makefiles written by others to the same task. Look for .mk files, and if you want to see the implementation of the macros, look into solenv/gbuild/.

I will write more about gbuild macros in the next series of blog posts on gbuild.

25 Jan 2024

gbuild tips and tricks – LibreOffice build system part 2

In the first blog post on LibreOffice build system, gbuild which uses GNU Make, I discussed some of the features of it. Here I discuss more about some gbuild tips and tricks that you may need.

Building a Single Module

In order to build a single module, you need to use its name. For example, to build only “odk”, which contains office development kit, you only have to type:

make odk

On the other hand, there are many other build targets associated with odk. By typing make odk, and then pressing tab, you will see this list, which shows possible targets:

odk odk.buildall odk.perfcheck odk.uicheck odk.all odk.check odk.screenshot odk.unitcheck odk.allbuild odk.checkall odk.showdeliverables odk.allcheck odk.clean odk.slowcheck odk.build odk.coverage odk.subsequentcheck

Each of the above is related to a specific task, in which many of them are common on different modules. Let’s discuss some of them:

make odk -> Builds odk module.

make odk.clean -> Cleans the odk module, removing the generated files.

make odk.check -> Runs test in odk module

make odk.uicheck -> It runs UI tests inside odk module

make odk.perfchek -> Runs performance/callgrind tests inside odk module

make odk.screenshot -> Creates screenshots inside odk module

To get a complete list and detailed description, run make help.

Handling Incomplete Builds

Sometimes because of OS crash or power outage, you may face problems when a build is stopped forcefully. In that case, you may see several zero byte object (*.o) files that exist, and prevent a successful build. In that case, you can find and remove them using this command:

$ rm `find -name *.o -size 0`

After that, you can retry your build without the above problem.

Customizing Build Configuration

The process of creating Makefile starts from configuring LibreOffice for build. This is done by invoking ./autogen.sh. The configuration parameters are read from autogen.input. The build configuration is done via configure.ac, which is an input for GNU autoconf.

There are various steps before the Makefiles are generated. For example, in order to make sure that a library is there when configuring the build, a very small C/C++ file is created, compiled and tested to ensure that the library is ready, and available to use with C/C++ code.

It is also possible to check for some specific version of library, and available functions. As an example, see this patch, which checks for specific version of ZXing library:

In the above example, multiple situations are handled:

1) When there is no ZXing library

2) When system ZXing library is used

And also, it is checked that specific version of ZXing is available:

1) When ZXing::ToSVG is not usable

2) When ZXing::ToSVG is usable

Then, the HAVE_ZXING_TOSVG symbolic constant is used in config_host/config_zxing.h.in, which can be used in C++ code.

Knowing More About gbuild

If you are interested in knowing more about gbuild, you can start from my first post on gbuild in this blog. I plan to write more about gbuild, and describe some of the frequently used macros.

Also, you can take a look at the article devoted to gbuild in the TDF Wiki:

3 Jan 2024

Outlook for the new year 2024

Now that year 2024 has come, I want to briefly discuss the year 2023 around the development blog, and the outlook for 2024 here.

My goal is to help people understand LibreOffice code better, and ultimately get involved in LibreOffice core development to make LibreOffice better for everyone. In 2023, I wrote 23 posts around LibreOffice development in the dev blog (3 of them are unpublished drafts).

At The Document Foundation (TDF), our aim is to improve LibreOffice, the leading free/open source office software that you and many other people around the world use. Our work is community-driven, and we need your help.

LibreOffice conference 2023

LibreOffice conference 2023

Outlook For the New Year

My focus for 2024 in this blog will be:

  1. Introducing new EasyHacks
  2. Discussing how to fix crashes
  3. Explaining LibreOffice architecture
  4. Describing user interface creation with VCL
  5. Explaining LibreOffice extensions

You can give feedback by writing a comment here, or sending an email to hossein AT libreoffice DOT org.

I provide mentoring support to those who want to start LibreOffice development. You are welcome to contact me if you need help to build LibreOffice and do some EasyHacks via the above email address.

I hope the best for you in the new year 2024.

21 Dec 2023

Custom string literals: two EasyHacks

In the previous part of the series on C/C++ strings, I described the string literal, plus how and why to use them. Then I introduced the new custom string literals and their benefits: (more…)

14 Dec 2023

LibreOffice extensions with Python – part 2: Debugging

In my previous blog post on creating LibreOffice extensions with Python, I have discussed how to write a Python code that works with LibreOffice API, and can be run and debugged in an IDE, and packed later in an extension. Now I discuss how to debug the Python code. (more…)

25 Nov 2023

LibreOffice extensions with Python – part 1

Ever wondered how to create a LibreOffice extension? Here I discuss how to do that via Python programming language. It is possible to run and debug the resulting Python code in an IDE, and then package the content as an extension. (more…)