lode - LibreOffice Development Environment

From The Document Foundation Wiki
Jump to: navigation, search

lode is a project that helps you setup a base 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. Currently, that is LibreOffice 5.4 and higher.

Note to experienced developers: this page is intentionally made simple, and shows a simple way to get LO development setup on a windows system. Please do not make functional changes to this page, but send an email instead.


Windows Bootstrapping (Windows user only)

Gnome-dialog-warning.svg

Installation of MSVC, SDK and JDK is not part of lode yet and must be installed manually.


bootstrap cygwin

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

If you have Windows 8, 8.1, 10 or Windows Server 2012 you already have Powershell. For Windows 7 and Windows Server 2008 R2, download it from [1].

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 permissions about PowerShell permissions, please see the Microsoft TechNet page 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 a directory C:\cyginstall), please do not use other drives (especially not network drives)

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

Then open a PowerShell console, cd to C:\cyginstall and run:

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

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

lode's aim is to eventually support every platform LibreOffice is buildable on, but some are more tested than others.

OS Family Flavor/Version Support Notes
Cygwin Yes
MacOSX 10.9 Yes
MacOSX 10.10 Yes
MacOSX 10.11 Yes

Getting Started

Gnome-dialog-warning.svg

All instructions below MUST be done with a regular user. DO NOT ever run ./setup as root, nor run sudo ./setup


Chose 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 25GB to be safe with one debug build environment... for a jenkins slave at least 100GB should be provisioned

A couple of warning, 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 char
  • Only use a-z and 0-9 in the name, NO spaces or other special characters

NOTE For Windows users: Important, 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 repo:

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

move to the lode directory:

cd lode

read the help and the pre-req for your platform:

./setup --help
./setup --prereq

Also read the README file present in the root of the lode folder, for instance by typing

cat README

This file will tell you about the prerequisites for building LibreOffice on various platforms. Make sure to install these prerequisites for your specific platform before you continue.

Windows prerequites:

  • Visual Studio 2015 (the free Community edition will do)

{{note|You need to install the newest "Update" for Visual Studio 2015, or the build will fail.

  • 32-bit Java Development Kit (JDK) jdk-8u111-windows-i586.exe or newer
  • Remark 64-bit JDK is currently being tested, but has known issues so will not work.

Once you have met the prerequisites for your platform, run

./setup


Read the notes at the end of the setup. And add environment variables into .bashrc or .bash_profile file. For example:

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

The setup program does not automatically adjust your .bashrc, 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 things went well, to setup a dev build environment run:

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

Now it is time to build:

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

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

If you do not like core as a workspace name or if you want another workspace to work with

./setup --new <name>

will do the same thing as --dev except the repo created will be in dev/<name>

Note that since lode uses a local bare mirror, the cost, in term of .git of an extra repo is minimal, typically few MB.

Before working on patches, please setup gerrit and then continue looking at Easy_Hacks

Developers

If your favorite OS/flavor is not supported, your 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 are we 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_MacOSX.sh, and utils_MacOSX_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 Mac OS X 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, with eventually different options the following objects may be created:

  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.

Additional Tools

Additional tools can be installed with apt-cyg

lynx -source rawgit.com/transcode-open/apt-cyg/master/apt-cyg > apt-cyg
install apt-cyg /bin

or if no lynx

wget rawgit.com/transcode-open/apt-cyg/master/apt-cyg

Example use of apt-cyg:

apt-cyg install nano