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

16 Nov 2023

String literals: C/C++ string data types part 2

In the first part of the series on string types in LibreOffice, I discussed some of the string data types that are in use in various places of the LibreOffice code. I discussed various character and string data types briefly: OString, OUString, char/char*, sal_Unicode, sal_Unicode*, rtl_String, rtl_uString and also std::string. Now I want to explain string literals. (more…)

2 Nov 2023

Integer data types improvement – EasyHack

Many different data types are used in LibreOffice code. During the long history of the LibreOffice, and before that in OpenOffice, there were integer data types that are no longer in use today. The task I discuss here is to choose appropriate data types to use instead of sal_uLong and similar deprecated integer data types. (more…)

26 Oct 2023

UNO API error reporting improvement – EasyHack

In this blog post, I discuss the EayHack for improving UNO API error reporting. EasyHacks are good if you want to become familiar with LibreOffice programming, and this specific task is a good choice for beginners as it is a difficultyBeginner task. (more…)

5 Oct 2023

LibreOffice conference 2023 workshop presentation slides

LibreOffice conference (LibOCon) 2023 was held in Bucharest from 20 to 23 September 2023. Among the other programs, an important part was the workshop “Introduction to LibreOffice Development”. Here you will find the slides for the presentations. (more…)