LibreOffice Developer Guide

How to get started with LibreOffice Development

Introduction

LibreOffice is a huge product, and can be a intimidating at first. Although the code is complex — with many modules and many layers — one area in which the project has made very noticeable efforts is ease of build. Nowadays building LibreOffice is a pretty straightforward task, and follow pretty much the standard auto-tools way.

This Document is an introduction to LibreOffice development. It is not meant to teach you the intricacies of the code, sctructure, design — and sometime apparent lack thereof — but to guide you in setting up a build environment, and introduce you to the different elements, tools, services that are involved in a typical development work-flow in the project. We are going to assume no prior knowledge of LibreOffice, The Document Foundation, or the communities around it. We are going to assume a basic working knowledge of a POSIX system, the ability to work in a shell environment and the familiarity with your text editor of choice.

Setting-up a build environment

In the course of setting-up a Continuous Integration (CI) system for LibreOffice, and in order to manage the installation and maintenance of dozen of machines dedicated to building LibreOffice, we had to emphasis regularity and automation in the setup of these machines. Although there are many way to setup and customize a build environment for LibreOffice, we will present here a setup based on what we use for CI. We strongly urge you to stick to the plan initially, until you are able to do builds regularly and gain an understanding of what is involved. After that you are of course free to deviate in any way you want, if some of the convention we choose irritate you.

Pre-Requisites per Platform

Each platform has its own set of pre-requisites. The platform covered in this documents are Linux, Mac OSX 10.8+, Windows 8+.

Pre-requisites for Linux

TBD.

Pre-requisites for Mac OSX

Mac OSX is actually one of the easiest platform to setup for. The main cause of trouble is the interaction of external system like MacPort or Brew.

When building LibreOffice or setting up the LibreOffice Development Environment (lode), if you have MacPort or Brew or another similar system installed, make sure to modify you session PATH so that none of these are visible. A typical PATH should look initially like :
PATH=/usr/bin:/bin:/usr/sbin:/sbin:/usr/local/git/bin
In the case of MacPort, for instance, you want to make sure that type -p port return nothing.

Disk Space

You will need enough disk space. Beyond that is required to install XCode and a JDK, you should count about 10GB for a Release build and 25GB for a debug build

XCode

You need to install XCode. It is available for free in the App Store. Once installed you need to agree to the license:

$> sudo xcodebuild -license

Read the license and follow the instructions. Then you need to install the command-line tools associated with XCode:

$> sudo xcode-select --install

JDK

You need to install a JDK. You can google for it. You want the JDK, not the JRE or something else. The most current version should be fine.

You may need to tweak the file Info.plist of the JDK. It should be located at /Library/Java/JavaVirtualMachines/jdk1.8.0_{version}.jdk/Contents. Locate the section in Info.plist:

    <key>JVMCapabilities</key>
    <array>

Make sure it contains entries for JNI and BundledApp:

    <key>JVMCapabilities</key>
    <array>
    <string>CommandLine</string>
    <string>JNI</string>
    <string>BundledApp</string>
    </array>

Pre-requisites for Windows

We typically build on Windows 2012R2, but Windows 2008R2 and Windows 8+ are known to works also.

Visual Studio

You need Visual Studio 2013 Community Edition or Pro.

JDK

You need to install a JDK. You can google for it. You want the JDK, not the JRE or something else. The most current version should be fine. If your Windows is 64 bits capable, you can build LibreOffice in 64 bits mode. In that case you need the 64 bits JDK. It is simpler to install both the 64 bits and the 32 bits JDK up front.

Cygwin

In order to build LibreOffice on Windows you need Cygwin. The PowerShell script below will install cygwin for you with all the packages needed for a LibreOffice build. To use the scrip, create a directory, for example c:\cyginstall and copy the script below in a file install_cygwin.ps1 in that directory. Note that the script install the 64 bits version of cygwin if your system is 64 bits. and it install things in C:\cygwin by default. If you want cygwin to be installed somewhere else, change the content of the variable $root in the script, to point to the desired cygwin location. For example if you want it on a D: drive set $root = "D:\cygwin".

$lode = $pwd
$temp = "$lode\packages\temp"
$root = "C:\cygwin"
$site = "http://mirrors.kernel.org/sourceware/cygwin/"
if(!(Test-Path -Path $lode\packages ))
{
    New-Item -ItemType directory -Path $lode\packages
}
if(!(Test-Path -Path $lode\packages\temp ))
{
    New-Item -ItemType directory -Path $lode\packages\temp
}

if([environment]::Is64BitOperatingSystem)
{
    $setup = "$lode\packages\setup-x86_64.exe"
    $url = "https://cygwin.com/setup-x86_64.exe"
}
else
{
    $setup = "$lode\packages\setup-x86.exe"
    $url = "https://cygwin.com/setup-x86.exe"
}

