Hackfests/VMs/Using a VM

    From The Document Foundation Wiki
    < Hackfests‎ | VMs

    This page is all about Using one of our VMs at a Hackfest.

    Getting Started

    Using a VM at a Hackfest is pretty straightforward, but reading through the instructions ahead of time will help to get you up and running quickly and correctly, building LibreOffice as efficiently as possible, and making sure that all of your data is properly backed up at the end of the day.

    Steps to Using a VM

    1. #Logging-in with SSH
    2. #Running LibreOffice via X2Go
    3. #Building LibreOffice
    4. #Writing Code
    5. #Saving Your Work
    6. #Committing Code to LibreOffice

    Logging-in with SSH

    Once you can log-in to a VM, you can get started writing code and building LibreOffice.

    You'll need a couple of pieces of information before you can log in:

    1. An SSH KEY
    2. The IP ADDRESS of the VM
    3. The BUILD USERNAME you'll use to log-in

    Ask the Hackfest Coordinator or one of the Developer Mentors for this information.

    (NOTE: For Hackfest Organizers, it can be helpful to keep track of which participant is using which VM by making a list on a whiteboard or posterboard hanging in the room)

    On Windows

    SSHing is a little more tricky on Windows because the system doesn't ship with a quality command-line shell or have /home directories, but we'll fix that right up!

    We'll help you install Cygwin, which will provide a Bash shell, ssh tools, and other goodies.

    There are some screencasts on YouTube to help you install Cygwin (the only packages you'll need are SSH and SCP)

    Steps:

    1. Download the 32-bit or 64-bit version of Cygwin, as appropriate for your Windows installation.
    2. Run the installer
      (Note: I think that Cygwin base include the SSH client by default, but I'm not sure -- TODO: CHECK!)
    3. Cygwin should now appear in your Start Menu. Start the 'Cygwin Bash Shell' (or whatever it's called!)

    On GNU/Linux, macOS, BSDs, and Windows with Cygwin

    1. Open a shell/terminal

    2. Put the SSH KEY into your $HOME/.ssh/ directory, e.g.

    /home/<your username>/.ssh/libreoffice-ubuntubuild.pem
    
    Notes:
    * If the directory doesn't exist, create it!
    * In Windows, the path to this directory will probably appear as /cygdrive/c/home/<your username>/.ssh/
    

    3. Log-in via SSH:

    ssh -i ~/.ssh/libreoffice-ubuntubuild.pem <BUILD USERNAME>@<IP-ADDRESS>
    

    and with the BUILD USERNAME and IP ADDRESS substituted-in, that'll look something similar to:

    ssh -i ~/.ssh/libreoffice-ubuntubuild.pem build2@145.23.14.227
    

    Windows with PuTTY (Alternate Method)

    If you can't use Cygwin or are already very familiar with PuTTY, you can ssh-in using this method.

    First, convert the SSH KEY:

    • Launch puttygen
    • Navigate to Conversions -> Import Key
    • Select the SSH KEY .pem file
    • Click the button 'Save private key'
    • Save the key as a .ppk.

    Second, run PuTTY:

    • Launch the PuTTY program
    • Navigate to Connection -> SSH -> Auth -> Private key for authentication, and select the .ppk.
    • Under 'Session', input the IP ADDRESS to the Host name field
    • Click 'Open'
    • You'll get an "accept key question". Select 'Yes'.
    • Input the BUILD USERNAME

    And that's it!

    Running LibreOffice via X2Go

    X2Go is a remote desktop tool. It will allow you to run a build of LibreOffice on a VM, and have the output display on your local machine.

    X2Go Installation

    X2Go Session Configuration

    Run X2Go from your GUI or command-line and open a New session for configuration. You'll use the same IP ADDRESS and BUILD USERNAME with X2Go as you used to log-in on the command line.

    • Session name: LibreOffice Hackfest
    • Server:
      • Host: IP ADDRESS
      • Login: BUILD USERNAME # e.g. user01, user02, etc..
      • SSH port: 22
    • Use RSA/DSA key for ssh connection: SSH KEY # Note: Right-click and select 'Show Hidden Folders' if your key is in .ssh/
    • Session type: XFCE or LXDE

    Finally, click the 'OK' button to finish creating the session config. You should see an entry for the session appear in the right-hand pane of the X2Go window.

    X2Go Connecting to the Machine

    (On your local machine, set your resolution to 1024x768 or higher, as otherwise some LO dialogs won't fit on the screen! :-)

    • In X2Go, click (perhaps double-click on Windows?) on the entry for the LibreOffice Hackfest.
    • Wait -- you should soon be connected
    • A new window will pop-up showing a GNU/Linux desktop environment
      • The name in the title bar should be LibreOffice Hackfest

    Running LibreOffice

    Once you're logged-on to the machine, you've got choices on how to start LibreOffice:

    On the command-line:

    • Open a terminal window
    • Run LibreOffice from the command line
    ~/source/libo-core/instdir/program/soffice
    

    From the GUI:

    • Open the file browser
    • Navigate to /home/(YOUR USERNAME)/source/libo-core/instdir/program
    • Run LibreOffice by double-clicking on soffice

    Building LibreOffice

    NOTE: If you're logging-in to the VM for the first time, it's quite likely that LibreOffice has already been built. Try #Running LibreOffice via X2Go first, before you start #Writing Code.

    If you've already completed the previous steps, you're probably ready to try building LibreOffice yourself. Great -- let's do it!

    Use the right Build Directory

    BEFORE you start building, please ask the Hackfest Coordinator which numbered build area you should use!

    You'll likely be given a source-code/prepopulated build area under your home directory

    ~/source/libo-core
    

    Update Before You Build

    Before you build LibreOffice, make sure that you're using the latest commits:

    cd ~/source/libo-core
    
    # Update the LibreOffice source code to the latest and greatest!
    ./g pull -r
    

    Building

    The first time you build, it's good to build from scratch. Thereafter, incremental builds are generally fine (but feel free to ask the Mentoring Developers if you have questions!)

    Incremental Build

    Most of the time, you can just run an incremental build. This will be much faster than running a complete build from scratch.

    # copy autogen.input
    cp ~/autogen.input ~/source/libo-core/
    
    # Enter your build directory
    cd ~/source/libo-core
    
    # Kick off the build
    time make gb_COLOR=1
    

    Building from scratch

    NOTE: You probably won't have to build from scratch. Ask your Mentor Devs for help before following these steps!

    # Make sure the build directory is perfectly empty
    cd ~/source/libo-core
    git clean -fdx
    
    # Grab the sample autogen file
    cp ~/autogen.input ~/source/libo-core
    cd ~/source/libo-core
    
    # Run autogen (To learn more, see the GNU page on AutoGen)
    ~/source/libo-core/autogen.sh
    
    # Kick off the build
    time make gb_COLOR=1
    

    How Long Does it Take to Build?

    An incremental build might take ~10 minutes (thanks to ccache).

    If a lot of code has changed throughout LibreOffice, an incremental build can still take a while, e.g.:

    real   75m20.328s
    user  551m44.651s
    sys    35m42.023s
    

    Here's a full rebuild (using ccache):

    real   20m17.130s
    user  100m41.193s
    sys    12m54.479s
    

    (Examples from 2014-11-13)

    When Building in /mnt

    DISREGARD THIS SECTION, unless otherwise instructed by one of the Mentoring Devs :-)

    There are additional build areas in /mnt (because /srv is too small to hold more than a few).

    Please set the following environmental variable when building in /mnt:

    export CCACHE_DIR=/mnt/lo/.ccache
    

    Writing Code

    The mentors at the Hackfest will be able to give you pointers on changes appropriate to your skill level.

    Working Remotely

    To get people up to speed quickly, we'll be helping you get started writing code by running a text editor on the VM itself.

    • You can work inside X2Go, if you like
    • You can just run an editor such as emacs or vim from the command-line
      • (Note: I suggest you use a terminal manager such as byobu so you can re-attach to the terminal if the connection fails for some reason)

    Saving Your Work

    If you've made some valuable changes to the LibreOffice source code, we want to make sure that they aren't deleted when the VM is shut down at the end of the Hackfest.

    There are several methods of retaining your changes

    Download diffs

    On the Hackfest VM, cd to the source directory and make a timestamped patchfile:

    git diff -u > ../saved-libreoffice-diff_$(date -u '+%Y.%m.%d_%H.%M.%S').patch
    

    On your local machine, cd to an appropriate directory and copy the patchfile(s) down:

    cd ~/src/libreoffice/  # Just as an example -- feel free to store your patches wherever you like :-)
    scp -i ~/path/to/hackfest/SSH_KEY BUILD_USERNAME@IP_ADDRESS:~/source/*.patch .
    

    Check to make sure that all of your code changes are present, to ensure no loss of data!

    Email diffs to yourself

    Turn your diffs into a patchfile as above and then email it:

    mail --attach=saved-libreoffice-code-changes.patch -s "LibreOffice Hackfest Changes" <your email address>
    
    (NOTE: Robinson has a script for this, but we don't
     currently run a mail server on the Hackfest VMs)
    

    Committing Code to LibreOffice

    Talk to the devs -- we also have notes on the wiki :-)

    If you're productive and create some patches, we'll want you to push them into our git repository. You can either pull them to your local git checkout, create a patch and copy that, or just copy the files down to your machine.

    WARNING: when we shut down the VMs, we also delete the disks, so anything not backed up will be GONE!

    Bibisect Repositories

    USERS: DISREGARD this section for now, please!

    The bibisect repositories are in

    ~/bibisect
    
    • These are local clones, i.e. space-efficient, so creating a ton of others is not a problem

    TODO

    Thoughts/notes on improving this documentation:

    - Install emacs on VMs (do we also need some very-GUI-friendly text editor?)
    - Make terminals use screen/byobu by default
      (like this, I guess) https://bugs.launchpad.net/byobu/+bug/586546/comments/21
    - Implement script to help users save their code changes