Clarify when the commands block is executed during rez-build (#1391)

* Clarity around when the commands block when building

Signed-off-by: Jason Scott <[email protected]>

wiki/pages/Building-Packages.md

@@ -76,9 +76,10 @@ build environment, but the details of the build itself are left open for the use
 Having said that, *cmake* has been supported by rez for some time, and rez comes with a
 decent amount of utility code to manage cmake builds.
 
-When a rez environment is configured, each package's [commands](Package-Definition-Guide#commands)
-section configures the environment. When a build is occurring, a special variable
-[building](Package-Commands#building) is set to *True*. Your packages should use this
+When a rez environment is configured, each required package's
+[commands](Package-Definition-Guide#commands) section configures the environment for the building
+package to use. When a build is occurring, a special variable
+[building](Package-Commands#building) is set to *True*. Your required packages should use this
 variable to communicate build information to the package being built.
 
 For example, our *boost* package's commands might look like so:
@@ -88,6 +89,11 @@ For example, our *boost* package's commands might look like so:
             # there is a 'FindBoost.cmake' file in this dir..
             env.CMAKE_MODULE_PATH.append("{root}/cmake")
 
+> [[media/icons/warning.png]] Note that _commands_ is never executed for the package actually
+being built - 
+> if you want to run commands in that case, you can use
+[pre_build_commands](Package-Commands#pre-build-commands) instead.
+
 A (very simple) *FindBoost.cmake* file might look like this:
 
     set(Boost_INCLUDE_DIRS $ENV{REZ_BOOST_ROOT}/include)

wiki/pages/Package-Commands.md

@@ -290,8 +290,10 @@ Do not check this variable to detect if an installation is occurring - see `buil
         env.FOO_INCLUDE_PATH = "{root}/include"
 
 This boolean variable is *True* if a build is occurring (typically done via the *rez-build* tool),
-and *False* otherwise. Typically a package will use this variable to set environment variables that
-are only useful during a build - C++ header include paths are a good example.
+and *False* otherwise, however, the `commands` block is only executed when the package is brought
+into a resolved environment, so this is not used when the package itself is building. Typically a
+package will use this variable to set environment variables that are only useful during when other
+packages are being built - C++ header include paths are a good example.
 
 ### command
 *Function*

wiki/pages/Package-Definition-Guide.md

@@ -546,9 +546,10 @@ enabled. If not provided, this is determined from the global config setting [def
         env.PYTHONPATH.append("{root}/python")
         env.PATH.append("{root}/bin")
 
-This is a block of python code which tells rez how to update an environment so that this package can
-be used. There is a python API provided (see [here](Package-Commands) for more details) that lets
-you do things such as:
+This is a block of python code which tells rez how to update an environment so that this package
+can be used. It is executed when the package is brought into a rez environment, either by explicit
+request or by another package's requirements. There is a python API provided (see
+[here](Package-Commands) for more details) that lets you do things such as:
 
 * set, unset, prepend and append environment variables;
 * create aliases;