How To Build LibreOffice

From The Document Foundation Wiki
< Development
Revision as of 2012-07-05T10:09:07 by Mst (Talk | contribs) (add more details to ccache configuration)

Jump to: navigation, search

Warning: Display title "How To Build LibreOffice" overrides earlier display title "".

This page documents how to build the current development version of LibreOffice, based on a git repository named 'core'; how to build older versions, such as releases 3.3 and 3.4, is documented here.

Preparation

Dependencies

The first step is to make sure that you have all the dependencies needed for your platform to build the product. There are pages that details what they are and how to install them for Windows, Linux, and MacOS.

Disk Space

At minimum, with all the git repositories, and the product build and packaged, you will need anywhere from 7 to 10 GB of disk space, depending on the platform, the build options and the specific autogen options you use, few Gb more if you make a debug build.

Bear in mind that if you want to do more than just building the product once for your own enjoyment, you most likely will want to have more than one working directory (we will see later how to set them up). A workdir allow you to have a separate build environment without having to duplicate the git history, but it will still cost you 6 to 9 Gb per workdir.

Getting the sources

In the rest of this tutorial we will work in ~/git. Of course you are free to choose which ever directory you want as a starting point. Now let's download the 'core' git repository:

$ mkdir git
$ cd git
$ git clone git://anongit.freedesktop.org/libreoffice/core libo
Cloning into libo...
Remote: Counting objects: 76845, done.
remote: Compressing objects: 100% (17328/17328), done.
remote: Total 76845 (delta 60786), reused 74045 (delta 58579)
Receiving objects: 100% (76845/76845), 15.82 MiB | 1.17 MiB/s, done.
Resolving deltas: 100% (60786/60786), done.
$ cd libo

Note 1: If you have ssh access, you might want to clone with this command:

$ git clone ssh://<<username>>@git.freedesktop.org/git/libreoffice/core libo

Note 2: Depending on your location, time of the day, phase of the moon etc., cloning all git repositories might be slow, or even failing after a while. For that case, we provide weekly-updated tarballs of the repositories. If you hit problems with the howto above, download the the following shell script: libo_git_from_tar.sh and run, for example:

$ mkdir git
$ ./libo_git_from_tar.sh -d ./git/libo

Please run ./libo_git_from_tar.sh --help for more information on how to use it

Checking out the 3.5 release branch

By default git will give you the 'master' branch for a new clone. If you want change your working copy to a release branch, first do this (before running 'autogen.sh'):

$ git checkout -b libreoffice-3-5 origin/libreoffice-3-5

After you have cloned the other repositories (see 'make fetch' below), do this to switch them to the release branch as well:

$ ./g checkout -b libreoffice-3-5 origin/libreoffice-3-5

Performance

Building LibreOffice takes time, a lot of time. Exactly how much depends on how powerful your machine is. But there are tools you can use to speed-up things.

ccache

ccache is a tool that caches the results of c/c++ compilation to try to re-use them later. It will not speed-up your initial build (on the contrary it will slow it down a bit), but it can dramatically speed up later re-building. If you plan to do some hacking in LibreOffice, you will do that a lot, so it is a worthy tool to have.

By default, ccache will be enabled automatically if it is found on your system. For best results, you may want to increase the cache size or enable cache compression; `man ccache` is your friend.

Note that the default cache size is just 1G which is far too small to be useful for a LibreOffice build; for a build without debug symbols, you should have at least 8G cache, and for a build with debug symbols for everything probably 32G is a useful starting point. You can set the size like this (note that this setting is stored inside the cache directory, if you change the location by setting $CCACHE_DIR you have to re-do it):

ccache --max-size 32G

ccache also supports compression, which is very likely a good idea to enable (does anybody have hard numbers?), especially if you are using a small or slow storage medium, like a SSD or laptop hard disk. You can enable compression by adding this to your .bashrc or equivalent:

export CCACHE_COMPRESS=1

distcc / Icecream

If you are in an environment where you have access to multiple machines with spare cpu cycles, you can take a look at distcc or icecream, tools for distributed build.

Support for Icecream is built into LibreOffice, it is enough to add --enable-icecream to ./autogen.sh, and the configure process will pre-set number of jobs to use, and will try to find the icecream gcc wrappers in /opt/icecream/bin. Should you have them somewhere else, please use --with-gcc-home=/path/to/your/icecream/bin switch to override that.

--with-max-jobs / --with-num-cpus

The build process can be told to run multiple tasks in parallel. The overall parallelism is controlled by the autogen parameter --with-max-jobs and the parallelism within a sub-task is controlled by --with-num-cpus. If you have enough memory, I found that using --with-max-jobs=n --with-num-cpus=n where n is your number of cores, or 2 for --with-max-jobs if you have only 1 core, give me the fastest build time.