if(!(Test-Path -Path $setup ))
{
    $webclient = New-Object System.Net.WebClient
    $webclient.DownloadFile($url,$setup)
}

start $setup  "-B -n -N -q -d -D -L -X -s $site -l $temp -R $root" -Wait

$packages = @"
 -P autoconf,automake,bison,cabextract,doxygen,flex,gcc-g++
 -P git,gnupg,gperf,libxml2-devel,libpng12-devel,make,mintty
 -P openssh,openssl,patch,perl,pkg-config,python,python3
 -P readline,rsync,unzip,emacs,wget,zip,perl-Archive-Zip
"@

start $setup  "-B -N -n -q -d -D -L -X -s $site -l $temp -R $root $packages" -Wait

start "$root/Cygwin.bat"

To run the script, open a PowerShell session, change the directory to where you saved the script — D:\cyginstall if you followed the instruction above— and run it with ./install_cygwin.ps1. It is possible that the permission on you machine prevent you from executing a PowerShell script. See Microsoft docs about it.

After the scrip has ran, you should have a cygwin shell windows opened and ready.

Installing lode

The LibreOffice Development Environment (lode) is a small project used to setup a fairly uniform build environment. It help setup the necessary extra tools — like an appropriate version of gmake — needed to build LibreOffice.

From now on, for simplicity, we will assume that you are working in the HOME directory of a user called tdf. Of course you can install lode where-ever you want, in your own user home directory or really anywhere else you see fit. Under Windows that anywhere else is restricted to somewhere in the cygwin root space, and on any platform it is strongly advised not to have any whitespace or similar fancy character that are likely to trip bash.

First we need to clone the lode git repository:

$> cd /home/tdf
$> git clone git://gerrit.libreoffice.org/lode

Next we setup lode itself. This will download other git repos, establish a mirror of core.git, install some tools locally in ~/lode/opt/bin. In general, whenever you are running a command that can produce a lot of output, always add at the end of the command: 2>&1 | tee build.log. That will save a copy of what come on your screen in a file build.log, which can be handy if something goes wrong and you need to dig out what, which may not be on your screen anymore, or even not in the screen buffer if you have one. This will be also invaluable, if there is a problem, to help us diagnose it.

$> cd lode
$> ./setup --dev 2>&1 | tee build.log

The setup should end up with 'Done.'. after that you need to add the definition of LODE_HOME in you profile. Typically edit your ~/.bashrc and add:

export LODE_HOME="$HOME/lode"
export PATH="$LODE_HOME/opt/bin:$PATH"

You need to exit you shell session and restart it for these changes to take effect. At this point you now have a directory $LODE_HOME/dev/core that contains a checkout of the core repo of LibreOffice, with configure options to do a vanilla debug build.

Configure the build with autogen.sh

LibreOffice build system uses a little script called autogen.sh to configure the LibreOffice build. Although it is possible to pass a bunch of argument directly to that script, the most common practice is to use a feature of this script, which is. if there is not argument given to it, it will look for a file named autogen.input If that file exist it will use it to determine the arguments used to configure the build. autogen.input is a regular text file with one argument per line. By default lode generated one for you that looks like:

--enable-debug

Which will use all the default for your platform, except that it will build a Debug build. Empty lines are allowed (and ignored) in autogen.input and line that start with # are also ignored. Here is an example of a more complex autogen.input (for illustration purpose only, not to cut-and-paste as a model).

--enable-epm
--enable-scripting-beanshell
--enable-scripting-javascript
--enable-ext-nlpsolver
--enable-extension-integration
--enable-online-update
--without-system-postgresql
--disable-gtk
#build the help, this will pull the help.git repo as as git submodule
--with-help
--with-myspell-dicts
--with-package-format=dmg

For now, just stick with the default build, once that is successful you'll have plenty of occasion to try exotic combinations, which may or may not work. There is 300+ flags that one can tweak in the configuration, that is more than 10^90 possible variations. which is a billions time greater than the estimated number of atoms in the universe... Sorry we do not have a system to test all possible combinations of these flags.

So, now let configure the build:

$> cd dev/core
$> ./autogen.sh 2>&1 | tee build.log

Building

Read carefully the messages at the end of the configuration, as they may indicate some potential problems. If things looks ok, then you can build it:

$> make 2>&1 | tee build.log

The first time you do a build, it will have to download from the internet few hundreds of MB of external libraries source packages. The actually build start after that. For an initial full build, count very roughly about 18 / (nb cores x frequency in GHz) hours.

To Be Continued...