Index: c/src/make/README
===================================================================
--- c/src/make/README	(revision 9608320702e8dba9947987cd34001824638c434e)
+++ c/src/make/README	(revision df49c60c9671e4a28e636964d744c1f59fb6cb68)
@@ -5,11 +5,16 @@
     make/README
 
-    This file describes the layout and conventions of the make tree used in
-    the RTEMS software project and others.
+    This file describes the layout and conventions of the application
+    makefile support for RTEMS applications.  Internally, RTEMS uses
+    GNU-style autoconf/automake Makefiles as much as possible to 
+    ease integration with other GNU tools.
+
     All of these "make" trees are substantially similar; however this
-    file documents the current state of the rtems Makefile tree.
-
-    This make tree was developed originally to simplify porting projects
-    between various os's.  The primary goals are:
+    file documents the current state of the RTEMS Application Makefile
+    support.
+
+    This make tree is based on a build system originally developed
+    to simplify porting projects between various OS's.  The primary
+    goals were:
 
         .  simple *and* customizable individual makefiles
@@ -18,6 +23,6 @@
             automatic generation of Makefiles.
 
-        .  Same makefiles work on *many* host os's due to portability
-            of GNU make and the host os config files.
+        .  Same makefiles work on *many* host OS's due to portability
+            of GNU make and the host OS config files.
 
         .  Support for different compilers and operating systems
@@ -36,4 +41,11 @@
             when you 'make' as everyone else on the project.
 
+    This Makefile system has evolved into its present form and as it
+    exists in RTEMS today, its sole goal is to build RTEMS applications.
+    The use of these Makefiles hides the complexity of producing
+    executables for a wide variety of embedded CPU families and target
+    BSPs.  Switching between RTEMS BSPs is accomplished via setting
+    the environment variable "RTEMS_MAKEFILE_PATH."
+
     This description attempts to cover all aspects of the Makefile tree.  Most
     of what is described here is maintained automatically by the configuration
@@ -89,5 +101,5 @@
     recurse into) in one source directory.  Ie., a directory in the source
     tree may contain EITHER source files OR recursive sub directories, but NOT
-    both.
+    both.  This assumption is generally shared with GNU automake.
 
     Variants (where objects go)
@@ -97,19 +109,20 @@
         example):
 
-            o-pc386/                -- binaries (no debug, no profile)
-            o-pc386-debug/          -- debug binaries
-            o-pc386-profile/        -- profiling binaries
-
-        Using the template Makefiles, this will all happen automatically.
-
-        Within a Makefile, the ${ARCH} variable is set to o-pc386,
-        o-pc386-debug, etc., as appropriate.
-
-        Typing 'make' will place objects in o-pc386.
-        'make debug' will place objects in o-pc386-debug.
-        'make profile' will place objects in o-pc386-profile.
-
-        NOTE:  For RTEMS work, the word 'pc386' is the specified
-               RTEMS_BSP (specified in the modules file)
+            o-optimize/       -- optimized binaries
+            o-debug/          -- debug binaries
+            o-profile/        -- profiling binaries
+
+        Using the template Makefiles, this will all happen automatically. 
+        The contents of these directories are specific to a BSP.
+
+        Within a Makefile, the ${ARCH} variable is set to o-optimize,
+        o-debug, etc., as appropriate.
+
+        HISTORICAL NOTE: Prior to version 4.5, the name of the sub-directory
+          in which objects were placed included the BSP name.
+           
+        Typing 'make' will place objects in o-optimize.
+        'make debug' will place objects in o-debug.
+        'make profile' will place objects in o-profile.
 
         The debug and profile targets are equivalent to 'all' except that
@@ -117,8 +130,7 @@
         debug and profile support.
 
-        The targets debug, profile, etc., can be
-        invoked recursively at the directory make level.  So from the top of a
-        tree, one could install a debug version of everything under that point
-        by:
+        The targets debug, profile, etc., can be invoked recursively at
+        the directory make level.  So from the top of a tree, one could
+        install a debug version of everything under that point by:
 
             $ cd src/lib
@@ -132,12 +144,12 @@
         profile version of "libmine.a" as appropriate:
 
-            LDLIBS   += $(LIBMINE)
+            LD_LIBS   += $(LIBMINE)
             LIBMINE = ../libmine/${ARCH}/libmine.a
 
             ${ARCH}/pgm: $(LIBMINE) ${OBJS}
-                $(LINK.c) -o $@ ${OBJS} $(LDLIBS)
+                $(make-exe)
 
         If we do 'gmake debug', then the library in
-        ../libmine/sparc-debug/libmine.a will be linked in.  If $(LIBMINE)
+        ../libmine/o-debug/libmine.a will be linked in.  If $(LIBMINE)
         might not exist (or might be out of date) at this point, we could add
 
@@ -166,7 +178,4 @@
 
             clean                   -- delete all targets
-            clobber                 -- 'clean' plus delete sccs'd files
-            lint                    -- run lint or lint-like tool
-            get                     -- "sccs get" all sources
             depend                  -- build a make dependency file
             "variant targets"       -- special variants, see below
@@ -187,7 +196,7 @@
         All Makefiles include a customization file which is used to select
         compiler and host operating system.  The environment variable
-        RTEMS_CUSTOM must point to this file; eg:
-
-                /.../make/custom/pc386.cfg
+        RTEMS_MAKEFILE_PATH must point to the directory containing this file; eg:
+
+                export RTEMS_MAKEFILE_PATH=/.../pc386/
 
         All leaf Makefile's also include either 'make/leaf.cfg' (or
