doc/dev/cephadm: describe advanced build options

Describe the advanced build options provided by build.py and how
to use `cephadm version --verbose` to print the internal metadata.

Signed-off-by: John Mulligan <jmulligan@redhat.com>

diff --git a/doc/dev/cephadm/developing-cephadm.rst b/doc/dev/cephadm/developing-cephadm.rst
index 49b771caa5c8d7a34b6344979340d270ede717a5..aebe002da88c6ba9aae7230581cf72a70d5ab5de 100644 (file)
--- a/doc/dev/cephadm/developing-cephadm.rst
+++ b/doc/dev/cephadm/developing-cephadm.rst
@@ -401,3 +401,64 @@ own copy of the cephadm "binary" use the script located at
 ``./src/cephadm/build.py [output]``.
 
 .. _Python Zip Application: https://peps.python.org/pep-0441/
+
+You can pass a limited set of version metadata values to be stored in the
+compiled cepadm. These options can be passed to the build script with
+the ``--set-version-var`` or ``-S`` option. The values should take the form
+``KEY=VALUE`` and valid keys include:
+* ``CEPH_GIT_VER``
+* ``CEPH_GIT_NICE_VER``
+* ``CEPH_RELEASE``
+* ``CEPH_RELEASE_NAME``
+* ``CEPH_RELEASE_TYPE``
+
+Example: ``./src/cephadm/build.py -SCEPH_GIT_VER=$(git rev-parse HEAD) -SCEPH_GIT_NICE_VER=$(git describe) /tmp/cephadm``
+
+Typically these values will be passed to build.py by other, higher level, build
+tools - such as cmake.
+
+The compiled version of the binary may include a curated set of dependencies
+within the zipapp. The tool used to fetch the bundled dependencies can be
+Python's ``pip``, locally installed RPMs, or bundled dependencies can be
+disabled. To select the mode for bundled dependencies use the
+``--bundled-dependencies`` or ``-B`` option with a value of ``pip``, ``rpm``,
+or ``none``.
+
+The compiled cephadm zipapp file retains metadata about how it was built. This
+can be displayed by running ``cephadm version --verbose``.  The command will
+emit a JSON formatted object showing version metadata (if available), a list of
+the bundled dependencies generated by the build script (if bundled dependencies
+were enabled), and a summary of the top-level contents of the zipapp. Example::
+
+  $ ./cephadm version --verbose
+  {
+    "name": "cephadm",
+    "ceph_git_nice_ver": "18.0.0-6867-g6a1df2d0b01",
+    "ceph_git_ver": "6a1df2d0b01da581bfef3357940e1e88d5ce70ce",
+    "ceph_release_name": "reef",
+    "ceph_release_type": "dev",
+    "bundled_packages": [
+      {
+        "name": "Jinja2",
+        "version": "3.1.2",
+        "package_source": "pip",
+        "requirements_entry": "Jinja2 == 3.1.2"
+      },
+      {
+        "name": "MarkupSafe",
+        "version": "2.1.3",
+        "package_source": "pip",
+        "requirements_entry": "MarkupSafe == 2.1.3"
+      }
+    ],
+    "zip_root_entries": [
+      "Jinja2-3.1.2-py3.9.egg-info",
+      "MarkupSafe-2.1.3-py3.9.egg-info",
+      "__main__.py",
+      "__main__.pyc",
+      "_cephadmmeta",
+      "cephadmlib",
+      "jinja2",
+      "markupsafe"
+    ]
+  }