LODE – LibreOffice Development Environment

TDF LibreOffice Document Liberation Project Community Blogs Weblate Nextcloud Redmine Ask LibreOffice Donate

• Wiki Home
• Development
• Design
• QA
• Events
• Documentation
• Website
• Localization
• Accessibility
• Marketing
• Diversity
• Wiki Help

• Overview
• Reporting Bugs
• How to build
• Code Overview
• Git Commands
• Debugging
• EasyHacks
• Release Plan
• FAQ
• Developers
• Extensions
• → Open Issues

• Linux
• Windows
• macOS
• Android
• Generic Building Hints

LODE helps you setup the environment to build LibreOffice.

Its purpose is to simplify the setup of necessary dependencies and tools needed to build LibreOffice. This is aimed at getting new developers up to speed quicker, and also at helping setup tinderbox and jenkins slaves.

LODE is meant to work well for builds on the master branch.

Windows-specific section

Installation of MSVC, SDK and JDK is not part of LODE yet and must be installed manually - see relevant sections at Building on Windows. If you now go to that page, remember to use it only to see how to install MSVC and JDK, then come back to this page.

Cygwin

On Windows, LODE needs Cygwin, so you need to install Cygwin first. A Powershell script is provided for that purpose.

Install the latest stable release of PowerShell.

PowerShell Permissions in Windows 8.1 and 10

The default PowerShell permissions setting in Windows 8.1 and 10's PowerShell is Restricted. This does not allow any scripts to run. Additionally, the LODE script is unsigned, so your permissions need to be set to Unrestricted to run it. For detailed information about PowerShell permissions, please see the Microsoft's documentation on the topic.

Follow these steps to set your permissions to Unrestricted to run the script, then revert this after running the script.

First, start PowerShell and issue this command to find out your current permission level:

Get-ExecutionPolicy

Record this before moving on. This value will be referred to below as <ORIGINAL_PERMISSION_LEVEL>.

Start PowerShell using the Run as Administrator option and write the following command:

Set-ExecutionPolicy -ExecutionPolicy Unrestricted

Now download and run the install_cygwin.ps1 script as mentioned below.

After the script finishes, reset your permissions to their original level:

Set-ExecutionPolicy -ExecutionPolicy <ORIGINAL_PERMISSION_LEVEL>

Running the script

Once you have PowerShell and its permissions have been temporarily changed as mentioned above, create the directory C:\cyginstall). Please do not use other drives (especially not network drives).

The Cygwin installation script is not made to run from the C:\cygwin directory; it will create that directory. Creating the separate directory for the script is necessary.

In a PowerShell console, cd to C:\cyginstall and download and run the script install_cygwin.ps1:

$Request = Invoke-WebRequest -Uri https://git.libreoffice.org/lode/+/refs/heads/master/bin/install_cygwin.ps1?format=TEXT; [Text.Encoding]::Utf8.GetString([Convert]::FromBase64String($Request.Content)) > install_cygwin.ps1; .\install_cygwin.ps1

If a security warning shows up, answer "R" for "Run Once".

This will install Cygwin and all the Cygwin dependencies that a LibreOffice build needs in C:\cygwin.

once this is done, reset the PowerShell permissions to their original level as mentioned in the previous section.

You now have a C:\cygwin\Cygwin.bat which will give you a Cygwin command prompt. You can access it via desktop and start menu shortcuts as well. Run it and follow the rest of the instructions below.

Note: The install is done with your own user account, without Administrator escalation. This means that there will be no Cygwin entries in the Start Menu and no shortcut on the Desktop. You can however make a shortcut to the bat file, if you want (hint, the icon for the shortcut is available in c:\cygwin).

Supported Platforms

Currently LODE only works on Windows and macOS. LODE's aim is to eventually support every platform LibreOffice is buildable on. For up-to-date information on platform support, see the file README.md at the root of the core repository.

Getting Started

All instructions below MUST be done with a regular user. DO NOT ever run ./setup as Administrator (on Windows) or root (on macOS), nor run sudo ./setup (on macOS).

Choose a place where you want your LODE installation to be. You can put it anywhere you want -- in your HOME directory is fine -- but you need to have enough space there to have a LibreOffice build and more... count 25 GB to be safe with one debug build environment... for a Jenkins slave at least 100 GB should be provisioned.

A couple of warnings based on experience from earlier installations:

• Do not use a network drive - it will not work. There can also be problems with some older USB drives
• Do not use names longer than 8 characters
• Only use a-z and 0-9 in the name, NO spaces or other special characters

Important: For Windows users, all the following commands must be run in a Cygwin shell. Using Git for Windows clones a version where line endings are converted to DOS style, and they will not work.

Clone the lode git repository:

git clone https://gerrit.libreoffice.org/lode

Change directory to the lode directory:

cd lode

Read the help, README and the prerequisites for your platform:

./setup --help
./setup --prereq
cat README

Make sure to install these prerequisites for your specific platform before you continue.

• Windows prerequisites (Visual Studio and Java Development Kit)

• macOS prerequisites

Once you have met the prerequisites for your platform, run:

./setup

Read the notes at the end of the setup.

The setup program does not automatically adjust your shell profile file, since that may not be desirable in your environment. You need to make the necessary adjustment and make sure that the shell environment conforms to the requirements:

