Minor improvements to the Emscripten instructions

Author: hoodmane

getting-started/setup-building.rst

@@ -522,34 +522,44 @@ The simplest way to build Emscripten is to run:
 
 .. code-block:: sh
 
-    python3 Platforms/emscripten build all --emsdk-cache=./cross-build/emsdk
+   export EMSDK_CACHE=$PWD/cross-build/emsdk
+   python3 Platforms/emscripten install-emscripten
+   python3 Platforms/emscripten build all
 
-This will:
+`install-emscripten` downloads and installs the version of the Emscripten SDK
+required, placing it in the `EMSDK_CACHE` directory.
+`build all` will:
 
 1. Build a copy of Python that can run on the host machine (the "build" python);
-2. Download a copy of the Emscripten SDK matching the version required by the
-   version of Python being compiled;
-3. Ensure that a required version of Node is installed;
-4. Download the code for all the binary dependencies of Python (such as
-   ``libFFI`` and ``xz``), and compile them for Emscripten; and
-5. Build a copy of Python that can run on Emscripten (the "host" python).
-
-If you omit the ``--emsdk-cache`` environment variable, the build script will
+2. Ensure that a required version of Node is installed;
+3. Download the code for all the binary dependencies of Python (such as
+   ``libffi`` and ``mpdecimal``), and compile them for Emscripten; and
+4. Build a copy of Python that can run on Emscripten (the "host" python).
+
+The built binary dependencies are cached inside the Emscripten cache directory.
+Once built for a given Emscripten version, they will not be rebuilt on
+subsequent runs unless there is a change in the version or build script for the
+dependency.
+
+If you omit the ``EMSDK_CACHE`` environment variable, the build script will
 assume that the current environment has the Emscripten tools available. You are
 responsible for downloading and activating those tools in your environment. The
 version of Emscripten and Node that is required to build Python is defined in
 the :cpy-file:`Platforms/emscripten/config.toml` configuration file.
 
-There are three environment variables that can be used to control the operation of
+There are two environment variables that can be used to control the operation of
 the ``Platforms/emscripten`` build script:
 
-* ``EMSDK_CACHE`` controls the location of the emscripten SDK. You can use this instead
-  environment variable instead of passing the ``--emsdk-cache`` flag.
-* ``CACHE_DIR`` defines the location where downloaded artefacts, such
-  as precompiled ``libFFI`` and ``xz`` binaries, will be stored.
-* ``CROSS_BUILD_DIR`` defines the name of the ``cross-build`` directory
-  that will be used for builds. This can be useful if you need to maintain
-  builds of multiple versions of Python.
+* ``EMSDK_CACHE`` (or the ``--emsdk-cache`` flag) controls the location of the
+  Emscripten SDK cache directory. You can use this environment variable instead
+  of passing the ``--emsdk-cache`` flag. When set, the build script will
+  validate that the required Emscripten version is present in the cache and will
+  exit with an error if it is not; run ``install-emscripten`` to populate the
+  cache.
+* ``CROSS_BUILD_DIR`` (or the ``--cross-build-dir`` flag) defines the location
+  of the ``cross-build`` directory that will be used for builds. This can be
+  useful if you need to maintain builds of multiple versions of Python
+  side by side.
 
 It is possible (but not necessary) to enable ``ccache`` for Emscripten builds
 by setting the ``EM_COMPILER_WRAPPER`` environment, but this step will only
@@ -571,8 +581,9 @@ Emscripten build in ``cross-build/build`` and
 ``cross-build/wasm32-emscripten/build/python/``, respectively.
 
 The ``Platforms/emscripten`` script has a number of other entry points that allow for
-fine-grained execution of each part of an iOS build; run ``python3
-Platforms/emscripten --help`` for more details.
+fine-grained execution of each part of an Emscripten build; run
+``python3 Platforms/emscripten --help`` for more details.
+
 
 Once the build is complete, you can run Python code using: