LibreOffice Development Howto

LibreOffice Development Howto

Questions about LibreOffice development efforts or how to implement specific improvements are among the most frequent requests we see at Lanedo. As a result, this LibreOffice development howto summarizes steps and tips to allow everyone interested to easily get involved.

With over 7 million lines of largely C++ code, contributing to the LibreOffice code base can seem like a daunting prospect. In spite of this, I would highly recommend it as an introduction to open source projects and as an educational tool. Much work has been carried out in the last three years to not only improve user-facing features and fix bugs, but also to make life easier for developers.

Getting Started

First of all, it is important to get a working build of LibreOffice on your system. Assuming a Linux-based setup, it’s relatively easy to compile. It will, however, take some time. There are detailed build instructions on the Document Foundation wiki:
Building on Linux
Building on Windows
Building on Mac OS

From here, the directory used by git to manage LibreOffice will be referred to as [lo-root]. Once a developer install has been successfully built, you can run the result from [lo-root]/install/program:
$ . ./ooenv
$ ./soffice.bin

Choosing a Problem

There are several ways to select something to work on.

The first is to find an issue that you experience yourself as a user of the product. This is probably the best way of breaking into any open source project as it’s easier to stay motivated when working on your own problems.

The second is to find an issue on the LibreOffice bugzilla. Ensure you choose LibreOffice as the product and filter the results as you see fit. You can also browse bugs under the Easy Hacks program. This is a fantastic way of finding bugs that have been deemed good introductory problems and they generally come with some advice and code pointers from the developers.

Finding the Code

The hardest part about working with a gigantic code base is knowing where to start. LibreOffice is conveniently partitioned into modules which contain (more or less) logical groupings of code. Each module is a subdirectory under [lo-root] and contains its own README file – these provide useful guidelines as to what to expect in each module. These can be viewed at a glance at http://docs.libreoffice.org/ – from there, each module has links to cgit, which provides online browsing of the git repository, and Doxygen documentation.

However, this is not generally specific enough to find the exact point at which the problem lies. This is where OpenGrok for LibreOffice comes in useful. This allows you to very quickly search the code for a specific phrase. The key is to find some text near the feature you want to fix. For example, to find code relating to the Word Count window you could use the text “Characters excluding spaces”. For this quoted phrase, OpenGrok gives us two results – statisticsinfopage.ui and wordcount.ui, both in the [lo-root]/sw (Writer) module. Reading through wordcount.ui, we can see that the label for the number of words in the current selection is referred to as “selectwords”. Using this term in OpenGrok then leads us to [lo-root]/sw/source/ui/dialog/wordcountdialog.cxx.

Another useful tool is Unix stalwart grep. Although it’s generally too slow to do a complete search of the code base, it is useful once you have narrowed down the possibilities to a module or two using OpenGrok.

Finally, the LibreOffice developer mailing list (archive) and IRC channel (#libreoffice-dev at freenode) are great places to find a developer who has worked on code relating to your problem before and can give you some code pointers to start from.

Exploring Code in Depth

Sometimes searching the code base doesn’t quite cut it when attempting to solve a problem. In these cases, a debugger can be used to explore the code as it is being run. To use gdb to do this, you must first configure the build before compiling it:
$ ./autogen.sh --enable-debug
$ make
$ make dev-install

There are several ways of running LibreOffice through gdb, but the easiest is probably:
$ cd [lo-root]/install/program
$ . ./ooenv
$ gdb ./soffice.bin
(gdb) run

A gdb primer is out of the scope of this post but a decent gdb cheatsheet can be found here. Once a rough code pointer has been found, a breakpoint can be set using the qualified name of the function or a full line specification. For example, breaking when a text node is being constructed can be done with either of these commands:
(gdb) break SwTxtNode::SwTxtNode
(gdb) break [full-path-to-lo-root]/sw/source/code/txtnode/ndtxt.cxx:196

For information on the current position in the code you can use the following to get your position in the stack, get a list of the ten lines surrounding the current one or print the value of any variable in scope:
(gdb) backtrace
(gdb) list
(gdb) print [var-name]

There are also several useful commands for moving around the code. You can step into function calls, move past them or continue to the next breakpoint using:
(gdb) step
(gdb) next
(gdb) continue

With strategic placement of breakpoints, it is then possible to narrow down where in the code the problem is occurring.

Making Changes

Once you’ve made some changes, you can recompile the module you’ve changed, avoiding a full re-make:
$ make [module-name]

If applicable, a unit test is a useful way for the core developers to see what changes you have made as well as to prevent regressions relating to your changes. Tests use the UNO API to load and manipulate documents as well as mimic user interactions. The easiest way to learn how to construct unit tests is to check out the existing examples. For example, tests for native file format (.odf) import can be found in [lo-root]/sw/qa/extras/odfimport/.

To submit your changes back to the community, you can use gerrit. Full instructions on submitting patches using this system can be found on the TDF wiki gerrit page.

Other Resources

Here is a list of recommended further readings on LibreOffice development:
TDF wiki development hub
Useful structural information on LibreOffice from Michael Meeks
Debugging LibreOffice

Do you need more help getting started with development on the code base? Still have a hard time to find your ways into LibreOffice? Let us know in the comments, we’re more than happy to help!

Share on Google+Tweet about this on TwitterShare on LinkedInShare on FacebookFlattr the authorBuffer this pageShare on RedditDigg thisPin on PinterestShare on StumbleUponShare on TumblrEmail this to someone

Eilidh McAdam is a programmer from Scotland who works on open source project LibreOffice. She also enjoys coding for fun, reading, music and writing. Eilidh got involved with the open source community through the Google Summer of Code program several years ago (libvisio – reading .vsd files produced by Microsoft Visio and importing them into LibreOffice Draw). Eilidh enjoys learning new languages and paradigms. You can contact Eilidh and her team for professional consulting on our contact page.

Tagged with: , , , , ,
Posted in Blog, LibreOffice

Leave a Reply

Your email address will not be published. Required fields are marked *

*

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>