Things to know if you are a new contributor to LibreOffice code

When I began contributing code to LibreOffice, I faced some issues because I didn't know several facts that the other active contributors knew. This blog post summarizes some of those facts, and I hope it will be useful for other new contributors!

1) The data types LibreOffice code uses -
If you have already browsed through the codebase of LibreOffice, you might have realized that the code doesn't generally use data types like int, float, double, et cetera like we use in small C++ programs. LibreOffice has its own classes, typedefs and structs defined and most of the code use them instead of the trivial data types. Some of those are OUString (instead of string), sal_uInt32 (instead of unsigned int), etc.

2) The CI infrastructure - 
As soon as you send a patch to Gerrit, Jenkins starts to build LibreOffice from your code on several platforms to check whether or not the change you made compiles successfully. Not only that, but it also runs the built software against several test cases and also checks whether or not your code is properly formatted. You are expected to check the output of Jenkins and fix any error it shows. But here's the catch - many of the tests LibreOffice has are flaky - which means the tests might fail even when it isn't your fault. You have to carefully examine the output of Jenkins, and if the error produced is irrelevant to your change, you simply have to rebase your change on the latest commit (which can be done using the Gerrit UI), and wait for Jenkins to build your code again.

3) The directory structure -
Though the presence of a large number of files in the LibreOffice core project might make it difficult for you to search for a particular code, having a knowledge of how the directories are structured might be helpful for you. The following are some important points-
  • Almost all directories have a README file which gives a bit of introduction of what kind of code the directory contains.
  • Many directories have a subdirectory named qa. QA stands for quality assurance and they contain the tests for the code implemented in the same directory.
  • Many directories have a subdirectory named include/inc. These folders contain header files.
  • Many directories have a subdirectory named source. This is the main source code of the directory the README file talks about.
4) The variable prefixing system -
If the file you are working with uses some letters as prefixes in the names of local variables, it'd be great if you use the same prefixes in the patch you send. The prefixes generally denote the data type of the variable. The meaning of some of the prefixes are listed below-


Prefix Meaning
b Boolean
p Pointer
r Reference
n Integer/Numeric Type
c Character
a Anything else

Comments

  1. Mike KaganskiMarch 21, 2019 at 10:51 PM

    Hi! Nice post; great that you share your knowledge.

    Some nitpicks:
    1. double is actually the main floating-point type used in the codebase;
    2. When your CI job has errored out, it's better to ask others on IRC to resume, than immediately rebase; that's because some platforms that succeeded would not be re-tested when resumed, but will be if rebased - thus resuming helps reducing overall load to CI infrastructure.
    3. The code conventions documentation is mentioned at https://wiki.documentfoundation.org/Development; there are also type prefixes like x (for interfaces), e (for enums); and also the other class of prefixes identifying if it's a member (m_), a static (s_).

    ReplyDelete
  2. Cor & OfficeBuzzApril 17, 2024 at 9:12 AM

    Searching for a tip on Jenkins failing, I found your post. Thanks :)

    ReplyDelete

Post a Comment

Popular posts from this blog

An overview of how UI logging works in LibreOffice

Logging in LibreOffice is mainly handled by a class called UITestLogger, defined here . The logger class logs the user actions only if the member flag mbValid is set to true. The flag can be turned on by setting the environment variable LO_COLLECT_UIINFO to a file name where the logs should be collected (see the constructor of UITestLogger, defined here ). We maintain a pointer to an instance of UITestLogger class here . To use the logger object, the static function getInstance can be used to get access to the pointer. The function logAction, defined in the same class, is used to log events from the classes which extend the class vcl::Control. The log statements corresponding to a particular class can be found in the function get_action of the UI wrapper classes. Most of the wrapper classes can be found with this OpenGrok search. The log statements get generated when VCL events get broadcasted. A list of the VCL events can be found in the enum class VclEventId here . ...
Read more

GSoC final report - UI logger

Overview The idea of this GSoC project was to implement a feature which logs the interaction of users with the UI elements in an interpretable Domain Specific Language (DSL), and an interpreter which converts the log into a file into something which will help in replaying the user actions. The project involved working with the UI elements and the UI testing framework of LibreOffice. Achievements The logger - The logging for the following is currently supported - The UI elements of Visual Component Library like Buttons, Checkboxes, Radio-buttons, Listboxes, Comboboxes, Spinbuttons, etc. Keys pressed in different UI elements UNO commands sent with parameters Selection of Objects Opening of Sidebar/Deck Some application-specific events can also be logged - Writer - Goto Page, Set Zoom, Text Selection Calc - Autofilter Launch, Selection of cells/range of cells, Switching of Sheet Math - Selection of elements from the element selector panel Impress - Set Zoom Addi...
Read more