If your shell is Bash (Cygwin's default), add the environment variables into ~/.bashrc or ~/.bash_profile. If your shell on macOS is Zsh, the file you need to edit will be ~/.zshrc or ~/.zprofile. You can find out your shell flavour with the command echo "$SHELL". For example, edit your profile file and add the following lines to it, replacing user with your user name:

Windows:

export LODE_HOME=/home/user/lode
PATH="${LODE_HOME}/opt/bin:${PATH}"

macOS:

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

One way to do that is issuing these commands directly from your terminal (use ~/.zprofile instead of ~/.bash_profile when using Zsh on macOS):

Windows:

echo "export LODE_HOME=/home/$USER/lode" >> ~/.bash_profile
echo PATH="\${LODE_HOME}/opt/bin:\${PATH}" >> ~/.bash_profile

macOS:

echo "export LODE_HOME=$HOME/lode\nexport PATH=\"\${LODE_HOME}/opt/bin:\${PATH}\"" >> ~/.bash_profile

macOS (Big Sur):

echo "export LODE_HOME=$HOME/lode\nexport PATH=\"\${LODE_HOME}/opt/bin:\${PATH}\"" >> ~/.zshrc

Restart your terminal: close the terminal window and open it again. On Windows, to start Cygwin run C:\cygwin\cygwin.bat (this is the default path). A restart is needed for Cygwin to use the new LODE_HOME environment variable from your profile.

If things went well, you can move to the right location and setup a dev build environment by running:

cd $LODE_HOME
./setup --dev

This will setup a dev/core repository. By default it will configure dev/core/autogen.input (the file where one puts the configuration options for the build) to make a debug build.

If you do not like core as a workspace name or if you want another workspace to work with, use this instead:

./setup --new <name>

It will do the same thing as the --dev flag, except the repository created will be in dev/<name>.

Now it is time to build. If you are on Windows, before you do this, make sure your anti-virus software will not cause any problems.

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

After 1 to 2 hours, or more depending on your machine (Windows can take more than 8 hours for the first build), you will have a built LibreOffice. Consult the other pages on this wiki to go further or to deal with build problems.

When the build has finished without errors, you can run your fresh build of LibreOffice on Windows using:

instdir/program/soffice.exe

or on macOS with:

open instdir/LibreOfficeDev.app

Notes: If make check tests fails, you can create a usable executable by running just make.

Before working on patches, please set up Gerrit and then continue looking at Easy_Hacks

Developers

If your favorite operating system is not supported, you are welcomed to contribute the necessary patches to add its support.

LODE is hosted on http://gerrit.libreoffice.org under the project 'lode'. You can propose patches the same way you would for LibreOffice itself. LibreOffice committers are also committers for LODE.

Here are a few things to know about LODE development itself:

Architecture

LODE is written in Bash shell. Most of the interesting stuff is in ./setup and ./bin/utils*.sh.

OS is determined using $(uname)... see determine_os() in bin/utils.sh.

Once an OS is determined we search for a file bin/utils_${OS}.sh. If it is found, it is sourced.

Then a function determine_os_flavor is called -- which should have been overridden in utils_${OS}.sh. This function sets up an OS_FLAVOR variable. If that variable is non-empty, then the file bin/utils_${OS}_${OS_FLAVOR}.sh is sourced, if it exists.

This mechanism will allow you to override any functions with one specific for your specific combinations.

You can then look at the 'setup' program and see what it calls in which case.. setup is platform independent (and must remain so). All the calls made after the call to determine_os in setup, immediately after the parameter parsing, can be overridden to do platform/flavor specific actions.

Any failures should end with a call to die "Error: <what we are complaining about>". This will terminate the execution.

Any step needs to handle being called repeatedly and behave appropriately. In other words any step should check if that step is necessary and if not just skip over the meat of the task. See utils.sh, utils_macOS.sh, and utils_macOS_10.0.sh for examples.

The function final_notes is meant to display at the end of a successful setup any extra information and requirements that the user will need to address.

The function display_prereq is meant to display prerequisites for setup to work. It is called when invoking ./setup --prereq. For example on macOS one needs to install XCode and a Java JDK before ./setup can be called.

As much as possible it is favored that setup does not need special privileges to function. So steps that do require elevated privileges should preferably be done by the user in pre-req steps. This position can be argued on a platform by platform basis. You may have a compelling case for using sudo, but under NO circumstances should the user be directed to run sudo ./setup.

Tree Structure

The naked structure of lode after a clone looks like this:

  .git                    # Git data.
  .gitignore              # LODE will create fields and directory inside the repo that need to be ignored by git.
  .libreoffice_autosetup  # A semaphore file to help auto-discover a LODE setup.
  README                  # Self-explanatory :-)
  bin/                    # Place for scripts delivered with LODE itself.
    utils*.sh             # Reserved for setup support code.
  setup                   # Main script.

After ./setup runs, additional objects may be created, such as:

  adm/          # A directory that contains auxiliary repos like today buildbot.git.
  dev/          # Where the --dev setup option installs a clone of core.git.
    core/       # LibreOffice core repo.
  jenkins/      # Jenkins's HOME when using LODE as a Jenkins slave.
  mirrors/      # Contains bare mirrors of repos to be use to accelerate cloning.

Keeping LODE Updated

To update Cygwin: Repeat the instructions above to run .\install_cygwin.ps1 from a PowerShell console with the necessary permissions.

To update build tools like cmake and autotools: From the root LODE folder, do a git pull. Then run ./setup.