Allow lesser Makefiles to reference installed BLIS.

Details:
- Updated the build system so that "lesser" Makefiles, such as those in
  belonging to example code or the testsuite, may be run even if the
  directory is orphaned from the original build tree. This allows a
  user to configure, compile, and install BLIS, delete the build tree
  (that is, the source distribution, or the build directory for out-
  of-tree builds) and then compile example or testsuite code and link
  against the installed copy of BLIS (provided the example or testsuite
  directory was preserved or obtained from another source). The only
  requirement is that make be invoked while setting the
  BLIS_INSTALL_PATH variable to the same installation prefix used when
  BLIS was configured. The easiest syntax is:

    make BLIS_INSTALL_PATH=/install/prefix

  though it's also permissible to set BLIS_INSTALL_PATH as an
  environment variable prior to running 'make'.
- Updated all lesser Makefiles to implement the new aforementioned build
  behavior.
- Relocated check-blastest.sh and check-blistest.sh from build to
  blastest and testsuite, respectively, so that if those directories are
  copied elsewhere the user can still run 'make check' locally.
- Updated docs/Testsuite.md with language that mentions this new option
  of building/linking against an installed copy of BLIS.

examples/tapi/Makefile

@@ -37,7 +37,7 @@
 #
 # Field G. Van Zee
 #
-# Makefile for BLIS testsuite.
+# Makefile for BLIS typed API example code.
 #
 
 #
@@ -49,13 +49,23 @@
 
 
 #
-# --- Distribution path override -----------------------------------------------
+# --- Determine makefile fragment location -------------------------------------
 #
 
-# Override the default DIST_PATH and BUILD_PATH values so that make can find
-# the source distribution and build location.
-DIST_PATH         := ../..
-BUILD_PATH        := ../..
+# Comments:
+# - DIST_PATH is assumed to not exist if BLIS_INSTALL_PATH is given.
+# - We must use recursively expanded assignment for LIB_PATH and INC_PATH in
+#   the second case because CONFIG_NAME is not yet set.
+ifneq ($(strip $(BLIS_INSTALL_PATH)),)
+LIB_PATH   := $(BLIS_INSTALL_PATH)/lib
+INC_PATH   := $(BLIS_INSTALL_PATH)/include/blis
+SHARE_PATH := $(BLIS_INSTALL_PATH)/share/blis
+else
+DIST_PATH  := ../..
+LIB_PATH    = ../../lib/$(CONFIG_NAME)
+INC_PATH    = ../../include/$(CONFIG_NAME)
+SHARE_PATH := ../..
+endif
 
 
 
@@ -63,23 +73,8 @@ BUILD_PATH        := ../..
 # --- Include common makefile definitions --------------------------------------
 #
 
-# Define the name of the common makefile fragment.
-COMMON_MK_FILE    := common.mk
-
-# Construct the path to the makefile configuration file that was generated by
-# the configure script.
-COMMON_MK_PATH    := $(DIST_PATH)/$(COMMON_MK_FILE)
-
 # Include the common makefile fragment.
--include $(COMMON_MK_PATH)
-
-# Detect whether we actually got the common makefile fragment. If we didn't,
-# then it is likely that the user has not yet generated it (via configure).
-#ifeq ($(strip $(COMMON_MK_INCLUDED)),yes)
-#COMMON_MK_PRESENT := yes
-#else
-#COMMON_MK_PRESENT := no
-#endif
+-include $(SHARE_PATH)/common.mk
 
 
 
@@ -95,6 +90,11 @@ TEST_OBJS      := $(sort $(patsubst $(TEST_SRC_PATH)/%.c, \
                                     $(TEST_OBJ_PATH)/%.o, \
                                     $(wildcard $(TEST_SRC_PATH)/*.c)))
 
+# Override the value of CINCFLAGS so that the value of CFLAGS returned by
+# get-frame-cflags-for() is not cluttered up with include paths needed only
+# while building BLIS.
+CINCFLAGS      := -I$(INC_PATH)
+
 # Use the "framework" CFLAGS for the configuration family.
 CFLAGS         := $(call get-frame-cflags-for,$(CONFIG_NAME))
 
@@ -102,7 +102,7 @@ CFLAGS         := $(call get-frame-cflags-for,$(CONFIG_NAME))
 CFLAGS         += -I$(TEST_SRC_PATH)
 
 # Locate the libblis library to which we will link.
-LIBBLIS_LINK   := $(BUILD_PATH)/$(LIBBLIS_LINK)
+LIBBLIS_LINK   := $(LIB_PATH)/$(LIBBLIS_L)
 
 # Binary executable name.
 TEST_BINS      := 00level1v.x \
@@ -126,23 +126,18 @@ bin: $(TEST_BINS)
 
 
 # --- Environment check rules ---
-#
-#check-env: check-env-make-defs check-env-fragments check-env-mk
-#
-#check-env-mk:
-#ifeq ($(CONFIG_MK_PRESENT),no)
-#    $(error Cannot proceed: config.mk not detected! Run configure first)
-#endif
-#
-#check-env-fragments: check-env-mk
-#ifeq ($(MAKEFILE_FRAGMENTS_PRESENT),no)
-#    $(error Cannot proceed: makefile fragments not detected! Run configure first)
-#endif
-#
-#check-env-make-defs: check-env-fragments
-#ifeq ($(MAKE_DEFS_MK_PRESENT),no)
-#    $(error Cannot proceed: make_defs.mk not detected! Invalid configuration)
-#endif
+
+check-env: check-env-make-defs check-env-fragments check-env-config-mk
+
+check-env-config-mk:
+ifeq ($(CONFIG_MK_PRESENT),no)
+    $(error Cannot proceed: config.mk not detected! Run configure first)
+endif
+
+check-env-make-defs: check-env-fragments
+ifeq ($(MAKE_DEFS_MK_PRESENT),no)
+    $(error Cannot proceed: make_defs.mk not detected! Invalid configuration)
+endif
 
 
 # --Object file rules --

examples/tapi/README

@@ -11,10 +11,19 @@ starts in '00').
 You can build all of the examples by simply running 'make' from this
 directory. (You can also run 'make clean'.) The makefile assumes that
 you've already configured and built (but not necessarily installed) BLIS
-two directories up, in "../..". Once the executable files have been built,
-we recommend reading the code in one terminal window alongside the
-executable output in another. This will help you see the effects of each
-section of code.
+two directories up, in "../..". If you have already installed BLIS to
+some permanent directory, you may refer to that installation by setting
+the environment variable BLIS_INSTALL_PATH prior to running make:
+
+  export BLIS_INSTALL_PATH=/usr/local; make
+
+or by setting the same variable as part of the make command:
+
+  make BLIS_INSTALL_PATH=/usr/local
+
+Once the executable files have been built, we recommend reading the code in
+one terminal window alongside the executable output in another. This will
+help you see the effects of each section of code.
 
 This tutorial is not exhaustive or complete; many typed API functions
 were omitted (mostly for brevity's sake) and thus more examples could be