Making a GNOME Development Snapshot Virtual Machine

Brent Smith

GNOME Documentation Project

This article explains how to create a virtual machine of the latest development snapshot of the GNOME Desktop.

Copyright (c) 2006 by Brent Smith. This material may be distributed only subject to the terms and conditions set forth in the Open Publication License, v1.0 or later (the latest version is presently available at

Distribution of the work or derivative of the work in any standard (paper) book form is prohibited unless prior permission is obtained from the copyright holder.


To report a bug or make a suggestion regarding the GNOME desktop or this manual, please send an email to gnomeATnextrealityDOTnet.

Revision History
Revision $Id: build-brigade-vm.xml,v 1.2 2006/08/27 04:47:50 smitten Exp $$Date: 2006/08/27 04:47:50 $

Brent Smith

GNOME Documentation Project


An article that explains how to create a virtual machine of the latest development snapshot of the GNOME Desktop.

1. Introduction
2. Building GNOME
3. Bootstrap the Virtual Machine
4. Setting Up the Environment
4.1. Required Packages
4.2. Selecting VMWare video driver
4.3. Directory Structure and Permissions
5. Transferring the GNOME build
6. Setting Up JHBuild
7. Fixing DBus/HAL
7.1. System Message Bus
7.2. Session Message Bus
7.3. HAL Daemon
8. Additional External Dependencies
A. Open Publication License
1. Requirements on both unmodified and modified versions
2. Copyright
3. Scope of license
4. Requirements on modified works
5. Good-practice recommendations
6. License options

1. Introduction

This document will provide steps[1] to create a virtual machine for the latest GNOME development snapshot. Why would you want to do that, you ask? Well for a number of reasons. First and foremost, the GNOME Documentation Team continually struggles with the issue of not having access to a recent development version and therefore can not provide up to date documentation. So my primary purpose in doing this is to assist them. This particular issue can be extrapolated to the Bugsquad team and possibly the translation teams as well[2]. The virtual machine can also serve a variety of other purposes... Even developers don't like to build the entire desktop, but would like to track the progress of other modules!

So without further ado, I'm going to jump into all the gory details.

2. Building GNOME

So probably the most painful part is what must be done first. You will need to build the development version of GNOME. It doesn't particularly matter whether you use GARNOME, JHBuild or the release teams' tarballs. I prefer JHBuild myself (so what if I like pain?), but any method will work fine. The reason being that once the development version is built, you simply archive up ${prefix} and transfer it to the virtual machine.

I'm not going to go into the specifics of building with any of the above mentioned tools, so you're pretty much on your own during this phase. You can get more information on different ways to build GNOME from the following links:


These instructions have only been tested by building via JHBuild. You may run into other problems if you use one of the other methods.


JHBuild tracks the dependencies between all the modules included in GNOME. This means it automatically determines the order to build modules for you. It will generally pull all of the source code from version control systems, so you will have the most up to date code available[3].


GARNOME is a set of scripts that will build GNOME from release tarballs. This method is generally easier than dealing with JHBuild as the GARNOME team works hard to provide any patches that may be necessary against the release tarballs.

Release Team Snapshots

The release team provides tarballs that you can use in conjunction with JHBuild to build an unstable “point” release of GNOME.

3. Bootstrap the Virtual Machine

Before we can transfer over our freshly built GNOME snapshot, we are going to need a virtual machine with an operating system! I'm not going to go over the specifics of creating a virtual machine, since it is relatively easy to do so using VMWare Workstation, which is a propietary product. There are other ways to create a virtual machine, although they may not necessarily follow license agreements set forth by VMWare. As there are members of the GNOME community who are paid by VMWare, I refuse to discuss those methods in this document. I will however, mention a few recommended settings when setting up your virtual machine:

  • Use bridged networking. I've found this networking mode to be the easiest, since the virtual machine will simply grab another IP address from your router. This is nice in that it makes communication between your desktop and your virtual machine easy, and also allows full access to the internet from your virtual machine.

  • Use IDE for the disk instead of SCSI. Not everyone will agree with me here, but generally I encounter fewer problems when I choose IDE.

To create the virtual machine, you are going to need to download the server installation CD[4] from Ubuntu as an .iso file. This is about 440MB for Ubuntu 6.06 and is available from Once you have this .iso image file, you can modify your virtual-machine.vmx configuration file for the virtual machine to connect the CDROM drive to this .iso image. The relevant parameters in this file are ideX:Y.present, ideX:Y.fileName, ideX:Y.deviceType and ideX:Y.startConnected, where X is 0 for the primary IDE interface, and 1 for the secondary IDE interface. The master device is indicated by setting Y to 0 or to indicate a slave device, set Y to 1. Typically you will want to use the secondary interface, and assign the CDROM as the master on this interface by substituting 1:0 for X:Y. Below is an example of part of the virtual-machine.vmx file with these parameters substituted:

ide1:0.present = "TRUE"
ide1:0.fileName = "ubuntu-server.iso"
ide1:0.deviceType = "cdrom-image"
ide1:0.autodetect = "TRUE"
ide1:0.startConnected = "TRUE"

Once you have connected the virtual machine's CDROM to the .iso image file, you can start up the virtual machine and follow the installation instructions.

  • Answer Yes to the system clock being set to UTC.

  • Make sure to write down the username and password you create.

After the installation finishes you will be asked to reboot. You need to click OK, and then hit Ctrl-Alt on your keyboatd to remove focus from the virtual machine. Instead of letting the system restart, shutdown the virtual machine after the operating system finishes shutting down, but before the BIOS starts the OS again. You will need to modify the virtual machine .vmx file to disconnect the .iso image from the CDROM drive. This can be achieved by setting the ide1:0.present parameter to FALSE.

ide1:0.present = "FALSE"

Now restart the virtual machine. It should boot up and present you with a lovely text based login screen!

Figure 1. Login Screen for Ubuntu 6.06 server edition

Login Screen for Ubuntu 6.06 server edition

Now that you can login, the first thing you will want to do is remove the CDROM as a potential source from your /etc/apt/sources.list file. To do so, perform the following steps:

  1. Run the command sudo vi /etc/apt/sources.list

  2. Enter the logged in user's password.

  3. Comment out (put a hash symbol #) in front of any lines containing the phrase “deb cdrom”.

As a final step, you will want to update Ubuntu server with the latest packages by running the command sudo apt-get update followed by sudo apt-get upgrade. This will update your package lists and then perform an upgrade for any installed packages. It may take some time.

4. Setting Up the Environment

4.1. Required Packages

Now we need to setup a minimal environment to run GNOME in. We need at least X-windows, and some basic build tools. After logging in as the user, use the sudo apt-get install command to install the following packages:

  • xserver-xorg

  • xinit

  • xfonts-base

  • xfonts-scalable

  • xfonts-100dpi

  • xfonts-75dpi

  • xfonts-utils

  • xkbutils

  • xkeyboard-config

  • xterm

  • netcat

  • cvs

  • make

  • build-essential

  • docbook

  • docbook-utils

  • docbook-xsl

  • docbook2x

  • libjpeg62

  • libpng12-0

  • libxrandr2

  • libxi6

  • libxinerama1

  • libxcursor1

  • libexif12

  • libnss3

  • libnspr4

  • libxtst6

  • gdb

  • libtiff4

  • libsdl1.2debian (ekiga)

  • libartsc0 (ekiga)

  • libaudio2 (ekiga)

  • libaa1

You will most likely be prompted for the resolution to use when X-windows is setup. I generally choose 1024x768, as most video cards nowadays support this size.

4.2. Selecting VMWare video driver

Fortunately, XOrg now includes a video driver for vmware. To select this video driver, perform the following steps:

  1. Run the command sudo vi /etc/X11/xorg.conf

  2. Find the section called “Device”.

  3. Verify that the Driver parameter has the value “vmware”. If it does not, then modify the value to be “vmware”.

    Section "Device"
            Identifier      "Name of video card/device"
            Driver          "vmware"

Optional: If you would like to test and make sure that X-windows is working, then add xterm to your .xinitrc file, and then use the startx command. Exiting the xterm application will stop the X-windows session and return you to the text based console.

$ echo "xterm" >> ~/.xinitrc
$ startx

4.3. Directory Structure and Permissions

We will be installing GNOME into the same $prefix which was used when it was built. Typically, I choose to build GNOME under the /opt directory as /opt/gnome2 or /opt/gnome-snapshot-YYYYMMDD. First, we will just create the /opt directory in the virtual machine:

$ sudo mkdir /opt
$ sudo chgrp users /opt
$ sudo chmod 775 /opt

Next, you will want to add the normal user (defined during installation) to the users group in the /etc/group file. The reason is because you will then have full access over the /opt directory, as well as any other users that are created and belong to this group. To add a user to the users group, simply append the username to the end of the line in the /etc/group file that starts with the group “users”. You must re-login for the changes to take effect.

You can verify you are part of the users group by running the groups command:

$ groups
gdpuser adm dialout cdrom floppy audio dip video plugdev users lpadmin scanner admin

Finally, you can create the $prefix directory under /opt:

$ mkdir -p /opt/gnome-prefix

5. Transferring the GNOME build

So at this point, we need to transfer the build of GNOME from your development computer, to the virtual machine. Since one of our goals is to keep the size of the virtual machine as small as possible (to ease distribution), we don't want to compress the /opt/gnome-prefix directory and transfer that to the virtual-machine; That will result in extra space being allocated in the virtual-machine's disk image, since both the compressed archive and the uncompressed versions will have to exist, even if briefly.

To get around this, my favorite method is to use the netcat command. This command allows you to pipe arbitrary data over the network.

The first step is to determine the IP address of the virtual machine. You can do this using the /sbin/ifconfig -a command.

  1. Type ifconfig -a

  2. Search for the IP Address in the form aaa.bbb.ccc.ddd in the section eth0.

You will see output similar to Example 1, “Example of ifconfig -a output”.

Example 1. Example of ifconfig -a output

$ ifconfig -a
eth0      Link encap:Ethernet  HWaddr 00:E0:18:D5:2A:AE 1
          inet addr: 2 Bcast:  Mask: 
          inet6 addr: fe80::2e0:18ff:fed5:2aae/64 Scope:Link
          RX packets:43723 errors:0 dropped:0 overruns:0 frame:0
          TX packets:27405 errors:0 dropped:0 overruns:0 carrier:0
          collisions:0 txqueuelen:1000
          RX bytes:52153543 (49.7 MiB)  TX bytes:2124276 (2.0 MiB)

lo        Link encap:Local Loopback
          inet addr:  Mask:
          inet6 addr: ::1/128 Scope:Host
          UP LOOPBACK RUNNING  MTU:16436  Metric:1
          RX packets:56 errors:0 dropped:0 overruns:0 frame:0
          TX packets:56 errors:0 dropped:0 overruns:0 carrier:0
          collisions:0 txqueuelen:0
          RX bytes:3210 (3.1 KiB)  TX bytes:3210 (3.1 KiB)

The address listed after the text HWaddr is the MAC Address of the virtual machine.


The address listed after the text inet addr: is the IP Address of the virtual machine.

Next, start listening for data on port 1599 on the virtual machine, and pipe the output to the tar utility in extract mode.

cd /opt
nc -l -p 1599 | tar xvf -

Then, start streaming a tar archive over the network on the development machine. You will see a list of all the files being transferred in both the development machine and the virtual machine. This may take some time (usually around 15-20 minutes for me).

cd /opt
tar cvf - gnome-prefix/ | nc vm-ip-address 1599

It's a bit difficult to tell when the transfer finishes, as netcat will wait for more input. Once the list of files stops printing to the terminal, the transfer has probably finished and you can use Ctrl-C on the development machine to stop netcat.

6. Setting Up JHBuild

The next task is to setup JHBuild within the virtual-machine (Don't worry, we're not going to actually compile anything!). The reason jhbuild is necessary is because it sets up the environment to run GNOME from /opt/gnome-prefix.

To get a copy of JHBuild, check out the current repository from the GNOME CVS servers. You can checkout the source in your user's home directory.

cvs -d co jhbuild
cd jhbuild
bindir=/usr/bin sudo make -e install

Next, we want to create a default configuration file for JHBuild at /etc/jhbuild.conf. Run the sudo vi /etc/jhbuild.conf command, and put the following line in the file (replacing gnome-prefix with your actual prefix):

prefix = '/opt/gnome-prefix'

7. Fixing DBus/HAL

Currently, Ubuntu server is not configured to run the DBus system message bus and hal at startup. In order for lots of things to function correctly in GNOME, a system message bus, a session message bus, and the hald daemon need to be running. We will start out getting the system message bus functioning properly, since it is probably the most important.

7.1. System Message Bus

The first task is to create some init scripts to run the dbus system daemon when the operating system starts. Since we simply copied the GNOME installation from one machine to another, there are no scripts in the /etc/init.d directory to start the system daemon. So, I will usually copy the version of this script from my development machine to the virtual-machine.

  1. Install openssh on the virtual machine using the command sudo apt-get install openssh.

  2. From the development machine, sftp to the virtual machine and upload the dbus script.

    $ sftp gdpuser@
    Connecting to
    gdpuser@'s password:
    sftp> put /etc/init.d/dbus
    Uploading /etc/init.d/dbus to /home/gdpuser/dbus
    /etc/init.d/dbus                                                                                         100% 2557     2.5KB/s   00:00
    sftp> quit
  3. Copy the script to /etc/init.d/dbus on the virtual machine.

    $ sudo cp ~/dbus /etc/init.d/dbus
  4. Modify the contents of the init script to point to the correct location of the dbus-daemon application, and the correct locations for the “PID” directory and the “event” directory.

  5. Make the script executable.

    $ sudo chmod 755 /etc/init.d/dbus
  6. Add the messagebus user to the /etc/passwd file using the sudo vi /etc/passwd command. The line that I use is given below.

  7. Add the messagebus group to the /etc/group file using the sudo vi /etc/group command. The line that I use is given below.

  8. Make a symbolic link in the /etc/rc2.d directory to the init script, so that the system message bus will be started when you reboot.

    $ cd /etc/rc2.d/ && sudo ln -s ../init.d/dbus S12dbus
  9. Start the system message bus!

    $ sudo /etc/init.d/dbus start

7.2. Session Message Bus

The session message bus is thankfully quite a bit easier. We modify the ~/.xinitrc file to use the dbus-launch command, which sets the appropriate environment variables, launches the session message bus and then launches the command given as an argument. The following will do the trick:

$ echo 'exec jhbuild --file=/etc/jhbuild.conf run dbus-launch gnome-session' > ~/.xinitrc

Now, whenever you use the startx command, you will get a session message bus automatically, and gnome-session will take care of starting GNOME.

7.3. HAL Daemon

Our last task is to get the HAL daemon working. Without HAL running, certain applications such as nautilus or gnome-power-manager will not be able to obtain information about your underlying hardware.

  1. From the development machine, sftp to the virtual machine and upload the 20hal script.

    $ sftp gdpuser@
    Connecting to
    gdpuser@'s password:
    sftp> put /etc/dbus-1/event.d/20hal
    Uploading /etc/dbus-1/event.d/20hal to /home/gdpuser/20hal
    /etc/dbus-1/event.d/20hal                                                                                100% 1901     1.9KB/s   00:00
    sftp> quit
  2. Create the directory /opt/gnome-prefix/etc/dbus-1/event.d

    $ mkdir /opt/gnome-prefix/etc/dbus-1/event.d
  3. Copy the script to /opt/gnome-prefix/etc/dbus-1/event.d

    $ cp ~/20hal /opt/gnome-prefix/etc/dbus-1/event.d
  4. Modify the contents of the script to point to the correct location of the hald application, and the correct location of the “PID” directory.

  5. Make the script executable.

    $ chmod 755 /opt/gnome-prefix/etc/dbus-1/event.d/20hal
  6. Add the haldaemon user to the /etc/passwd file using the sudo vi /etc/passwd command. The line that I use is given below.

    haldaemon:x:111:111:Hardware abstraction layer,,,:/var/run/hal:/bin/false
  7. Add the haldaemon group to the /etc/group file using the sudo vi /etc/group command. The line that I use is given below.


8. Additional External Dependencies

You will undoubtably find that when you try to launch a particular GNOME application, you receive an error about being unable to load a library file. This is because some of the modules built (as part of JHBuild, GARNOME, etc...) use external dependencies which are not compiled and installed by JHBuild. These libraries will have to downloaded from Ubuntu's package repository to install the necessary libraries. Only then will you be able to run that particular application.

A classic example of an external dependency are the mozilla/firefox libraries. Many applications that are part of GNOME use the library. When you compile these applications, you have the option to use the development packages from your distribution. Therefore, if you compiled the help application, yelp, using the firefox-dev package from ubuntu, you will most likely have to install the firefox-dev application on the virtual machine as well.

The telltale sign that a library is missing is the following error message:

$ yelp &
unable to load library No such file or directory

On the development machine, you can find the library which is missing by using the dpkg -S command to search for the package that contains this library. Then, it's just the simple task of using apt-get to install that package on the virtual machine!

A. Open Publication License

1. Requirements on both unmodified and modified versions

The Open Publication works may be reproduced and distributed in whole or in part, in any medium physical or electronic, provided that the terms of this license are adhered to, and that this license or an incorporation of it by reference (with any options elected by the author(s) and/or publisher) is displayed in the reproduction.

Proper form for an incorporation by reference is as follows:

Copyright (c) <year> by <author's name or designee>. This material may be distributed only subject to the terms and conditions set forth in the Open Publication License, vX.Y or later (the latest version is presently available at

The reference must be immediately followed with any options elected by the author(s) and/or publisher of the document (see section VI).

Commercial redistribution of Open Publication-licensed material is permitted.

Any publication in standard (paper) book form shall require the citation of the original publisher and author. The publisher and author's names shall appear on all outer surfaces of the book. On all outer surfaces of the book the original publisher's name shall be as large as the title of the work and cited as possessive with respect to the title.

2. Copyright

The copyright to each Open Publication is owned by its author(s) or designee.

3. Scope of license

The following license terms apply to all Open Publication works, unless otherwise explicitly stated in the document.

Mere aggregation of Open Publication works or a portion of an Open Publication work with other works or programs on the same media shall not cause this license to apply to those other works. The aggregate work shall contain a notice specifying the inclusion of the Open Publication material and appropriate copyright notice.

SEVERABILITY. If any part of this license is found to be unenforceable in any jurisdiction, the remaining portions of the license remain in force.

NO WARRANTY. Open Publication works are licensed and provided "as is" without warranty of any kind, express or implied, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose or a warranty of non-infringement.

4. Requirements on modified works

All modified versions of documents covered by this license, including translations, anthologies, compilations and partial documents, must meet the following requirements:

  1. The modified version must be labeled as such.

  2. The person making the modifications must be identified and the modifications dated.

  3. Acknowledgement of the original author and publisher if applicable must be retained according to normal academic citation practices.

  4. The location of the original unmodified document must be identified.

  5. The original author's (or authors') name(s) may not be used to assert or imply endorsement of the resulting document without the original author's (or authors') permission.

