Development/lode

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.

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. This does not allow any scripts to run. Additionally, the LODE script is unsigned, so your permissions need to be set to  to run it. For detailed permissions about PowerShell permissions, please see the Microsoft TechNet page on the topic.

Follow these steps to set your permissions to  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:

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

Start PowerShell using the  option and write the following command:

Now download and run the  script as mentioned below.

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

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

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

In a PowerShell console,  to   and download and run the script  :

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.

You now have a  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 ).

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
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

Clone the lode git repository:

Change directory to the  directory:

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

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:

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  or. If your shell on macOS is Zsh, the file you need to edit will be  or. You can find out your shell flavour with the command. For example, edit your profile file and add the following lines to it, replacing user with your user name:

Windows:

macOS:

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

Windows:

macOS:

macOS (Big Sur):

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

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

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

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

It will do the same thing as the  flag, except the repository created will be in.

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.

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  tests fails, you can create a usable executable by running just.

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  and.

OS is determined using ... see  in.

Once an OS is determined we search for a file. If it is found, it is sourced.

Then a function  is called -- which should have been overridden in. This function sets up an  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  in setup, immediately after the parameter parsing, can be overridden to do platform/flavor specific actions.

Any failures should end with a call to. 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,  , and   for examples.

The function  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  is meant to display prerequisites for setup to work. It is called when invoking. For example on macOS one needs to install XCode and a Java JDK before  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.

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  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  from a PowerShell console with the necessary permissions.

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