readme wording updates

README.md

@@ -25,15 +25,29 @@ If you want to operate a node, build services, or explore psibase's command-line
 
 ## Building this repo from source
 
-We only support developing natively on Ubuntu 20.04 and Ubuntu 22.04. Some of our developers have very strong success with Ubuntu on WSL2, and also with Docker.
+We only officially support developing natively on Ubuntu 20.04 and Ubuntu 22.04, although any Linux distribution may work. If you use a distribution other than Ubuntu 20.04 or 22.04, ensure the versions of the dependencies you install are at least as high as they are in Ubuntu.
 
-To build this repo from source, your environment first needs to be set up. To set up your environment, 
+Some of our developers have very strong success with Ubuntu on WSL2, and also with Docker.
 
-```TODO - LIST DEPENDENCIES, RATHER THAN LINKING TO THE DOCKERFILES.```
+### Environment setup
 
-You may also reference either the [Ubuntu 20.04 dockerfile](https://github.com/gofractally/image-builders/blob/main/docker/ubuntu-2004-builder.Dockerfile) or the [Ubuntu 22.04 dockerfile](https://github.com/gofractally/image-builders/blob/main/docker/ubuntu-2204-builder.Dockerfile) for an example on how an environment could be set up.
+> Note: If you would prefer to use a containerized development environment (for example to isolate the dependencies, or to develop on operating systems other than Ubuntu 20.04 and Ubuntu 22.04 such as Windows or Mac), see the [Psibase Contributor](https://github.com/gofractally/psibase-contributor) repository.
 
-Alternatively, if you would prefer to use a containerized development environment (for example to isolate the dependencies, or to develop on operating systems other than Ubuntu 20.04 and Ubuntu 22.04 such as Windows or Mac), see the [Psibase Contributor repository](https://github.com/gofractally/psibase-contributor).
+Here is a script for Ubuntu 22.04:
+ ~TODO~
+
+Add the paths to the following packages (or later versions) into your PATH environment variable:
+ * `node 16.17`
+ * `npm 8.19`
+ * `yarn 1.22`
+ * `cargo 1.63`
+ * `wasm-opt`
+
+Also set the `WASI_SDK_PREFIX` environment variable before building to the root of your llvm installation (Alternatively, use cmake's `-DWASI_SDK_PREFIX=....` option when building). 
+
+> You may reference either the [Ubuntu 20.04 dockerfile](https://github.com/gofractally/image-builders/blob/main/docker/ubuntu-2004-builder.Dockerfile) or the [Ubuntu 22.04 dockerfile](https://github.com/gofractally/image-builders/blob/main/docker/ubuntu-2204-builder.Dockerfile) for an example on how an environment could be set up.
+
+### Running a build
 
 After your environment is set up, then you should be able to use the following build instructions:
 
@@ -48,13 +62,15 @@ make install
 
 The built product lives in `/opt/psidk/`.
 
-To build documentation, add the `-DBUILD_DOC=yes` flag to the `cmake` command. Further instructions on building and hosting documentation can be found in the [documentation section](https://doc-sys.psibase.io/documentation.html) of our demo deployment docs.
+The documentation for Psibase is part of this repository. To build & view it through a deployed Psibase instance, see the instructions in the [Documentation section](https://doc-sys.psibase.io/documentation.html) of our demo deployment docs.
 
 ### MacOS
 
-Use either an Ubuntu 22.04 VM or a Docker Ubuntu 22.04 container. If your machine is ARM, you must use Rosetta; eos-vm JITs Intel machine code.
+Although some people have had success building natively on MacOS, we struggled to reproduce this success. Therefore for now, we do not officially support building natively on a MacOS.
+
+If you have a Mac (including the new Apple Silicon M1 or M2 based Macs), you may use either an Ubuntu 22.04 VM or a Docker Ubuntu 22.04 container. We do not host an ARM variants of our [docker images](https://github.com/orgs/gofractally/packages?repo_name=image-builders) on our GitHub container registry. Therefore if you would like to use either the `psibase-builder-ubuntu-2204` or `psibase-contributor` on your Mac, you should pull the [image-builders](https://github.com/gofractally/image-builders) repo and build the images yourself.  
 
-Some people have been able to build this directly on MacOS without using Docker or Ubuntu VMs. We struggled to reproduce these successes on other MacOS machines. For now, we don't have the people to answer questions relating to Mac. The error messages are nonsensical. The workarounds unreproducible. Apple mangled several tools and libraries such as libtool and openssl. Brew tries to replace them, but MacOS fights back hard. In some cases Brew is too careful about this and requires magic incantations to use the replacements; these incantations change with Brew's frequent version bumps. Building and running appear to require disabling several MacOS security features. Apple keeps changing the magic incantations to do this. Our existing developers need a multi-year break from even thinking of Mac.
+If your machine is ARM, you must use Rosetta; eos-vm JITs Intel machine code.
 
 ## Support