pkgs/by-name/xe/xen/README.md

   1 <p align="center">
   2   <a href="https://xenproject.org/">
   3     <picture>
   4       <source
   5         media="(prefers-color-scheme: light)"
   6         srcset="https://downloads.xenproject.org/Branding/Logos/Green+Black/xen_project_logo_dualcolor_2000x832.png">
   7       <source
   8         media="(prefers-color-scheme: dark)"
   9         srcset="https://xenproject.org/wp-content/uploads/sites/79/2018/09/logo_xenproject.png">
  10       <img
  11         src="https://downloads.xenproject.org/Branding/Logos/Green+Black/xen_project_logo_dualcolor_2000x832.png"
  12         width="512px"
  13         alt="Xen Project Logo">
  14     </picture>
  15   </a>
  16 </p>
  17
  18 # Xen Project Hypervisor <a href="https://xenproject.org/"><img src="https://downloads.xenproject.org/Branding/Mascots/Xen-Fu-Panda-2000px.png" width="48px" align="top" alt="Xen Fu Panda"></a>
  19
  20 This directory begins the [Xen Project Hypervisor](https://xenproject.org/) build process.
  21
  22 Some other notable packages that compose the Xen Project Ecosystem include:
  23
  24 - `ocamlPackages.xenstore`: Mirage's `oxenstore` implementation.
  25 - `ocamlPackages.vchan`: Mirage's `xen-vchan` implementation.
  26 - `ocamlPackages.xenstore-tool`: XAPI's `oxenstore` utilities.
  27 - `xen-guest-agent`: Guest drivers for UNIX domUs.
  28 - `win-pvdrivers`: Guest drivers for Windows domUs.
  29 - `xtf`: The Xen Test Framework.
  30
  31 ## Updating
  32
  33 ### Manually
  34
  35 1. [Update](https://xenbits.xenproject.org/gitweb/) the `package.nix` file for
  36    the latest branch of Xen.
  37    - Do not forget to set the `branch`, `version`, and `latest` attributes.
  38    - The revisions are preferably commit hashes, but tag names are acceptable
  39      as well.
  40 1. Make sure it builds.
  41 1. Use the NixOS module to test if dom0 boots successfully on the new version.
  42 1. Make sure the `meta` attributes evaluate to something that makes sense. The
  43    following one-line command is useful for testing this:
  44
  45    ```console
  46    echo -e "\033[1m$(nix eval .#xen.meta.description --raw 2> /dev/null)\033[0m\n\n$(nix eval .#xen.meta.longDescription --raw 2> /dev/null)"
  47    ```
  48
  49 1. Run `xtf --all --host` as root when booted into the Xen update, and make
  50    sure no important tests fail.
  51 1. Clean up your changes and commit them, making sure to follow the
  52    [Nixpkgs Contribution Guidelines](../../../../CONTRIBUTING.md).
  53 1. Open a PR and await a review from the current maintainers.
  54
  55 ## Features
  56
  57 ### Generic Builder
  58
  59 `buildXenPackage` is a helpful utility capable of building Xen when passed
  60 certain attributes. The `package.nix` file on this directory includes all
  61 important attributes for building a Xen package with Nix. Downstreams can
  62 pin their Xen revision or include extra patches if the default Xen package
  63 does not meet their needs.
  64
  65 ### EFI
  66
  67 Building `xen.efi` requires an `ld` with PE support.[^2]
  68
  69 We use a `makeFlag` to override the `$LD` environment variable to point to our
  70 patched `efiBinutils`. For more information, see the comment in `pkgs/build-support/xen/default.nix`.
  71
  72 > [!TIP]
  73 > If you are certain you will not be running Xen in an x86 EFI environment, disable
  74 the `withEFI` flag with an [override](https://nixos.org/manual/nixpkgs/stable/#chap-overrides)
  75 to save you the need to compile `efiBinutils`.
  76
  77 ## Security
  78
  79 We aim to support the **latest** version of Xen at any given time.
  80 See the [Xen Support Matrix](https://xenbits.xen.org/docs/unstable/support-matrix.html)
  81 for a list of versions. As soon as a version is no longer the newest, it should
  82 be removed from Nixpkgs (`master`). If you need earlier versions of Xen, consider
  83 building your own Xen by following the instructions in the **Generic Builder**
  84 section.
  85
  86 > [!CAUTION]
  87 > Pull requests that introduce XSA patches
  88 should have the `1.severity: security` label.
  89
  90 ### Maintainers
  91
  92 Xen is a particularly complex piece of software, so we are always looking for new
  93 maintainers. Help out by [making and triaging issues](https://github.com/NixOS/nixpkgs/issues/new/choose),
  94 [sending build fixes and improvements through PRs](https://github.com/NixOS/nixpkgs/compare),
  95 updating the branches, and [patching security flaws](https://xenbits.xenproject.org/xsa/).
  96
  97 We are also looking for testers, particularly those who can test Xen on AArch64
  98 machines. Open issues for any build failures or runtime errors you find!
  99
 100 ## Tests
 101
 102 So far, we only have had one simple automated test that checks for
 103 the correct `pkg-config` output files.
 104
 105 Due to Xen's nature as a type-1 hypervisor, it is not a trivial matter to design
 106 new tests, as even basic functionality requires a machine booted in a dom0
 107 kernel. For this reason, most testing done with this package must be done
 108 manually in a NixOS machine with `virtualisation.xen.enable` set to `true`.
 109
 110 Another unfortunate thing is that none of the Xen commands have a `--version`
 111 flag. This means that `testers.testVersion` cannot ascertain the Xen version.
 112 The only way to verify that you have indeed built the correct version is to
 113 boot into the freshly built Xen kernel and run `xl info`.
 114
 115 <p align="center">
 116   <a href="https://xenproject.org/">
 117     <img
 118       src="https://downloads.xenproject.org/Branding/Mascots/Xen%20Big%20Panda%204242x3129.png"
 119       width="96px"
 120       alt="Xen Fu Panda">
 121   </a>
 122 </p>
 123
 124 [^1]: We also produce fake `git`, `wget` and `hostname` binaries that do nothing,
 125       to prevent the build from failing because Xen cannot fetch the sources that
 126       were already fetched by Nix.
 127 [^2]: From the [Xen Documentation](https://xenbits.xenproject.org/docs/unstable/misc/efi.html):
 128       > For x86, building `xen.efi` requires `gcc` 4.5.x or above (4.6.x or newer
 129       recommended, as 4.5.x was probably never really tested for this purpose)
 130       and `binutils` 2.22 or newer. Additionally, the `binutils` build must be
 131       configured to include support for the x86_64-pep emulation (i.e.
 132       `--enable-targets=x86_64-pep` or an option of equivalent effect should be
 133       passed to the configure script).