Xapi Project's XenAPI Management Toolstack

Xen API (or xapi) is a management stack that configures and controls Xen-enabled hosts and resource pools, and coordinates resources within the pool. Xapi exposes the Xen API interface for many languages and is a component of the XenServer project. Xen API is written mostly in OCaml 4.07.

Xapi is the main component produced by the Linux Foundation's Xapi Project.

Build and Install

To build xen-api from source, we recommend using opam with the xs-opam repository (further explanation in its readme).

1. Install opam and git with your package manager.

2. Clone this repo and work from its root.

   git clone https://github.com/xapi-project/xen-api && cd xen-api

3. Figure out which version of ocaml-base-compiler to use.

   • Go to this xs-opam file, and look for OCAML_VERSION_FULL.

   • Run that line, e.g.:

     export OCAML_VERSION_FULL="4.14.2"

4. Setup opam with your environment (i.e. switch).

   opam init
   opam switch create xen-api ocaml-base-compiler.$OCAML_VERSION_FULL
   # This basically "jumps you into" the environment you just created:
   eval $(opam env --switch=xen-api --set-switch)

5. Get the Recommended Packages.

   # Add the xs-opam library as the main repo to check for versions at:
   opam repo add xs-opam https://github.com/xapi-project/xs-opam.git
   # Remove the default, because how it handles version conflicts is different:
   opam repo remove default
   # (NOT needed with opam>=2.1.0) Have opam now figure out what versions of each package to use:
   opam pin --yes add . --no-action

6. Install all the Packages.

   opam install xs-toolstack
   
   # Install developer tools (utop, ocamlformat, ocaml-lsp-server, etc.)
   opam install dev-tools
   
   # Update the current switch. (You're already on the correct one, just refresh it).
   eval $(opam env)

7. Build xen-api.

   ./configure
   make
   make test

The binaries should now be in ./_build/install/default/bin!

Working With Several Branches

When working on this repository as a regular contributor, one generally has to work with several branches: the master branch and lifecycle-management (LCM) branches. The following two recommendations make such workflows easier:

• Create one Opam switch per branch you work on. This is because different branches of this repository may have different dependencies. In particular, this means that different branches may have to get their dependencies from different branches of the xs-opam repository. As repository definitions are global to Opam rather than local to a given switch, if a branch of this repository needs to get its dependencies from a branch other than master in xs-opam, then that other branch will have to be added with a different repository name (see example below).

• Use git worktree to make sure that different branches are checked out at different locations on your file system. This is because pinning makes it so that Opam expects certain dependencies to be available at certain paths. When not using work trees, the same path can refer to different versions of a same file as the checked out branch changes.

For instance, assuming the 26.1-lcm branch, which takes its dependencies from the 6.99-lcm branch of the xs-opam repository, has been checked out in a Git work tree somewhere on your file system, here is how to proceed to create an Opam switch that will work for this branch:

export OCAML_VERSION_FULL="4.14.2"
opam switch create xen-api-26.1-lcm ocaml-base-compiler.$OCAML_VERSION_FULL
eval $(opam env --switch=xen-api-26.1-lcm --set-switch)
opam repo add xs-opam-6.99-lcm "https://github.com/xapi-project/xs-opam.git#6.99-lcm"
opam repo remove default
opam install xs-toolstack

Working From a Fork

If you are working from within a clone of a fork of this repository, you will need tags from the upstream repository in order to produce a build with the correct versioning string.

To fetch these tags, you must ensure that this repository is known to git (as a remote, often called upstream) and then you can fetch the tags as follows:

git remote add upstream https://github.com/xapi-project/xen-api
git fetch upstream --tags

You can check if this has been successful by invoking git describe.

You can then push these tags to your remote repository to ensure they are cloned in future:

git push origin --tags

Contributions

To contribute changes to xen-api, please fork the repository on GitHub, and then submit a pull request.

It is required to add a Signed-off-by: as a Developers Certificate of Origin. It certifies the patch's origin and is licensed under an appropriate open-source licence to include it in Xapi: https://git-scm.com/docs/git-commit#Documentation/git-commit.txt---signoff

For more detailed guidelines on what makes a good contribution, see CONTRIBUTING.

Discussions

Discussions can be started at https://github.com/xapi-project/xen-api/discussions

Issues

Issues can be raised at https://github.com/xapi-project/xen-api/issues

Licensing

This software is licensed under the GNU LGPLv2 license. Please see the LICENSE file for more information.