summaryrefslogtreecommitdiffstats
path: root/make/README
diff options
context:
space:
mode:
authorJoel Sherrill <joel.sherrill@OARcorp.com>1998-01-20 19:30:30 +0000
committerJoel Sherrill <joel.sherrill@OARcorp.com>1998-01-20 19:30:30 +0000
commitbffb93879940c71c58d2c66410e1bd5e5e4dc979 (patch)
tree2b13eb892f6022cb62a7847f2d27fb44e5e313ae /make/README
parent3294650cc34a7b1e6e669ecd4f95fba26ac4b97d (diff)
downloadrtems-bffb93879940c71c58d2c66410e1bd5e5e4dc979.tar.bz2
Removed PROJECT_HOME and CONFIG_DIR variables.
Diffstat (limited to 'make/README')
-rw-r--r--make/README518
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.
+
+
+