Update BUILDING.txt

BUILDING.txt

@@ -2,17 +2,22 @@
 
 Usual Makefile project. This project does not require a configure phase.
 
-The minimum required compiler is GCC 4.2.  On 10.6+ with Xcode 3.2+, the
-default Xcode compiler is adequate, and a simple 'make' is sufficient to
+Officially, the minimum required compiler is GCC 4.2.  On 10.6+ with Xcode 3.2+,
+the default Xcode compiler is adequate, and a simple 'make' is sufficient to
 build all three versions of the library for the default architecture.
 
-On 10.5 with Xcode 3.1, GCC 4.2 is provided, but the default is usually
-GCC 4.0, so overriding the default may be needed.  On 10.4 with Xcode
-2.5, only GCC 4.0 is provided, so it's necessary to use the MacPorts
-apple-gcc42 compiler (or better).
+On 10.5 with Xcode 3.1, GCC 4.2 is provided, but the default is usually GCC 4.0,
+so overriding the default may be needed.  Successful builds have been observed
+with Xcode 3.1 GCC 4.0, but these have not been significantly tested.  There is
+very little reson not to use the provided GCC 4.2.
 
-Cross-builds and/or universal builds may be specified in the usual way,
-either via the usual CFLAGS/CXXFLAGS/LDFLAGS, or via ARCHFLAGS.
+On 10.4 with Xcode 2.5, only GCC 4.0 is provided, and its accompanying linker is
+known to have issues with legacy-support's dynamic linking, so it's necessary to
+use the MacPorts apple-gcc42 compiler (or better).
+
+Cross-builds and/or universal builds may be specified in the usual way, either
+via the usual CFLAGS/CXXFLAGS/LDFLAGS, or via ARCHFLAGS, though the preferred
+method is to provide a list of architectures in ARCHS.
 
 Note that the 'ar' tool may generate spurious warnings when creating a
 universal static library, but it still produces the correct result.
@@ -29,15 +34,39 @@ the Makefile.  To override the defaults, see below.
 
 # `XCFLAGS`
 # `XCXXFLAGS`
+# `XLDFLAGS`
 
-Overridable default values for CFLAGS and CXXFLAGS, respectively.  Merged with
-any supplied CFLAGS and/or CXXFLAGS.  Note that the only C++ builds are a few
-tests not included in the standard test suite, so [X]CXXFLAGS usually has no
-effect.
+Overridable default values for CFLAGS, CXXFLAGS, and LDFLAGS, respectively.
+Merged with any supplied CFLAGS, CXXFLAGS, and/or LDFLAGS.  Note that the only
+C++ builds are a few tests not included in the standard test suite, so
+[X]CXXFLAGS usually has no effect.
+
+# `ARCHS`
+
+List of architectures to build, without the '-arch'.  This is the preferred
+method of specifying architectures.  Including architectures that can't be
+built with the default or chosen SDK will result in failures.
 
 # `ARCHFLAGS`
 
 Merged into CFLAGS/CXXFLAGS/LDFLAGS, normally to specify arch-related options.
+The default value is derived from 'ARCHS', so in most cases it should not be
+specified.  The only exception is if there is some reason to want to use options
+like '-m32' or '-m64'.  Note that setting both 'ARCHS' and 'ARCHFLAGS'
+inconsistently will probably produce bad results.
+
+# `TESTARCHS`
+
+List of architectures to use for running tests.  The default is a filtered
+version of 'ARCHS' which excludes architectures that can't be executed on the
+current machine.  In most cases, this is appropriate.  This does not affect
+the *building* of tests, which is always based on 'ARCHS', but the targets
+for *running* tests are based on this list.
+
+# `TEST_ARGS`
+
+Arguments supplied to tests when run via the test targets.  Most commonly
+used for the '-v' argument, giving verbose output.
 
 # `DEBUG`
 
@@ -47,7 +76,8 @@ such as `-g3`.
 # `OPT`
 
 The optimization setting (defaulting to `-Os`), which is merged into the
-compile flags but not the linker flags.
+compile flags but not the linker flags.  When debugging, `-O0` is usually
+a desirable choice.
 
 ### Special optional variables
 
@@ -55,3 +85,42 @@ compile flags but not the linker flags.
 # `FORCE_ARCH`
 
 Obsolete.  No longer used.
+
+
+## Running tests
+
+If a test is named 'test_foo', then it has a run target named 'run_foo', which
+builds (if needed) and runs that test.  If 'TESTARCHS' has multiple entries,
+then the test also has a set of targets of the form 'run_foo_<arch>', to run the
+test on that specific architecture.  Additionally, it has a target
+'run_foo_unv', which runs all the 'run_foo_<arch>' targets.  If 'TESTARCH' does
+not have multiple entries, the '<arch>' versions are unavailable, but
+'run_foo_unv' still exists as a synonym for 'run_foo', making it unconditionally
+legal.  In all cases, 'run_foo' runs the test without any constraints, allowing
+the OS to choose the architecture (if relevant).
+
+## Special test targets
+
+# `test[_unv]`
+# 'check[_unv]`
+
+These run all normal automatic tests on the usual dynamic library.
+
+# `test_static[_unv]`
+
+Like the above, but using the static library.
+
+# `test_syslib[_unv]`
+
+Like the above, but using the special "system" version of the dynamic library.
+
+# `test_all[_unv]`
+
+Run all tests against all three libraries.
+
+# `build_tests`
+# `build_tests_static`
+# `build_tests_syslib`
+# `build_tests_all`
+
+Versions of the above run targets which build the tests without running them.