doc: Update CMake's README

cmake/README.md

@@ -1,31 +1,67 @@
 Building with CMake
 -------------------
 
-The quickest way to build and install panda with CMake is to run:
+On Windows and macOS, please ensure that you have the very latest version of
+CMake installed; older versions may work, but if not, please upgrade to the
+latest available version of CMake before requesting help.
+
+On systems that package CMake themselves (e.g. Linux distributions), we most
+likely support the provided version of CMake as long as the system itself is
+supported.
+
+CMake will also require that you already have your system's developer tools
+installed.
+
+The quickest way to build and install Panda with CMake is to install any
+third-party dependencies and then run:
 ```sh
 mkdir build && cd build
 cmake ..
-make
-[sudo] make install
+cmake --build . --config Standard --parallel 4
+[sudo] cmake --build . --config Standard --target install
 ```
 
+Note that, if you are targeting 64-bit on Windows, it is necessary to supply
+the `-A x64` option when first invoking `cmake` (as `cmake -A x64 ..`).
+
+CMake itself does not build Panda; rather, it generates project files for an
+existing IDE or build tool. To select a build tool, pass the `-G` option when
+first invoking CMake, (`cmake -G Ninja ..` is highly recommended on Linux).
+Some of these (Xcode, Visual Studio) support targeting multiple configurations
+(the `--config Standard`, above, selects the `Standard` configuration in those
+cases). Other build tools (Ninja, Makefiles, ...) do not support multiple
+configurations, and the `--config` option is ignored. To change the
+configuration in these cases (from `Standard`, the default), it is necessary to
+change the `CMAKE_BUILD_TYPE` variable as explained below.
+
+The configurations are:
+
+| Configuration  | Explanation                                            |
+| -------------- | ------------------------------------------------------ |
+| Standard       | Default; build provided to users of SDK                |
+| Release        | Distribution for end-users                             |
+| MinSizeRel     | Like Release, but optimized for size                   |
+| RelWithDebInfo | Like Release, but include debug symbols                |
+| Debug          | Do not optimize, enable optional debugging features    |
+| Coverage       | Like Debug, but profile code coverage; developers only |
+
 To configure CMake, it is recommended to use cmake-gui (`cmake-gui .`),
-however it is also possible to configure it entirely through CMake's
-command-line interface; see `man cmake` for more details.
+or ccmake (`ccmake .`), however it is also possible to configure it entirely
+through CMake's command-line interface; see `man cmake` for more details.
 
 In general, the config variable for a particular third party library is:
 ```
-	HAVE_<LIBRARY>=True/False   # Example: USE_JPEG
+	HAVE_<LIBRARY>=YES/NO   # Example: USE_JPEG
 ```
 Panda subpackage building is handled by:
 ```
-	BUILD_<SUBPACKAGE>=True/False   # Example: BUILD_DTOOL, BUILD_PANDA
+	BUILD_<SUBPACKAGE>=YES/NO   # Example: BUILD_DTOOL, BUILD_PANDA
 ```
 Other configuration settings use their historical names (same names as in-source):
 ```
 	# Examples
 	PANDA_DISTRIBUTOR="MyDistributor"
-	LINMATH_ALIGN=On
+	LINMATH_ALIGN=YES
 
 	# ... etc ...
 
@@ -33,20 +69,10 @@ Other configuration settings use their historical names (same names as in-source
 
 For example, `makepanda.py --distributor X` becomes `cmake -DPANDA_DISTRIBUTOR=X`
 
-All found third-party libraries are enabled by default.
-Most config settings are set to a sensible default for typical
-a PC/desktop Panda3D distribution.
-Third-party libraries and other settings can be enabled or disabled
-through configuration with the cmake gui or cli.
-
-Running Panda3D with `-DCMAKE_BUILD_TYPE=` and one of `Release`, `Debug`,
-`MinSizeRel`, or `RelWithDebInfo` will cause some configuration settings
-to change their defaults to more appropriate values.
-
-If cmake has already been generated, changing the build type will not cause
-some of these values to change to their expected values, because the values
-are cached so that they don't overwrite custom settings.
+All found third-party libraries are enabled by default, and makepanda-style
+tools packages are searched in the same path as makepanda (however this may be
+overridden with the `THIRDPARTY_DIRECTORY` option).
 
-To reset CMake's config to defaults, delete the CMakeCache.txt file, and rerun
-CMake with the preferred build mode specified
-(example: `cmake .. -DCMAKE_BUILD_TYPE=Debug`).
+Most config settings are set to a sensible default for a typical PC/desktop
+Panda3D distribution. Third-party libraries and other settings can be enabled
+or disabled through configuration with the cmake GUI or CLI.