@@ -210,12 +219,4 @@
 
 
-        private customization files
-        ---------------------------
-
-            [ $(RTEMS_CUSTOM) ]
-
-            Your own private configuration file.  Specifies which of the above
-            files you want to include.
-
         generic rules file
         ------------------
@@ -258,15 +259,19 @@
 
         Variables you have to set in the environment or in your Makefile.
-        Note: the rtems module files set RTEMS_ROOT and RTEMS_CUSTOM
+        Note: the RTEMS module files set RTEMS_ROOT and RTEMS_CUSTOM
         for you.
 
-        Environment Variables
-        ---------------------
-
-            RTEMS_BSP      -- name of your 'bsp' eg: pc386
+        Makefile Variables
+        ------------------
+
+            RTEMS_BSP        -- name of your 'bsp' eg: pc386, mvme136
+
+            RTEMS_CPU        -- CPU architecture e.g.: i386, m68k
+
+            RTEMS_CPU_FAMILY -- CPU model e.g.: i486dx, m68020
 
             RTEMS_ROOT     -- The root of your source tree.
                               All other file names are derived from this.
-                              [ eg: % setenv RTEMS_ROOT $HOME/work/rtems ]
+                              [ eg: % setenv RTEMS_ROOT $HOME/work/RTEMS ]
 
             RTEMS_CUSTOM   -- name of your config files in make/custom
@@ -274,11 +279,10 @@
                                  $(RTEMS_ROOT)/make/custom/$(RTEMS_BSP).cfg
 
-            RTEMS_GNUTOOLS -- root of the gcc tools for the target
-
             The value RTEMS_ROOT is used in the custom
             files to generate the make(1) variables:
 
-                PROJECT_ROOT
                 PROJECT_RELEASE
+                PROJECT_BIN
+                PROJECT_INCLUDE
                 PROJECT_TOOLS
 
@@ -290,5 +294,5 @@
         ----------------
 
-            Aside from command names set by the os and compiler config files,
+            Aside from command names set by the OS and compiler config files,
             a number of MAKE variables are automatically set and maintained by
             the config files.
@@ -306,14 +310,10 @@
                            [ eg: $(PROJECT_ROOT)/build-tools ]
 
-            TARCH       -- ${TARGET_ARCH}
-                           [ eg: o-forc386 ]
-                           obsolete and should not be referenced
-
             ARCH        -- target sub-directory for object code
-                           [ eg: o-pc386 or o-pc386-debug ]
+                           [ eg: o-optimize or o-debug ]
 
             VARIANTS    -- full list of all possible values for $(ARCH);
                            used mainly for 'make clean'
-                           [ eg: "o-pc386 o-pc386-debug o-pc386-profile" ]
+                           [ eg: "o-optimize o-debug o-profile" ]
 
             VARIANT_VA  -- Variant name.
@@ -356,12 +356,4 @@
                                     -Bdynamic or -dn (svr4)
 
-            LIB_SOCKET
-                                -- ld(1) -l option(s) to provide
-                                    socket support.
-
-            LIB_MATH            -- ld(1) -l option(s) to provide
-                                    math library.
-
-
             Makefile Variables
             ------------------
@@ -389,8 +381,4 @@
                                leaf Makefiles.
                                [ eg: CPPFLAGS += -I../include ]
-
-                YFLAGS      -- Yacc flags.
-                               leaf Makefiles.
-                               [ eg: YFLAGS += -v ]
 
                 LD_PATHS    -- arguments to -L for ld.
@@ -435,10 +423,4 @@
                                you don't need to duplicate items in both.
 
-                TARGET_ARCH -- target architecture (eg: o-pc386)
-                               leaf makefiles only.
-                               Should be specified before 'include leaf.cfg'.
-                               Only needs to be specified if your target is
-                               different from output of `arch`.
-
             Command names
             -------------
@@ -447,12 +429,35 @@
                 as make variables:
 
-                    MAKE,INSTALL,SHELL
-
-                    ECHO,CAT,RM,CP,MV,LN,MKDIR,CHMOD
-
-                    ED,SED
+                    MAKE,INSTALL,INSTALL_VARIANT,SHELL
+
+                    ECHO,CAT,CP,MV,LN,MKDIR,CHMOD
+
+                    SED
 
                     CC,CPP,AS,AR,LD,NM,SIZE,RANLIB,MKLIB,
                     YACC,LEX,LINT,CTAGS,ETAGS
+
+                 In addition, the following commands specifically support
+                 the installation of libraries, executables, header files,
+                 and other things that need to be installed:
+
+                    INSTALL_CHANGE  - install a file only if the source
+                                      file is actually different than
+                                      the installed copy or if there is
+                                      no installed copy.  USAGE:
+
+      usage: install-if-change [ -vmV ] file [ file ... ] dest-directory-or-file
+	-v	    -- verbose
+        -V suffix   -- suffix to append to targets (before any . suffix)
+                        eg: -V _g would change 'foo' to 'foo_g' and
+                                               'libfoo.a' to 'libfoo_g.a'
+        -m mode     -- mode for new file(s)
+
+                    INSTALL_VARIANT - installs the built file using the
+                                      proper variant suffix (e.g. _g
+                                      for debug turns libmine.a into libmine_g.a)
+                                      This is implemented as a macro that
+                                      invokes install-if-change with the
+                                      appropriate -V argument setting.
 
             Special Directory Makefile Targets
@@ -487,3 +492,4 @@
 
 
-
+    
+