5. Good-practice recommendations

In addition to the requirements of this license, it is requested from and strongly recommended of redistributors that:

  1. If you are distributing Open Publication works on hardcopy or CD-ROM, you provide email notification to the authors of your intent to redistribute at least thirty days before your manuscript or media freeze, to give the authors time to provide updated documents. This notification should describe modifications, if any, made to the document.

  2. All substantive modifications (including deletions) be either clearly marked up in the document or else described in an attachment to the document.

  3. Finally, while it is not mandatory under this license, it is considered good form to offer a free copy of any hardcopy and CD-ROM expression of an Open Publication-licensed work to its author(s).

6. License options

The author(s) and/or publisher of an Open Publication-licensed document may elect certain options by appending language to the reference to or copy of the license. These options are considered part of the license instance and must be included with the license (or its incorporation by reference) in derived works.

  1. To prohibit distribution of substantively modified versions without the explicit permission of the author(s). "Substantive modification" is defined as a change to the semantic content of the document, and excludes mere changes in format or typographical corrections.

    To accomplish this, add the phrase `Distribution of substantively modified versions of this document is prohibited without the explicit permission of the copyright holder.' to the license reference or copy.

  2. To prohibit any publication of this work or derivative works in whole or in part in standard (paper) book form for commercial purposes is prohibited unless prior permission is obtained from the copyright holder.

    To accomplish this, add the phrase 'Distribution of the work or derivative of the work in any standard (paper) book form is prohibited unless prior permission is obtained from the copyright holder.' to the license reference or copy.

[1] OK, it's little more than a structured set of notes ;-)

[2] Although, the current process for creating the virtual machine may make it undesirable for testers to submit bugs against the core modules since bugs may be specific to the distributor's VM.

[3] This is not always true, sometimes JHBuild will download release tarballs or use a branch other than the main branch in the version control system

[4] The reason we use the server installation CD is because it provides a minimal installation that doesn't require much disk space.