Removed PROJECT_HOME and CONFIG_DIR variables.

1 files changed, 518 insertions, 0 deletions

diff --git a/make/README b/make/README
new file mode 100644
index 0000000000..6d4b7501b4
--- /dev/null
+++ b/make/README
@@ -0,0 +1,518 @@
+#
+#  $Id$
+#
+
+    make/README
+
+    This file describes the layout and conventions of the make tree used in
+    the RTEMS software project and others.
+    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:
+
+        .  simple *and* customizable individual makefiles
+
+        .  use widely available GNU make.  There is no pre-processing or
+            automatic generation of Makefiles.
+
+        .  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
+            on a per-user basis.  Using the same sources (including
+            Makefiles) one developer can develop and test under SVR4,
+            another under 4.x, another under HPUX.
+
+        .  Builtin support for compiling "variants" such as debug,
+            profile, and tcov versions.  These variants can be built
+            recursively.
+
+        .  Control of system dependencies.  "hidden" dependencies on
+            environment variables (such as PATH)
+            have been removed whenever possible.  No matter what your
+            PATH variable is set to, you should get the same thing
+            when you 'make' as everyone else on the project.
+
+    This description attempts to cover all aspects of the Makefile tree.  Most
+    of what is described here is maintained automatically by the configuration
+    files.
+
+    The example makefiles in make/Templates should be used as a starting
+    point for new directories.
+
+    There are 2 main types of Makefile:
+
+        directory and leaf.
+
+    Directory Makefiles
+    -------------------
+
+        A Makefile in a source directory with sub-directories is called a
+        "directory" Makefile.
+
+        Directory Makefile's are simply responsible for acting as "middle-men"
+        and recursing into their sub-directories and propagating the make.
+
+        For example, directory src/bin will contain only a Makefile and
+        sub-directories.  No actual source code will reside in the directory.
+        The following commands:
+
+            $ cd src/bin
+            $ make all
+
+        would descend into all the subdirectories of 'src/bin' and recursively
+        perform a 'make all'.
+
+        A 'make debug' will recurse thru sub-directories as a debug build.
+
+        A template directory Makefile which should work in almost all
+        cases is in make/Templates/Makefile.dir
+
+
+    Leaf Makefiles
+    --------------
+
+        Source directories that contain source code for libraries or
+        programs use a "leaf" Makefile.
+
+        These makefiles contain the rules necessary to build programs
+        (or libraries).
+
+        A template leaf Makefile is in Templates/Makefile.leaf .  A template
+        leaf Makefile for building libraries is in Templates/Makefile.lib .
+
+
+    NOTE: To simplify nested makefile's and source maintenance, we disallow
+    combining source and directories (that make(1) would be expected to
+    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.
+
+    Variants (where objects go)
+    ---------------------------
+
+        All binary targets are placed in a sub-directory whose name is (for
+        example):
+
+            o-force386/                -- binaries (no debug, no profile)
+            o-force386-debug/          -- debug binaries
+            o-force386-profile/        -- profiling binaries
+
+        Using the template Makefiles, this will all happen automatically.
+
+        Within a Makefile, the ${ARCH} variable is set to o-force386,
+        o-force386-debug, etc., as appropriate.
+
+        Typing 'make' will place objects in o-force386.
+        'make debug' will place objects in o-force386-debug.
+        'make profile' will place objects in o-force386-profile.
+
+        NOTE:  For RTEMS work, the word 'force386' is the specified
+               RTEMS_BSP (specified in the modules file)
+
+        The debug and profile targets are equivalent to 'all' except that
+        CFLAGS and/or LDFLAGS are modified as per the compiler config file for
+        debug and profile support.
+
+        Targets debug_install and profile_install are equivalent to 'make
+        install' except that debug (or profile) variants are built and
+        installed.
+
+        The targets debug, profile, debug_install, profile_install, 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
+            $ gmake debug_install
+
+        When building a command that is linked with a generated library, the
+        appropriate version of the library will be linked in.
+
+        For example, the following fragments link the normal, debug, or
+        profile version of "libmine.a" as appropriate:
+
+            LDLIBS   += $(LIBMINE)
+            LIBMINE = ../libmine/${ARCH}/libmine.a
+
+            ${ARCH}/pgm: $(LIBMINE) ${OBJS}
+                $(LINK.c) -o $@ ${OBJS} $(LDLIBS)
+
+        If we do 'gmake debug', then the library in
+        ../libmine/sparc-debug/libmine.a will be linked in.  If $(LIBMINE)
+        might not exist (or might be out of date) at this point, we could add
+
+            ${LIBMINE}: FORCEIT
+	        cd ../libmine; ${MAKE} ${VARIANT_VA}
+
+        The above would generate the following command to build libmine.a:
+
+            cd ../libmine; gmake debug
+
+        The macro reference ${VARIANT_VA} converts ${ARCH} to the word 'debug'
+        (in this example) and thus ensures the proper version of the library
+        is built.
+
+
+    Targets
+    -------
+
+        All Makefile's support the following targets:
+
+            all                     -- make "everything"
+            install                 -- install "everything"
+
+        The following targets are provided automatically by
+        the included config files:
+
+            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
+
+
+        All directory Makefiles automatically propagate all these targets.  If
+        you don't wish to support 'all' or 'install' in your source directory,
+        you must leave the rules section empty, as the parent directory Makefile
+        will attempt it on recursive make's.
+
+
+    Configuration
+    -------------
+
+        All the real work described here happens in file(s) included
+        from your Makefile.
+
+        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/force386.cfg
+
+        All leaf Makefile's also include either 'make/leaf.cfg' (or
+        'make/lib.cfg' for building libraries).  These config files provide
+        default rules and set up the command macros as appropriate.
+
+        All directory Makefiles include 'make/directory.cfg'.  directory.cfg
+        provides all the rules for recursing through sub directories.
+
+        The Makefile templates already perform these include's.
+
+        'make/leaf.cfg' (or directory.cfg) in turn includes:
+
+            a file specifying general purpose rules appropriate for
+                both leaf and directory makefiles.
+                ( make/main.cfg )
+
+            personality modules specified by the customization file for:
+                compiler            ( make/compilers/??.cfg )
+                operating system    ( make/os/??.cfg )
+
+
+        private customization files
+        ---------------------------
+
+            [ $(RTEMS_CUSTOM) ]
+
+            Your own private configuration file.  Specifies which of the above
+            files you want to include.
+
+            Example: custom/force386.cfg
+
+               CONFIG.$(HOST_ARCH).OS = $(RTEMS_ROOT)/make/os/HPUX-9.0.cfg
+
+               # HOST Compiler config file
+               # You may also want to specify where the compiler resides here.
+               CC_$(HOST_ARCH)_DIR=/usr/local
+               CONFIG.$(HOST_ARCH).CC   = $(RTEMS_ROOT)/make/compilers/gcc.cfg
+
+               ## Target compiler config file, if any
+               CC_$(TARGET_ARCH)_DIR=$(RTEMS_GNUTOOLS)
+               CONFIG.$(TARGET_ARCH).CC = $(RTEMS_ROOT)/make/compilers/gcc-force386.cfg
+
+        generic rules file
+        ------------------
+
+            [ make/main.cfg ]
+            included by leaf.cfg or directory.cfg.
+
+            This file contains some standard rules and variable assignments
+            that all Makefiles need.
+
+            It also includes the FORCEIT: pseudo target.
+
+
+        OS config file for host machine
+        -------------------------------
+
+            [ make/os/OS-NAME.cfg ]
+            included by main.cfg
+
+            Figures out the target architecture and specifies command names
+            for the OS tools including RCS/CVS (but NOT for the compiler tools).
+
+
+        Compiler configuration for the target
+        -------------------------------------
+
+            [ compilers/COMPILER-NAME.cfg ]
+            included by leaf.cfg
+
+            Specifies the names of tools for compiling programs.
+            Names in here should be fully qualified, and NOT depend on $PATH.
+
+            Also specifies compiler flags to be used to generate optimized,
+            debugging and profile versions, as well as rules to compile
+            assembly language and make makefile dependencies.
+
+
+    Configuration Variables
+    -----------------------
+
+        Variables you have to set in the environment or in your Makefile.
+        Note: the rtems module files set RTEMS_ROOT and RTEMS_CUSTOM
+        for you.
+
+        Environment Variables
+        ---------------------
+
+            RTEMS_BSP      -- name of your 'bsp' eg: force386
+
+            RTEMS_ROOT     -- The root of your source tree.
+                              All other file names are derived from this.
+                              [ eg: % setenv RTEMS_ROOT $HOME/work/rtems ]
+
+            RTEMS_CUSTOM   -- name of your config files in make/custom
+                              Example:
+                                 $(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_TOOLS
+
+            etc., which are used within the make config files themselves.
+            (The files in make/*.cfg try to avoid use of word RTEMS so
+            they can be more easily shared by other projects)
+
+        Preset variables
+        ----------------
+
+            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.
+
+            CONFIG.$(HOST_ARCH).OS
+                        -- full path of OS config file, set by
+                           custom config file.
+
+            CONFIG.$(HOST_ARCH).CC
+                        -- full path of C compilation config file, set by custom
+                           config file.
+
+            PROJECT_RELEASE
+                        -- release/install directory
+                           [ $(PROJECT_ROOT) ]
+
+            PROJECT_BIN
+                        -- directory for installed binaries
+                           [ $(PROJECT_ROOT)/bin ]
+
+            PROJECT_TOOLS
+                        -- directory for build environment commands
+                           [ 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-force386 or o-force386-debug ]
+
+            HOST_ARCH
+                        -- host machine architecture name
+                           [ eg: sun4, sparc on SVR4 ]
+
+            VARIANTS    -- full list of all possible values for $(ARCH);
+                           used mainly for 'make clean'
+                           [ eg: "o-force386 o-force386-debug o-force386-profile" ]
+
+            VARIANT_VA  -- Variant name.
+                           Normally "", but for 'make debug' it is "debug",
+                           for 'make profile', "profile, etc.
+
+                           see make/leaf.cfg for more info.
+
+
+        Preset compilation variables
+        ----------------------------
+
+          This is a list of some of the compilation variables.
+          Refer to the compiler config files for the complete list.
+
+            CFLAGS_OPTIMIZE_V   -- value of optimize flag for compiler
+                                   [ eg: -O ]
+
+            CFLAGS_DEBUG_V      -- value of debug flag for compiler
+                                   [ eg: -g ]
+
+            CFLAGS_PROFILE_V    -- compiler profile flags
+                                   [ eg: -pg ]
+
+            CFLAGS_DEBUG_OPTIMIZE_V
+                                -- optimize flag if compiling for debug
+                                     [ eg: "" ]
+
+            CFLAGS_DEBUG
+            CFLAGS_PROFILE
+            CFLAGS_OPTIMIZE     -- current values for each depending
+                                    on make variant.
+
+            LDFLAGS_STATIC_LIBRARIES_V
+                                -- ld option for static libraries
+                                    -Bstatic or -dy (svr4)
+
+            LDFLAGS_SHARED_LIBRARIES_V
+                                -- ld option for dynamic libraries
+                                    -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
+            ------------------
+
+                The following variables may be set in a typical Makefile.
+
+                C_PIECES    -- File names of your .c files without '.c' suffix.
+                               [ eg: C_PIECES=main funcs stuff ]
+
+                CC_PIECES   -- ditto, except for .cc files
+
+                S_PIECES    -- ditto, except for .S files.
+
+                LIB         -- target library name in leaf library makefiles.
+                               [ eg: LIB=${ARCH}/libmine.a ]
+
+                H_FILES     -- your .h files in this directory.
+                               [ eg: H_FILES=stuff.h extra.h ]
+
+                DEFINES     -- cc -D items.  Included in CPPFLAGS.
+                               leaf Makefiles.
+                               [ eg: DEFINES += -DUNIX ]
+
+                CPPFLAGS    -- -I include directories.
+                               leaf Makefiles.
+                               [ eg: CPPFLAGS += -I../include ]
+
+                YFLAGS      -- Yacc flags.
+                               leaf Makefiles.
+                               [ eg: YFLAGS += -v ]
+
+                LD_PATHS    -- arguments to -L for ld.
+                               Will be prefixed with '-L' or '-L ' as appropriate
+                               and included in LDFLAGS.
+
+                LDFLAGS     -- -L arguments to ld; more may be ADDed.
+
+                LD_LIBS     -- libraries to be linked in.
+                               [ eg: LDLIBS += ../libfoo/${ARCH}/libfoo.a ]
+
+                XCFLAGS     -- "extra" CFLAGS for special needs.  Pre-pended
+                               to CFLAGS.
+                               Not set or used by Makefiles.
+                               Can be set on command line to pass extra flags
+                               to the compiler.
+
+                XCPPFLAGS   -- ditto for CPPFLAGS
+                               Can be set on command line to pass extra flags
+                               to the preprocessor.
+
+                XCCPPFLAGS  -- same as XCPPFLAGS for C++.
+
+                XCCFLAGS    -- same as XCFLAGS for C++.
+
+                SUB_DIRS    -- list of sub directories for make recursion.
+                               directory Makefiles only.
+                               [ eg: SUB_DIRS=cpu bsp ]
+
+                CLEAN_ADDITIONS
+                            -- list of files or directories that should
+                               be deleted by 'make clean'
+                               [ eg: CLEAN_ADDITIONS += y.tab.c ]
+
+                               See 'leaf.cfg' for the 'clean:' rule and its
+                               default deletions.
+
+                CLOBBER_ADDITIONS
+                            -- list of files or directories that should
+                               be deleted by 'make clobber'
+                               Since 'make clobber' includes 'make clean',
+                               you don't need to duplicate items in both.
+
+                TARGET_ARCH -- target architecture (eg: o-force386)
+                               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
+            -------------
+
+                The following commands should only be called
+                as make variables:
+
+                    MAKE,INSTALL,SHELL
+
+                    ECHO,CAT,RM,CP,MV,LN,MKDIR,CHMOD
+
+                    ED,SED
+
+                    CC,CPP,AS,AR,LD,NM,SIZE,RANLIB,MKLIB,
+                    YACC,LEX,LINT,CTAGS,ETAGS
+
+            Special Directory Makefile Targets
+            ----------------------------------
+
+                all_WRAPUP
+                clean_WRAPUP
+                install_WRAPUP
+                clean_WRAPUP
+                clobber_WRAPUP
+                depend_WRAPUP
+                            -- Specify additional commands for recursive
+                               (directory level) targets.
+
+                               This is handy in certain cases where you need
+                               to do bit of work *after* a recursive make.
+
+    make/Templates
+    --------------
+
+        This directory contains Makefile and source file templates that
+        should help in creating or converting makefiles.
+
+        Makefile.leaf
+            Template leaf Makefiles.
+
+        Makefile.lib
+            Template leaf library Makefiles.
+
+        Makefile.dir
+            Template "directory" makefile.
+
+
+