Build Instructions 0.95

This document is intended for developers who want to build the oVirt components from scratch. If you just want to see how it works, just follow the install instructions. The below steps assume a familiarity with Linux development tools.

Throughout this document, we give commands to type at a shell prompt. By convention, if a command is meant to be run by a non-privileged user, we will precede it with a $ prompt. If a command is meant to be run by the root user, we will precede it with a #.

Source Repositories

Source code is contained in the following source repositories:

  1. ovirt-server: RPMs that provide oVirt Server Suite functionality
  2. ovirt-node: RPMs that provide oVirt node functionality
  3. ovirt-node-image: RPMs that contain LiveCD ISO image and PXE images of the oVirt Node which uses the ovirt-node RPM
  4. ovirt-recipe: RPM that contains a recipe for creating the oVirt Appliance using the Thincrust tools.
  5. ovirt-appliance: RPM that contains a Fedora appliance OS based on the ovirt-recipe RPM
  6. ovirt-release: RPM that contains yum repo configuration file for ovirt.org repositories and developer convenience scripts
  7. ovirt-docs: RPMs that contain documentation for the oVirt project

All of these source repositories are available via git web interface. It is not necessary to manually clone each of these repositories. Please follow the instructions below for using the ovirt.mk Makefile provided in the ovirt-build RPM for retrieving the repositories.

Prerequisites

There are a few prerequisites to building the oVirt components:

  1. Fedora 9 installed with latest updates.
  2. The user running the build does not need to be root, however it does need to have passwordless sudo as root access. This is because the ovirt-appliance and ovirt-node-image repositories use livecd-creator which presently requires root.
  3. Hardware virtualization is not necessary for building, but if you wish to run the oVirt Appliance on the same machine you are building on then the host machine should have hardware virtualization capabilities
  4. The user must have valid ~/.rpmmacros set up if not running the build as root. A minimal ~/.rpmmacros should contain: 
    %_topdir      %(echo $HOME)/rpmbuild
    This will put your rpmbuild directory in ~/rpmbuild. Adjust the destination to your liking. In that directory you'll need to run: 
    mkdir BUILD RPMS SOURCES SPECS SRPMS
  5. The Node is built with SELinux enabled by default. This requires build host to also have SELinux enabled in Permissive mode. If SELinux is not enabled, the build will fail. If it is enabled but in Enforcing mode the build will temporarily put the host into Permissive mode and then toggle back to Enforcing

    NOTE: The Node does not require SELinux to be enabled, though it is by default. This behavior can be toggled in the Node kickstart file in the ovirt-node-image repository.

Getting Started

In order to build oVirt you will need several RPMs from the ovirt.org repositories. To get these, install the ovirt-release RPM which provides a yum configuration file. Because this process updates libvirt and you'll need to restart libvirt at the end, shut down any existing virtual machines before proceeding.

  1. Install the ovirt-release RPM to get yum configured: 
    # rpm -ivh http://ovirt.org/repos/ovirt/9/ovirt-release-LATEST.fc9.noarch.rpm
  2. Update any existing RPMs with newer RPMs available in the oVirt repository: 
    # yum update --enablerepo=ovirt
  3. Install additional RPMs necessary for building the components. Each component has a different set of required RPMs so use one or more of the following commands:
    1. Common build requirements 
      # yum install --enablerepo=ovirt ovirt-build
    2. ovirt-release build requirements - No additional RPMs required
    3. ovirt-server build requirements 
      # yum install --enablerepo=ovirt ruby ruby-devel rubygem-rake rubygem-gettext ruby-gettext-package
    4. ovirt-node build requirements 
      # yum install --enablerepo=ovirt pkgconfig libvirt-devel dbus-devel hal-devel hardlink selinux-policy-devel
    5. ovirt-node-image build requirements 
      # yum install --enablerepo=ovirt livecd-tools syslinux
    6. ovirt-recipe build requirements - No additional RPMs required
    7. ovirt-appliance build requirements 
      # yum install --enablerepo=ovirt appliance-tools appliance-os syslinux qemu-img wget
    8. ovirt-docs build requirements 
      # yum install --enablerepo=ovirt publican publican-ovirt
      NOTE: If you have java-1.5.0-gcj-devel installed you may have Java classpath issues. It is recommended that you uninstall that package to build the documentation successfully.

Using the oVirt Makefile

the ovirt-build RPM provides a Makefile to assist developers with building from source.

This makefile provides a convenient way for a developer to clone/update all of the git repositories and to do an end-to-end build. In addition, it can be used to just build specific components rather than the entire system.

The makefile also uses several environment variables to alter its behavior:

  1. OVIRT_BRANCH - This specifies which branch to use in git. Default is 'next', which is for the latest development code. Stable releases are in the 'master' branch.
  2. FEDORA_URL - This provides a local mirror to use for Fedora repositories. Default is to use the remote mirrorlist.
  3. OVIRT_CACHE_DIR - The build of ovirt-node-image and ovirt-appliance requires RPMs from Fedora repositories. This is the location of a cache directory for storing files used in those builds. Default is to use ~/ovirt-cache
  4. SUBDIRS - The list of repositories to build. This can be overridden if you only want to work with a subset of the repositories available. The default set is defined in the ovirt.mk file in the ovirt-release repository.

To build the entire system:

  1. Prepare your development directory and check out the git repositories: 
    $ mkdir $HOME/ovirt
$ cd $HOME/ovirt
$ make -f /usr/share/ovirt-build/ovirt.mk update
  2. Create a symlink to the release/ovirt.mk makefile to use in the top level build directory: 
    $ ln -s release/ovirt.mk Makefile
  3. Run a build of all components: 
    $ make build
    This step will take a quite a while to complete the first time you run it. Subsequent runs should take much less time, since the downloaded packages are stored in a cache directory.

The following are some of the top level make targets in ovirt.mk that are useful for developers:

  1. update - This target refreshes all of the repository checkouts with git pull and switches to the branch specified in OVIRT_BRANCH
  2. build - Does a build of all repositories
  3. update-host - Does yum localinstall of locally build RPMS for ovirt-appliance, ovirt-release and ovirt-build
  4. status, diff, branch, show-branch - Runs the corresponding git command on each of the repository directories

Following a successful build the generated RPMs for each of the git repositories will be placed into $OVIRT_CACHE_DIR/ovirt. A symlink is created in the build directory (for example: ~/ovirt/rpms).

After the build has finished, update your host with the new appliance, release and build RPMs. This can be done with the following command:

$ make update-host

NOTE: This command (like the builds for ovirt-appliance and ovirt-node-image) requires passwordless sudo as root access since it runs the yum command.

Follow the instructions on the install page for starting up the appliance and nodes.

Once the appliance is booted, you can start fake oVirt Nodes on the host machine:

# virsh start node3
# virsh start node4
# virsh start node5

The fake oVirt Nodes are intended for development and testing usage. They have very limited amounts of memory (512MB RAM each) and cannot utilize hardware accelerated virtualization. Provisioning a real operating system on these fake Nodes is not recommended. If you only have a single hardware virtualization capable machine, you can manage guests directly on that machine from the appliance.

Each fake Node has a 128MB virtual disk associated with it for use in testing the various node installation and configuration persistence options. Each of the above nodes has slightly different boot semantics:

  1. node3 - Boots from PXE and stores critical configuration data on the provided virtual disk.
  2. node4 - Boots from PXE and installs the Node onto the hard disk so that future boots can be directly from disk instead of from the network
  3. node5 - Does not utilize the disk at all. This node is completely stateless