Merge pull request #5593 from contificate/update-readme

Update README with different build instructions

README.markdown

@@ -4,7 +4,7 @@ Xapi Project's XenAPI Management Toolstack
 ![Build](https://github.com/xapi-project/xen-api/actions/workflows/main.yml/badge.svg?branch=master)
 
 Xen API (or xapi) is a management stack that configures and controls
-Xen-enabled hosts and resource pools, and co-ordinates resources
+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](http://caml.inria.fr/ocaml/)
@@ -16,31 +16,31 @@ Xapi is the main component produced by the Linux Foundation's
 Build and Install
 -----------------
 
-To build xen-api from source, we recommend using [opam](https://opam.ocaml.org/doc/Manual.html) with the [xs-opam](https://github.com/xapi-project/xs-opam) repository (farther explanation in its [readme](https://github.com/xapi-project/xs-opam/blob/master/README.md)).
+To build xen-api from source, we recommend using [opam](https://opam.ocaml.org/doc/Manual.html) with the [xs-opam](https://github.com/xapi-project/xs-opam) repository (further explanation in its [readme](https://github.com/xapi-project/xs-opam/blob/master/README.md)).
 
 1) Install `opam` and `git` with your package manager.
 
-2) Clone this repo, and work from it's root.
+2) Clone this repo and work from its root.
 
     ```bash
     git clone https://github.com/xapi-project/xen-api && cd xen-api
     ```
 
-3) Figure out what version of ocaml-base-compiler to use.
+3) Figure out which version of ocaml-base-compiler to use.
 
-    - Go to [this xs-opam file](https://raw.githubusercontent.com/xapi-project/xs-opam/master/tools/xs-opam-ci.env), and look for "OCAML_VERSION_FULL"
-    - Run that line, i.e:
+    - Go to [this xs-opam file](https://raw.githubusercontent.com/xapi-project/xs-opam/master/tools/xs-opam-ci.env), and look for `OCAML_VERSION_FULL`.
+    - Run that line, e.g.:
 
         ```bash
-        export OCAML_VERSION_FULL="4.10.1"
+        export OCAML_VERSION_FULL="4.14.1"
         ```
 
-4) Setup opam, with your Enviornment (i.e switch).
+4) Setup opam with your environment (i.e. switch).
 
     ```bash
     opam init
     opam switch create xen-api ocaml-base-compiler.$OCAML_VERSION_FULL
-    # This basically "jumps you into" the enviornment you just created:
+    # This basically "jumps you into" the environment you just created:
     eval $(opam env --switch=xen-api --set-switch)
     ```
 
@@ -58,12 +58,7 @@ To build xen-api from source, we recommend using [opam](https://opam.ocaml.org/d
 6) Install all the Packages.
 
     ```bash
-    PACKAGES="xapi-cli-protocol xapi-client xapi-consts xapi-datamodel xapi-types xapi xe xen-api-sdk xen-api-client xen-api-client-lwt xen-api-client-async xapi-rrdd xapi-rrdd-plugin xapi-rrd-transport xapi-rrd-transport-utils rrd-transport rrdd-plugin rrdd-plugins rrddump gzip http-lib pciutil safe-resources sexpr stunnel uuid xapi-compression xml-light2 zstd vhd-tool xs-toolstack"
-
-    # NOT needed with opam>=2.1.0) Install all the dependencies (Including OS):
-    opam --yes depext --yes -u $PACKAGES # The first '--yes' is to install depext itself
-    # Install the Packages finally:
-    opam install $PACKAGES --yes --deps-only --with-test -v
+    opam install xs-toolstack
     # Update the current switch. (You're already on the correct one, just refresh it).
     eval $(opam env)
     ```
@@ -78,6 +73,29 @@ To build xen-api from source, we recommend using [opam](https://opam.ocaml.org/d
 
 The binaries should now be in `./_build/install/default/bin`!
 
+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:
+
+```bash
+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:
+
+```bash
+git push origin --tags
+```
+
 Contributions
 -------------