Development/BuildingOnLinux

    From The Document Foundation Wiki
    This page contains changes which are not marked for translation.

    Introductory notice

    Since this turns out to be the common problem with newbies, please note: do not build as root! This will break your build, and as the result, you'll need to cleanup everything (including ccache) and start over. The steps that need elevation use sudo explicitly in the following explanation.

    Do also read our generic building hints.

    Build dependencies

    In general, the easiest way to build LibreOffice is on Linux.

    Note: Windows Subsystem for Linux is not supported!

    Note pin.svg

    Note:
    It is usually the case that branches that are newer than what your distro has packaged (especially master) have additional requirements, which the autogen.sh step will helpfully point out to you; usually these requirements are either optional and have a corresponding --disable-foo or --without-foo argument, or the requirement can be satisfied with an option to use a bundled copy via --without-system-foo argument (which should be the default already). If neither is the case then you need to install some development package on your system: look at what configure is complaining about specifically and use apt-cache search or yum search to find relevant packages, usually with -dev or -devel in the name.

    Debian and Ubuntu

    Install the dependencies

    sudo apt-get install git build-essential zip ccache junit4 libkrb5-dev nasm graphviz python3 python3-dev qtbase5-dev libkf5coreaddons-dev libkf5i18n-dev libkf5config-dev libkf5windowsystem-dev libkf5kio-dev libqt5x11extras5-dev autoconf libcups2-dev libfontconfig1-dev gperf openjdk-17-jdk doxygen libxslt1-dev xsltproc libxml2-utils libxrandr-dev libx11-dev bison flex libgtk-3-dev libgstreamer-plugins-base1.0-dev libgstreamer1.0-dev ant ant-optional libnss3-dev libavahi-client-dev libxt-dev
    
    Note pin.svg

    Note:
    Since Sept 22 2023, gcc/g++ must be at least version 12. sudo apt install gcc-12 g++-12 and then sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-12 60 --slave /usr/bin/g++ g++ /usr/bin/g++-12

    You may need to first add a PPA (and then get version 13 instead) with sudo add-apt-repository ppa:ubuntu-toolchain-r/test

    openSUSE

    The dependencies can be installed on Tumbleweed with this command:

    sudo zypper in git autoconf automake bison make gcc gcc-c++ cups-devel fontconfig-devel gperf java-17-openjdk-devel libxslt-devel python3-devel krb5-devel libX11-devel libXext-devel libICE-devel libSM-devel libXt-devel libXrender-devel libXrandr-devel flex gtk3-devel gstreamer-devel gstreamer-plugins-base-devel ant junit nasm ccache binutils-gold mozilla-nss-devel
    

    on Leap gcc12 and gcc12-c++ distro packages should be installed and the following lines should be added to autogen.input:

    CC=gcc-12
    CXX=g++-12
    

    Fedora/Red Hat

    sudo dnf builddep libreoffice

    Arch Linux

    These make dependencies are copied from the official PKGBUILD of Arch Build System (with some modifications as it includes stuff that is not needed).

    sudo pacman -S --needed 'base-devel' 'git' 'ccache' 'ant' 'apr' 'beanshell' 'bluez-libs' 'clucene' \
                            'coin-or-mp' 'cppunit' 'curl' 'dbus-glib' \
                            'desktop-file-utils' 'doxygen' 'flex' 'gcc-libs' \
                            'gdb' 'glm' 'gobject-introspection' 'gperf' 'gpgme' \
                            'graphite' 'gst-plugins-base-libs' 'gtk3' \
                            'harfbuzz-icu' 'hicolor-icon-theme' 'hunspell' \
                            'hyphen' 'icu' 'java-environment' 'junit' \
                            'lcms2' 'libabw' 'libatomic_ops' 'libcdr' 'libcmis' \
                            'libe-book' 'libepoxy' 'libepubgen' 'libetonyek' \
                            'libexttextcat' 'libfreehand' 'libgl' 'libjpeg' \
                            'liblangtag' 'libmspub' 'libmwaw' 'libmythes' \
                            'libnumbertext' 'libodfgen' 'liborcus' 'libpagemaker' \
                            'libqxp' 'libstaroffice' 'libtommath' 'libvisio' \
                            'libwpd' 'libwpg' 'libwps' 'libxinerama' 'libxrandr' \
                            'libxslt' 'libzmf' 'lpsolve' 'mariadb-libs' \
                            'mdds' 'nasm' 'neon' 'nspr' 'nss' 'pango' \
                            'plasma-framework5' 'poppler' 'postgresql-libs' \
                            'python' 'qt5-base' 'redland' 'sane' 'serf' 'sh' \
                            'shared-mime-info' 'ttf-liberation' 'unixodbc' \
                            'unzip' 'xmlsec' 'zip' 'gtk4' 'qt6-base' 'zxing-cpp' \
                            'abseil-cpp'

    If you don't plan to be working on Java, you can remove ant, beanshell, java-environment and junit from this list as LibreOffice mostly runs without it.

    If 'gcc-libs-multilib' is installed, you will have to remove the 'gcc-libs' dependency.

    Slackware

    ./autogen.sh --without-java --disable-postgresql-sdbc --disable-gstreamer-1-0

    BSDs

    • DragonFlyBSD cd /usr/dports/editors/libreoffice && make patch
    • FreeBSD cd /usr/ports/editors/libreoffice && make patch
    • NetBSD cd /usr/pkgsrc/misc/libreoffice && make depends

    Cloning and building

    Next, we clone the repository. Beware that building doesn't currently seem to work properly in paths that include Unicode characters, and that git clone may take a while based on your connection speed and server traffic:

    $ git clone https://gerrit.libreoffice.org/core libreoffice
    $ cd libreoffice


    At this point, you might want to display possible options to pass to autogen:

    $ ./autogen.sh --help

    For example consider adding a Debugging option. Changing some of these options will require to do a full rebuild: e.g., adding --enable-dbgutil. Since the following command make takes a vast quantity of time to run for the first time, you probably would like to save time by specifying the settings you'd need depending on the ultimate goal of your build. In case of doubt, possibly it's good to ask for advice on #libreoffice-dev IRC://.

    You should have a suitable configuration for the build that you put inside autogen.input file. But, you can start with a minimum set of options and customize them later. A sample autogen.input for building LibreOffice on Linux can be as follows, to enable debug build, and also disable doxygen to save time. Since the make command can take a vast quantity of time to run for the first time, these options are helpful.

    --enable-dbgutil
    --without-doxygen

    Then you can prepare build files using:

    $ ./autogen.sh


    Now you are ready for building using make. Beware that full (all components, non-incremental) build may take up to 24 hours and takes up about 20 GB of drive space. You will also most likely need at least 8 GBs of RAM, otherwise the machine might fall into swap and appear to freeze up.

    It is a good idea to first run make, so you have a working build in case make check later fails.

    $ make
    $ make check

    Running your build

    The previous step creates a good local installation, which you can then start with:

    $ instdir/program/soffice --writer
    $ instdir/program/soffice --calc


    Video Tutorials

    Getting Started with LibreOffice Development

    Please accept this video. By accepting you will be accessing content from YouTube, a service provided by an external third party.

    YouTube privacy policy

    The video illustrates the process of setting up a development environment and building. However, please use the wiki documentation for your setup instead of trying to write things down from what you see in the video.

    Tips

    Running under a debugger

    For starting your build directly under a debugger:

    $ make debugrun

    Then you can open Writer with the command:

       (gdb) run --writer
    

    Note that soffice.bin will be terminated the first time it is run directly (or via make debugrun), this is normal, you simply need to run it again to make use of it. Running soffice will deal with this for you.

    Enable warnings

    Various versions of GCC are well-known to emit more/unhelpful/bogus warnings at higher optimization levels. Don't even try to combine --disable-debug --enable-werror build with GCC.

    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 change lots of header files in LibreOffice, 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 5GB which is far too small to be useful for a LibreOffice build; for a build without debug symbols, you should have at least 8GB cache, and for a build with debug symbols for everything probably 32GB 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
    

    Icecream / distcc

    If you are in an environment where you have access to multiple machines with spare CPU cycles, you can take a look at icecream or distcc tools for distributed build. Icecream is recommended and easier to setup.

    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 /usr/lib/icecc/bin or in /opt/icecream/bin. Should you have them somewhere else, please use --with-gcc-home=/path/to/your/icecream/bin switch to override that.

    To make use of distcc, first install and start distccd on all the build machines and make sure all the compiler versions are compatible (this is important for C++ code). Now on the driving machine install and configure distcc to use the other build hosts. Then pass --with-parallelism=N to autogen.sh, where N is the total number of CPUs available in your cluster and run distcc-pump make CC=distcc CXX=distcc to start the distributed build.

    Precompiled headers

    Passing --enable-pch to autogen.sh enables use of precompiled headers (PCH), which reduce build time at the expense of more disk space and more source files possibly rebuilt when a header changes. The option has several levels (system, base, normal, full), the higher level the higher possible gain but also disk space usage and chance for larger rebuilds on changes.

    --with-parallelism

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

    --with-parallelism already defaults to the number of cores/CPUs on your system, unless you use --enable-icecream - then to 10.

    --with-system-libs

    Building with existing libraries may speed up your build, but you have to fiddle with the dependencies.

    Approximate build times

    The first build or a clean build takes approximately 8/number_cores hours on a recent processor. With ccache, subsequent daily build time varies between 2 and 10 min (depending on the number of modified or added files and their complexity).

    Verbose make

    Make will hide the exact command invocations. To see what make does exactly for a single run one can invoke it as

    $ make verbose=1

    Using verbose=1, in turn sets this option for the child make invocations, and also deals with externals. In the verbose mode, every single command used to build LibreOffice is shown, which can be used for troubleshooting build problems.

    Multiple Work Dirs

    If you want to work on both the master branch, and the current release branch(es) 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 between different release branches within the same working dir is not recommended; even if there are no dependency problems, the amount of stuff you'd have to rebuild is practically equal to a clean rebuild. If you can afford the disk space, maintaining separate trees is the recommended way.

    There are two methods to share git repos across working directories: git clone --reference and git-new-workdir. A referenced clone can avoid re-downloading the repo, but the new workdir will still have its own .git/config, etc. This is supported by upstream git developers. git-new-workdir, however, is not supported and can cause problems if you try to check out the same branch in two working directories, etc.

    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:

    $ git clone --reference /path/to/master --branch name-of-branch ssh://logerrit/core /dir/to/be/created

    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-referenced-git=/path/to/master --with-external-tar=/path/to/master/external/tarballs

    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.

    The --with-referenced-git option is only needed if you enabled some submodules (translations, dictionaries or help) or you're building the libreoffice-4-0 branch (or one that is even older). On newer branches submodules are disabled by default.

    If you want to cherry-pick between the working directories, you can setup your local copy of git to act like a remote, like this:

    $ cd /path/to/stable-workingcopy
    $ git remote add unstable /path/to/master/.git
    $ cd /path/to/master
    $ git remote add stable /path/to/stable-workingcopy/.git

    You then just cherry-pick commits like you would to a "true" remote on another server.

    Checking out a release branch

    run autogen.sh on master with the specific parameters you need, then run make fetch to fetch the submodules that may be needed depending on the parameters you passed to autogen.sh

    then switch branch with

    $ ./g checkout -b libreoffice-4-0 origin/libreoffice-4-0

    rpm not found/ant not found/no package gnome-vfs-2.0

    --disable-epm This will fix "rpm not found", as autogen.sh 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 built at all.

    Note: Installing 'libgnomevfs2-dev' package on Ubuntu manually will fix "No package 'gnome-vfs-2.0' found" on older release branches. It should not be needed anymore on master by now. Use synaptic package manager or run in terminal

    $ sudo apt-get install libgnomevfs2-dev

    Build DEB and/or RPM Packages

    If you are wanting to build DEB or RPM packages, add the appropriate options to your autogen.input file:

    RPM

    --with-package-format=rpm
    --enable-epm

    DEB

    --with-package-format=deb
    --enable-epm

    The basic TDF distro configs can be found in the distro-configs module. For Linux, look at distro-configs/LibreOfficeLinux.conf.

    Where are the packages?

    Look for the files in the ./workdir/installation/ directory. There is a folder for each of the different sets of packages that includes subfolder[s] for the type or types of packages, either DEB, RPM, or both. Inside the subfolder[s] is another folder called install, and it includes two subfolders. One subfolder contains an archive of all of the packages zipped together (the ..._download folder) and the other contains a DEBS/RPMS folder with each individual package. The rest should be self-explanitory!

    Dealing with line endings and Git's autocrlf

    If autogen.sh produces output like the following:

    ./autogen.sh: line 1: $':\r': command not found
    ' '--srcdir=/home/user/libreoffice' '--enable-option-checking=fatal'
    configure: WARNING: you should use --build, --host, --target
    configure: WARNING: invalid host type: 
    ********************************************************************
    *
    *   Running LibreOffice build configuration.
    *
    ********************************************************************
    
    ' not recognized system type... Invalid configuration `
     failedre: error: /bin/bash ./config.sub 
    Error running configure at ./autogen.sh line 241.

    ... then you probably have line-ending problems. This might occur if you mistakenly set Git's core.autocrlf=true.

    To fix the issue, run these commands (WARNING: uncommitted changes will be lost!):

    git config --unset core.autocrlf
    git rm --cached -r .
    git reset --hard
    git clean -x -f
    ./autogen.sh

    Building translated user interface with .po files TDF Weblate

    LibreOffice's user interface is translated using .po files hosted on TDF Weblate server and translations are updated and packaged as language packs with every new release for every branch respectively. That often means language pack is not reflecting all the improvements made in-between releases and nightly builds exists only for a handful of languages. Translators might benefit from testing their work before new release been published and but early adopters could test translations before the official release.

    First make sure you managed build dependencies and then try to clone and run your build.

    Building translated user interface

    1. Firstly you need to download .po files from TDF Weblate. You might log-in to TDF Weblate to download .po files.
    2. rebuild the source with language pack option on using command ./autogen.sh --with-lang="<langCode>" and don't forget to replace <langCode> with actual language code. If using an autogen.input file, no quotes are used, so this becomes: --with-lang=de ja ar
    3. extract downloaded .po files and copy content to relevant directories in source tree using command (on GNU/Linux) cp -R <langCode>/libo_ui/* libreoffice/translations/source/<langCode>/ and don't forget to replace <langCode> (two occurrences) with actual language code
    4. this step might be tricky. It seems that some extracted .po files are named 'messages.po' and some are named differently. What you need is every .po file converted to .mo file and
      1. for files that are **not named** 'messages.po', conversion is done by running make build-l10n-only
      2. for files that **are** named 'messages.po' you need to convert to .mo files manually running msgfmt -o instdir/program/resource/<langCode>/LC_MESSAGES/<moFile><dir>/messages.po for every such file. Here three things must be changed: <langCode> to actual language code, <moFile> with data from the left column of the table below and <dir> with data from right side of table below. Just make sure you prefix path '<dir>/messages.po' with full path from current working to destination.

    As mentioned in step 4, some .po files are named 'messages.po' and some are named differently. The table below lists directories that might hold 'messages.po' files and on which step 4.2 should be applied.

    <mofile> <dir>
    acc.mo accessibility
    avmedia.mo avmedia
    basctl.mo basctl
    chart.mo chart2
    cnr.mo connectivity
    cui.mo cui
    dba.mo dbaccess
    dkt.mo desktop
    editeng.mo editeng
    filter filter
    for.mo formula
    fps.mo fpciker
    frm.mo forms
    fwk.mo framework
    pcr.mo extensions
    rpt.mo reportdesign
    sb.mo basic
    sc.mo sc
    sca.mo scaddins
    scc.mo sccomp
    sd.mo sd
    sfx.mo sfx2
    sm.mo starmath
    svl.mo svl
    svt.mo svtools
    svx.mo svx
    sw.mo sw
    uui.mo uui
    vcl.mo vcl
    wiz.mo wizards
    wpt.mo writerperfect
    xsc.mo xmlsecurity

    Last step in process is to run sudo make install to install with newly added translations.

    If you would like to build LibreOffice-master and check the translation, you may need "make translations" to merge .po file with the .pot files.

    Building translated Help files

    Help files are also translated on TDF Weblate so for translated Help files this can be done

    1. by downloading .po files of translated Help
    2. run ./autogen.sh --with-help --with-lang="<langCode>" replacing <langCode> with actual language code. If you want to build Help as HTML files, do --with-help=HTML. If using an autogen.input file, no quotes are used, so this becomes: --with-lang=de ja ar
    3. run make
    4. run cp -fR <langCode>/libo_help/* libreoffice/translations/source/<langCode>/helpcontent2/source/text/, but remember to replace two instances of <langCode> with actual language code and make sure you navigate to this folder correctly from current working directory
    5. run mv libreoffice/translations/source/<langCode>/helpcontent2/source/text/auxiliary.po libreoffice/translations/source/<langCode>/helpcontent2/source/. Replace two instances of <langCode> with actual language code and make sure you navigate to this folder correctly from current working directory
    6. run make build-l10n-only
    7. run sudo make install

    (Thanks to Kiyotaka and Jihui)