Automate PATH verification in install_prerequisites.sh, simplify README

README.adoc

@@ -35,62 +35,12 @@ You can **run the https://github.com/rust-lang/rust-clippy[Clippy linter]** usin
 
 === Installing Prerequisite Software
 
-The following software may be installed automatically with the following scripts:
+The following software may be installed automatically with the following script:
 
 ----
 $ ./tools/install_prerequisites.sh
 ----
 
-Alternatively, the manual installation steps as follows:
-
-Both normal execution and the test suite expect certain binaries (described below) on your PATH.
-
-. libpq, the PostgreSQL client library
-+
---
-We use Diesel's PostgreSQL support to connect to CockroachDB (which is wire-compatible with PostgreSQL).  Diesel uses the native libpq to do this.  You can get the client library with:
-
-* Helios: `pkg install library/postgresql-13`
-* Linux: `sudo apt-get install libpq-dev`
-* Mac: `brew install postgresql`
-
-After doing this, you should have the `pg_config` command on your PATH.  For example, on Helios, you'd want `/opt/ooce/bin` on your PATH.
---
-. pkg-config, a tool for querying installed libraries
-+
---
-
-* Helios: `pkg install pkg-config`
-* Linux: `sudo apt-get install pkg-config`
-* Mac: `brew install pkg-config`
-
-After doing this, you should have the `pkg-config` command on your PATH.  For
-example, on Helios, you'd want `/usr/bin` on your PATH.
---
-. CockroachDB v21.1.10.
-+
-The build and test suite expects to be able to start a single-node CockroachDB cluster using the `cockroach` executable on your PATH.
-On illumos, MacOS, and Linux, you should be able to use the `tools/ci_download_cockroachdb` script to fetch the official CockroachDB binary.  It will be put into `./out/cockroachdb/bin/cockroach`.
-Alternatively, you can follow the https://www.cockroachlabs.com/docs/stable/install-cockroachdb.html[official CockroachDB installation instructions for your platform].
-
-. ClickHouse >= v21.7.1.
-+
-The test suite expects a running instance of the ClickHouse database server.
-The script `./tools/ci_download_clickhouse` can be used to download a pre-built binary for illumos, Linux, or macOS platforms. Once complete, you must manually add the binary (located at `./out/clickhouse/clickhouse`) to your PATH.
-You may also install ClickHouse manually; instructions can be found https://clickhouse.tech/docs/en/getting-started/install[here].
-See <<_configuring_clickhouse>> for details on ClickHouse's setup and configuration files.
-+
-. Additional software requirements:
-+
-On an illumos-based machine (Helios, OmniOS), if you want to run the real (non-simulated) Sled Agent to run actual VMs with Propolis, make sure your packages are up to date, and you have the `brand/omicron1/tools` package:
-+
-[source,text]
-----
-pkg install brand/omicron1/tools
-pkg install pkg:/package/pkg
-pkg update
-----
-
 === Running (Simulated) Omicron
 
 NOTE: If you'd like to run on Helios, refer to <<Deploying Omicron>> below.

tools/install_prerequisites.sh

@@ -30,6 +30,22 @@ function confirm
   esac
 }
 
+# Packages to be installed on all OSes:
+#
+# - libpq, the PostgreSQL client lib.
+# We use Diesel's PostgreSQL support to connect to CockroachDB (which is
+# wire-compatible with PostgreSQL). Diesel uses the native libpq to do this.
+# `pg_config` is a utility which may be used to query for the installed
+# PostgreSQL libraries, and is expected by the Omicron build to exist in
+# the developer's PATH variable.
+# - pkg-config, a tool for querying installed libraries.
+#
+# Packages to be installed on Helios only:
+#
+# - pkg, the IPS client (though likely it will just be updated)
+# - build-essential: Common development tools
+# - brand/omicron1/tools: Oxide's omicron1-brand Zone
+
 HOST_OS=$(uname -s)
 if [[ "${HOST_OS}" == "Linux" ]]; then
   packages=(
@@ -70,5 +86,66 @@ else
   exit -1
 fi
 
+# CockroachDB and Clickhouse are used by Omicron for storage of
+# control plane metadata and metrics.
+#
+# They are used in a couple of spots within Omicron:
+#
+# - Test Suite: The test suite, regardless of host OS, builds temporary
+# databases for testing, and expects `cockroach` and `clickhouse` to
+# exist as a part of the PATH.
+# - Packaging: When constructing packages on Helios, these utilities
+# are packaged into zones which may be launched by the sled agent.
+
 ./tools/ci_download_cockroachdb
 ./tools/ci_download_clickhouse
+
+# Validate the PATH:
+expected_in_path=(
+  'pg_config'
+  'pkg-config'
+  'cockroach'
+  'clickhouse'
+)
+
+function show_hint
+{
+  case "$1" in
+    "pg_config")
+      if [[ "${HOST_OS}" == "SunOS" ]]; then
+        echo "On illumos, $1 is typically found in '/opt/ooce/bin'"
+      fi
+      ;;
+    "pkg-config")
+      if [[ "${HOST_OS}" == "SunOS" ]]; then
+        echo "On illumos, $1 is typically found in '/usr/bin'"
+      fi
+      ;;
+    "cockroach")
+      echo "$1 should have been installed to '$PWD/out/cockroachdb/bin'"
+      ;;
+    "clickhouse")
+      echo "$1 should have been installed to '$PWD/out/clickhouse'"
+      ;;
+    *)
+      ;;
+  esac
+}
+
+# Check all paths before returning an error.
+ANY_PATH_ERROR="false"
+for command in "${expected_in_path[@]}"; do
+  rc=0
+  which "$command" &> /dev/null || rc=$?
+  if [[ "$rc" -ne 0 ]]; then
+    echo "ERROR: $command seems installed, but was not found in PATH. Please add it."
+    show_hint "$command"
+    ANY_PATH_ERROR="true"
+  fi
+done
+
+if [[ "$ANY_PATH_ERROR" == "true" ]]; then
+  exit -1
+fi
+
+echo "All prerequisites installed successfully, and PATH looks valid"