--with-max-jobs defaults to 1, and --with-num-cpus defaults to the the number of cores/cpus on your system. Note that their net effect is multiplicative, there can be up to their product of simultaneous work (compiler) processes.

Compiler flags

Certain compiler flags, most notably optimizations and debug information, enable additional compiler features, which make the build take longer time. If you do not need these features and want the build as fast as possible, you can explicitly disable them by setting CFLAGS/CXXFLAGS for gcc when running make:

$ CFLAGS='-O0 -g0' CXXFLAGS='-O0 -g0' make

Note that for development you generally want the build configured with at least --enable-symbols, which turns on debug information, so this is not generally applicable.

Approximate times

An Athlon 435 X3 with ccache without java without epm takes about 1.5 hours for the initial make on gentoo.

The first build, on an Intel 2630QM with ccache without java and epm with --with-max-jobs/--with-num-cpus at 8 and ext4 formatted disk takes about 1,5 h too on Kubuntu. The following daily build time varies between 2 and 10 min (depending on the number of modified or added files and their complexity).

Autogen

Now you need to configure your build. This is done by running a script named 'autogen.sh'. There are many options that can be given to that scripts, you can get a list of them by running

$ ./autogen.sh --help
'configure' configures LibreOffice 3.3 to adapt to many kinds of systems.
 
Usage: ./configure [OPTION]... [VAR=VALUE]...
 
To assign environment variables (e.g., CC, CFLAGS...), specify them as
VAR=VALUE.  See below for descriptions of some of the useful variables.
 
Defaults for the options are specified in brackets.
 
Configuration:
  -h, --help              display this help and exit
      --help=short        display options specific to this package
      --help=recursive    display the short help of all the included packages
[....]

You mileage may vary, depending on your platform and distribution. To get us going here is the autogen I use for linux

$ ./autogen.sh --with-num-cpus=6 --with-max-jobs=6 --without-junit

and for MacOS

$ ./autogen.sh --with-max-jobs=8 --with-num-cpus=8

and for a build without any external repositories (only core)

$ ./autogen.sh --without-help --without-myspell-dicts

Please refer to this page for more detailed descriptions of build configuration options.

Parameters to autogen.sh to fix common problems

--disable-epm This will fix "rpm not found", as autogen expects to find either dpkg or rpm on the system.

--without-java This will fix "ant not found"

As of the master towards LibreOffice 3.6, to build the UNO SDK you need to have Doxygen installed so that HTML documentation for the C++ UNO interface can be generated. One option is to install Doxygen from its website and make sure the doxygen executable is found on the PATH, or specify its exact location via --with-doxygen=pathname configure switch. Another option is to configure --without-doxygen, in which case the HTML documentation for the C++ UNO interface will be missing from the UNO SDK being built. A third option is to configure --disable-odk, in which case the UNO SDK is not build at all.

Note: Installing 'libgnomevfs2-dev' package on Ubuntu manually will fix "No package 'gnome-vfs-2.0' found". Use synaptic package manager or run in terminal

$ sudo apt-get install libgnomevfs2-dev

Fetch

The first time only, run

$ make fetch

This will download the other git repos and needed tar.gz packages. Note that make will do this step anyways if you don't do it manually, but doing a make fetch the first time allow you to monitor the download activity.

Building

First Build

The first time make is invoked, it will download the other git repository needed (if any) and other external packages to be downloaded.

Building the product can take 8/number_cores hours on a reasonably recent processor, and much more on Windows.

$ make 2>&1 | tee build.log

Note that in the command above, a simple 'make' would have been sufficient. The rest of the command is to save all the output of the make into a file (build.log), so that you can go back to it later to investigate if needed.

( With a fresh git clone, download and corresponding make might take some time. To avoid accidental killing of the process, one can do a nohup make as below )

