LODE – LibreOffice Development Environment

    From The Document Foundation Wiki


    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

    Warning.svg

    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 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 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 -UseBasicParsing; [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.

    Warning.svg

    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

    Warning.svg

    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
    Warning.svg

    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.

    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.