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.

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:

An SSH KEY
The IP ADDRESS of the VM
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:

Download the 32-bit or 64-bit version of Cygwin, as appropriate for your Windows installation.
Run the installer
(Note: I think that Cygwin base include the SSH client by default, but I'm not sure -- TODO: CHECK!)
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.

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:

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