sync master to configure ssh (xapi-project#6282)

Resolved onflicts:
	ocaml/idl/datamodel_errors.ml
	ocaml/xapi-consts/api_errors.ml

Author: BengangY

.github/workflows/generate-and-build-sdks.yml

@@ -168,6 +168,7 @@ jobs:
         run: |
           dotnet test source/XenServerTest `
           --disable-build-servers `
+          -p:DefineConstants=BUILD_FOR_TEST `
           --verbosity=normal
 
       - name: Build C# SDK

.github/workflows/main.yml

@@ -1,7 +1,11 @@
 name: Build and test
 
 on:
+  # When only Hugo docs change, this workflow is not required:
   push:
+    paths-ignore:
+      - 'doc/**'
+      - '.github/workflows/hugo.yml'
   pull_request:
   schedule:
     # run daily, this refreshes the cache

.github/workflows/other.yml

@@ -1,7 +1,11 @@
 name: Build and test (other)
 
 on:
+  # When only Hugo docs change, this workflow is not required:
   push:
+    paths-ignore:
+      - 'doc/**'
+      - '.github/workflows/hugo.yml'
   pull_request:
   schedule:
     # run daily, this refreshes the cache

.github/workflows/release.yml

@@ -20,13 +20,11 @@ jobs:
           python-version: "3.x"
 
       - name: Install build dependencies
-        run: |
-          pip install build
-          sudo apt-get install ocaml dune libfindlib-ocaml-dev libdune-ocaml-dev libcmdliner-ocaml-dev
+        run: pip install build
 
       - name: Generate python package for XenAPI
         run: |
-          ./configure --xapi_version=${{ github.ref_name }}
+          echo "export XAPI_VERSION=${{ github.ref_name }}" > config.mk
           make python
 
       - name: Store python distribution artifacts

doc/README.md

@@ -1,17 +1,104 @@
-Quick start guide:
+# Quick start guide
+
+- Visit <https://xapi-project.github.io/new-docs/> to view the current documentation.
+
+## Required software
+
+The docs use Hugo and the [Hugo Relearn theme](https://mcshelby.github.io/hugo-theme-relearn),
+an enhanced fork of the popular Hugo Learn theme.
+
+### Supported versions of Hugo and the Hugo Relearn theme
+
+Hugo Relearn 7.3.2 is currently used (defined by a git tag in `doc/go.mod`).
+
+- The minimum Hugo version required by the Relearn theme is 0.126.0.
+- The current Ubuntu `snap` (which provides 0.142.0) also works.
+
+## Installation
+
+- Install Hugo 0.126 or newer (required by the Hugo Relearn theme)
+  follow the guidance on <https://gohugo.io/installing>.
+  You'll need to install Go as well: see <https://go.dev/>
+  - On Ubuntu, use the `snap` package:
+    - `sudo snap install hugo` installs the current version
+      `apt-get install hugo` would install a version that is too old,
+      (this applies up to Ubuntu 24.04)
+
+  - To install Hugo from source, you need a recent `golang-1.2x` compiler:
+    - On Ubuntu 22.04, this can be done with:
+
+      ```bash
+      sudo apt install golang-1.23-go
+      # Add it to your path, assuming your .local/bin/ is early in your PATH:
+      ln -s /usr/lib/go-1.23/bin/go ~/.local/bin/go
+      go version
+      go install github.com/gohugoio/[email protected]
+      ```
+
+## Development
 
-- Visit https://xapi-project.github.io/new-docs/ to view the current documentation.
-- Install Hugo; follow the guidance on https://gohugo.io/getting-started/installing.
-  You'll need Go as well: see https://go.dev/
-  - On Ubuntu 22.04 and older, use `sudo snap install hugo` to get the needed newer version of `hugo`.
 - Run a local server: `hugo server`
-- Open a browser at http://127.0.0.1:1313/new-docs/
+- Open a browser at <http://127.0.0.1:1313/new-docs/>
 - Add content to `doc/content/`:
   - Documents are written in Markdown.
-  - Please wrap lines in paragraphs to make review and diffs easier to read.
-  - The menu hierarchy comes mostly from the directory structure in `content/`.
+  - Please wrap lines in paragraphs to make reviews more manageable.
+  - The menu hierarchy comes mainly from the directory structure in `content/`.
   - A file called `_index.md` is needed in a directory to define a new level in the menu.
-    - To set the page title which is also used for the main menu,
+    - To set the page title,
       [use the front matter](https://gohugo.io/content-management/front-matter/).
-  - For a page that has images or other stuff included, it is best to create a new directory. Put the contents in a `index.md` file (no `_`) and the related files next to it. See https://gohugo.io/content-management/organization/ for more information.
-  - Look at https://mcshelby.github.io/hugo-theme-relearn/ for more information about what the Relearn theme offers, including some handy "shortcodes".
+  - For a page that has images or other stuff included, it is best to create a new directory:
+    Put the contents in an `index.md` file (no `_`) and the related files next to it.
+    See <https://gohugo.io/content-management/organization/> for more information.
+
+  See <https://mcshelby.github.io/hugo-theme-relearn/> for more information about
+  the features of the Relearn theme, including handy "shortcodes".
+
+Note: When switching versions, before re-generating the documentation using
+`hugo server`, delete the previously generated static site using `rm -r docs/public`.
+
+### Notes for supporting current versions of Hugo and the Relearn theme
+
+Backported fixes to support newer Hugo versions:
+
+- `layouts/partials/header.html`, it fixes:
+  ```js
+  ERROR deprecated: .Sites.First was deprecated in Hugo v0.127.0 and will be removed in Hugo 0.143.0. Use .Sites.Default instead.
+  ```
+- `layouts/partials/menu.html`, it fixes:
+  ```js
+  ERROR deprecated: .Site.IsMultiLingual was deprecated in Hugo v0.124.0 and will be removed in Hugo 0.143.0. Use hugo.IsMultilingual instead.
+  ```
+
+The fixes for those issues were backported from the Hugo Relearn v7.x.x theme.
+When updating to Hugo Relearn 7.x.x, please remove them (if possible).
+
+#### Tips when upgradubg to newer Hugo Relearn versions
+
+Check the release notes of the Hugo Relearn theme for breaking changes:
+https://mcshelby.github.io/hugo-theme-relearn/introduction/releasenotes
+
+These pages might need review when making changes as their content is
+generated by layouts/partials/content.html:
+
+- XenAPI Reference: <https://xapi-project.github.io/new-docs/xen-api/classes>
+- XenAPI Releases: <https://xapi-project.github.io/new-docs/xen-api/releases>
+
+For a summary of the partials supported by the Hugo Relearn theme, see:
+https://mcshelby.github.io/hugo-theme-relearn/configuration/customization/partials
+
+Hint: For upgrading the Hugo Relearn theme, you can use:
+
+```bash
+cd doc; hugo mod get -u github.com/McShelby/[email protected]
+```
+
+#### Summary
+
+Hugo >= 0.126 and the Hugo Relearn >= 7.3.2 are supported to render the docs.
+
+#### References
+
+- Changes with Relearn 6.x:
+  <https://mcshelby.github.io/hugo-theme-relearn/introduction/releasenotes/6/#6-0-0>
+- Breaking changes with Relearn 7.x:
+  <https://mcshelby.github.io/hugo-theme-relearn/introduction/releasenotes/7/#7-0-0>

doc/content/design/_index.md

@@ -1,6 +1,6 @@
 +++
 title = "Design Documents"
-menuTitle = "Designs"
+linkTitle = "Designs"
 +++
 
 {{< design_docs_list >}}

doc/content/design/coverage/index.md

@@ -8,7 +8,7 @@ revision: 2
 
 We would like to add optional coverage profiling to existing [OCaml]
 projects in the context of [XenServer] and [XenAPI]. This article
-presents how we do it. 
+presents how we do it.
 
 Binaries instrumented for coverage profiling in the XenServer project
 need to run in an environment where several services act together as
@@ -21,7 +21,7 @@ isolation.
 To build binaries with coverage profiling, do:
 
     ./configure --enable-coverage
-    make 
+    make
 
 Binaries will log coverage data to `/tmp/bisect*.out` from which a
 coverage report can be generated in `coverage/`:
@@ -38,7 +38,7 @@ and logs during execution data to in-memory data structures. Before an
 instrumented binary terminates, it writes the logged data to a file.
 This data can then be analysed with the `bisect-ppx-report` tool, to
 produce a summary of annotated code that highlights what part of a
-codebase was executed. 
+codebase was executed.
 
 [BisectPPX] has several desirable properties:
 
@@ -65,13 +65,13 @@ abstracted by OCamlfind (OCaml's library manager) and OCamlbuild
 
     # build it with instrumentation from bisect_ppx
     ocamlbuild -use-ocamlfind -pkg bisect_ppx -pkg unix example.native
-    
+
     # execute it - generates files ./bisect*.out
     ./example.native
-    
+
     # generate report
     bisect-ppx-report -I _build -html coverage bisect000*
-    
+
     # view coverage/index.html
 
     Summary:
@@ -86,7 +86,7 @@ will be instrumented during compilation. Behind the scenes `ocamlfind`
 makes sure that the compiler uses a preprocessing step that instruments
 the code.
 
-## Signal Handling 
+## Signal Handling
 
 During execution the code instrumentation leads to the collection of
 data. This code registers a function with `at_exit` that writes the data
@@ -98,7 +98,7 @@ terminated by receiving the `TERM` signal, a signal handler must be
 installed:
 
     let stop signal =
-      printf "caught signal %d\n" signal;
+      printf "caught signal %a\n" Debug.Pp.signal signal;
       exit 0
 
     Sys.set_signal Sys.sigterm (Sys.Signal_handle stop)
@@ -149,8 +149,8 @@ environment variable. This can happen on the command line:
 
     BISECT_FILE=/tmp/example ./example.native
 
-In the context of XenServer we could do this in startup scripts. 
-However, we added a bit of code 
+In the context of XenServer we could do this in startup scripts.
+However, we added a bit of code
 
     val Coverage.init: string -> unit
 
@@ -176,12 +176,12 @@ Goals for instrumentation are:
 
 * what files are instrumented should be obvious and easy to manage
 * instrumentation must be optional, yet easy to activate
-* avoid methods that require to keep several files in sync like multiple 
+* avoid methods that require to keep several files in sync like multiple
   `_oasis` files
 * avoid separate Git branches for instrumented and non-instrumented
   code
 
-In the ideal case, we could introduce a configuration switch 
+In the ideal case, we could introduce a configuration switch
 `./configure --enable-coverage` that would prepare compilation for
 coverage instrumentation. While [Oasis] supports the creation of such
 switches, they cannot be used to control build dependencies like
@@ -196,7 +196,7 @@ rules in file `_tags.coverage` that cause files to be instrumented:
 
 leads to the execution of this code during preparation:
 
-    coverage: _tags _tags.coverage 
+    coverage: _tags _tags.coverage
       test ! -f _tags.orig && mv _tags _tags.orig || true
       cat _tags.coverage _tags.orig > _tags
 
@@ -207,7 +207,7 @@ could be tweaked to instrument only some files:
     <**/*.native>:   pkg_bisect_ppx
 
 When `make coverage` is not called, these rules are not active and
-hence, code is not instrumented for coverage. We believe that this 
+hence, code is not instrumented for coverage. We believe that this
 solution to control instrumentation meets the goals from above. In
 particular, what files are instrumented and when is controlled by very
 few lines of declarative code that lives in the main repository of a
@@ -226,14 +226,14 @@ coverage analysis are:
 The `_oasis` file bundles the files under `profiling/` into an internal
 library which executables then depend on:
 
-		# Support files for profiling 
+		# Support files for profiling
 		Library profiling
 			CompiledObject:     best
 			Path:               profiling
 			Install:            false
 			Findlibname:        profiling
 			Modules:            Coverage
-			BuildDepends: 
+			BuildDepends:
 
 		Executable set_domain_uuid
 			CompiledObject:     best
@@ -243,16 +243,16 @@ library which executables then depend on:
 			MainIs:             set_domain_uuid.ml
 			Install:            false
 			BuildDepends:
-				xenctrl, 
-				uuidm, 
+				xenctrl,
+				uuidm,
 				cmdliner,
 				profiling			# <-- here
 
 The `Makefile` target `coverage` primes the project for a profiling build:
 
 		# make coverage - prepares for building with coverage analysis
 
-		coverage: _tags _tags.coverage 
+		coverage: _tags _tags.coverage
 			test ! -f _tags.orig && mv _tags _tags.orig || true
 			cat _tags.coverage _tags.orig > _tags
 

doc/content/design/cpu-levelling-v2.md

@@ -29,7 +29,7 @@ The old XS 5.6-style Heterogeneous Pool feature that is based around hardware-le
 History
 =======
 
-- Original XS 5.6 design: [heterogeneous-pools](../heterogeneous-pools)
+- Original XS 5.6 design: [heterogeneous-pools](heterogeneous-pools)
 - Changes made in XS 5.6 FP1 for the DR feature (added CPUID checks upon migration)
 - XS 6.1: migration checks extended for cross-pool scenario
 

doc/content/design/emulated-pci-spec.md

@@ -11,7 +11,7 @@ status: proposed
 At present (early March 2015) the datamodel defines a VM as having a "platform" string-string map, in which two keys are interpreted as specifying a PCI device which should be emulated for the VM. Those keys are "device_id" and "revision" (with int values represented as decimal strings).
 
 Limitations:
-* Hardcoded defaults are used for the the vendor ID and all other parameters except device_id and revision.
+* Hardcoded defaults are used for the vendor ID and all other parameters except device_id and revision.
 * Only one emulated PCI device can be specified.
 
 When instructing qemu to emulate PCI devices, qemu accepts twelve parameters for each device.

doc/content/design/integrated-gpu-passthrough/index.md

@@ -11,7 +11,7 @@ Introduction
 ------------
 
 Passthrough of discrete GPUs has been
-[available since XenServer 6.0]({{site.baseurl}}/xapi/design/gpu-passthrough.html).
+[available since XenServer 6.0](../gpu-passthrough.md).
 With some extensions, we will also be able to support passthrough of integrated
 GPUs.