$ nohup make & 
nohup: ignoring input and appending output to `nohup.out
$ tail -f nohup.out

If your build fails, check that you have satisfied the dependencies mentioned at the top of this page.

Start what you have built

To run the LibreOffice you have just built, do

$ make dev-install

and the output will show how to start the program. Typically this is ../libo/install/program/soffice, which comes from the Makefile

Re-build

If you modify the sources, or pulled your git repositories with the lastest update, you can rebuild by simply running :

$ make

Sometimes, often because some header file got removed or renamed, it is necessary to do a full-blown rebuild.

$ make clean && make

Partial build

Of course, due to the time it takes, a full rebuild is not the first recourse. When something goes wrong in a specific module, you can rebuild just that module.

$ make <module>.clean
$ make <module>

For dmake-based module you also need to 'deliver' after a successful build

$ make <module>.deliver

Partial debug build

Should you need to do a debug build of a module, to see more of the debugging messages during the LibreOffice run, you can add debug=build as a build's parameter, like:

$ rm -r $INPATH
$ build debug=true

The syntax is similar for the new build system:

$ make -s clean
$ make -s debug=true

Verbose build

If you want to get verbose output during build:

$ make verbose=t

Getting debug output

If you want to get the output of OSL_TRACE() calls and other debug messages:


$ build debug=t dbglevel=2

with gmake:

$ make -s dbglevel=2

Getting debug symbols

If you want to enable symbols for profiling, debugging with gdb etc, but don't want to turn on debug outputs or change compiler optimization settings, run:

$ build -- ENVCFLAGS+=-g

with gmake:

$ make -s ENABLE_SYMBOLS=true

See other useful commands you can use (GNU make only)

To see other available options during partial module build, run:

$ make help

Note that this is different from running make -h, which lists commands for the GNU make itself.

The Build Failed... What can I do ?

Using a cutting edge development branch means that you are, more often than not, going to get cut. Things will not quite work as expected.

Here is an example of a failed build. My build messages ended with:

Making:    libslideshowtestlx.so
slideshow deliver
Module 'slideshow' delivered successfully. 2 files copied, 2 files unchanged
 
-----------------------------------------------------------------------
        Oh dear - something failed during the build - sorry !
  For more help with debugging build errors, please see the section in:
            http://wiki.documentfoundation.org/Development
 
  internal build errors:
 
ERROR: error 65280 occurred while making /lo/libo/connectivity/source/cpool
 
 it seems that the error is inside 'connectivity', please re-run build
 inside this module to isolate the error and/or test your fix:
-----------------------------------------------------------------------
[...]
make: *** [all] Error 1

First things: do not post that on the mailing list. The only useful information in all this is that the module 'connectivity' could not be built for some yet unknown reason.

Look at a file named build_error.log. if should contain the logs of the modules that failed.

Then look at the section Partial build for instruction on how to rebuild a module

Some explanation from IRC :

The "output" .component files (that end up somewhere under */${INPATH?}, i.e., either in a module-local unxlngx6.pro tree, or in global workdir/unxlngx6.pro or solver/unxlng6.pro) are generated from "input" .component files (within the source) by calling an xslt script and passing in a parameter; the parameter is written down in the makefiles (and then even "translated" into another parameter value via other makefile logic. So if any of those places change (the xslt script, the explicit parameters in the makefiles, or the makefile logic to translate them), there is typically no dependency between those changed files and the generated .component files, so "make" erroneously does not regenerate them

Finally, if there's no more option, you can relaunch the compilation from scratch on root directory :

$ make clean && make

Build tips

Building on Windows with Cygwin and Visual Studio Express

Building on Windows with Cygwin is a little bit special and not all information given here apply. Notices of such a build are collected here.

If you get mysterious build breaks or your systems hangs totally, you should consider, that you are running an application which interferes with Cygwin, for details see [1]

If you have consistent test failures on testCVEs, that probably means your antivirus is blocking the test files (as they are known to be exploits of fixed security issues). You may want to disable the monitoring of <root of repo>\*\pass in your AV.

Enable mozilla

As of June June 11th, 2012 Mozilla has been disabled by default because users on multiple platforms were having problems building without adding the --disable-mozilla option. If you wish to test, try, or use any features located in the Mozilla code you must enable mozilla by using option --enable-mozilla. Users have reported problems with Ubuntu based machines, Windows and Macs.

Windows multi-language installer

In order to build a multi-language installer on Windows, first complete the build to the end, then do

 cd instsetoo_native/util
 dmake openoffice_<locale>,<locale>,....   (comma separated list of locales)

where you specify the locales you want to include in the installer. Don't forget to build with --with-lang="<locale> <locale> ... " in order to make those locales available during the build.

Multiple Work Dirs

If you want to work on both the master branch, and the current release branch at the same time, you can share git repos, and external source tarballs (note the savings can be significant, especially if you also use the quite huge l10n repo). Note that switching branches within the same working dir is not recommended - the build dependencies for LibreOffice are still somewhat incomplete and fragile, and you'd likely have to perform clean re-compilations everytime you switch branches. If you can afford the diskspace, maintaining separate trees is the recommended way.

Setup

Prepare the first build on your disk just like explained above. For the second, and all other builds, do this to clone the initial core repo:

$ /other/libo/bin/git-new-workdir /other/libo /dir/to/be/created my-libo-branch

You'll notice a much quicker clone operation. After that, setup the new work dir with these two extra configure (or autogen.sh) options:

$ ./autogen.sh ... --with-linked-git=/other/libo/clone --with-external-tar=/other/libo/src
$ ./g checkout my-libo-branch

Again, cloning will be much faster. You have to use an absolute path for the --with-external-tar option. After that, you proceed with building just like for the single-workdir case.