Hackfests/VMs/Using a VM

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)
 * 2)
 * 3)
 * 4)
 * 5)
 * 6)

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  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  directory, e.g. /home/ /.ssh/libreoffice-ubuntubuild.pem

Notes: * If the directory doesn't exist, create it! * In Windows, the path to this directory will probably appear as

3. Log-in via SSH:

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

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.


 * Download PuTTY and install it

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

 * Download and install X2Go.
 * On GNU/Linux, install the X2Go Client via your packager manager

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: ~/source/libo-core/instdir/program/soffice
 * Open a terminal window
 * Run LibreOffice from the command line

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 first, before you start.

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

./g pull -r
 * 1) Update the LibreOffice source code to the latest and greatest!

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.

cp ~/autogen.input ~/source/libo-core/
 * 1) copy autogen.input

cd ~/source/libo-core
 * 1) Enter your build directory

time make gb_COLOR=1
 * 1) Kick off the build

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

cd ~/source/libo-core git clean -fdx
 * 1) Make sure the build directory is perfectly empty

cp ~/autogen.input ~/source/libo-core cd ~/source/libo-core
 * 1) Grab the sample autogen file

~/source/libo-core/autogen.sh
 * 1) Run autogen (To learn more, see the GNU page on AutoGen)

time make gb_COLOR=1
 * 1) Kick off the build

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  or   from the command-line
 * (Note: I suggest you use a terminal manager such as  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"  

(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