From df49c60c9671e4a28e636964d744c1f59fb6cb68 Mon Sep 17 00:00:00 2001 From: Joel Sherrill Date: Mon, 12 Jun 2000 15:00:15 +0000 Subject: Merged from 4.5.0-beta3a --- make/README | 158 +++++++++++++++++++++++++++++++----------------------------- 1 file changed, 82 insertions(+), 76 deletions(-) (limited to 'make/README') diff --git a/make/README b/make/README index 911d2b8aea..8a3d599aef 100644 --- a/make/README +++ b/make/README @@ -4,21 +4,26 @@ 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. + file documents the current state of the RTEMS Application Makefile + support. - This make tree was developed originally to simplify porting projects - between various os's. The primary goals are: + 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 . 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. + . 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 @@ -35,6 +40,13 @@ PATH variable is set to, you should get the same thing 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 files. @@ -88,7 +100,7 @@ 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. + both. This assumption is generally shared with GNU automake. Variants (where objects go) --------------------------- @@ -96,30 +108,30 @@ All binary targets are placed in a sub-directory whose name is (for 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. + o-optimize/ -- optimized binaries + o-debug/ -- debug binaries + o-profile/ -- profiling binaries - Within a Makefile, the ${ARCH} variable is set to o-pc386, - o-pc386-debug, etc., as appropriate. + Using the template Makefiles, this will all happen automatically. + The contents of these directories are specific to a BSP. - 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. + Within a Makefile, the ${ARCH} variable is set to o-optimize, + o-debug, etc., as appropriate. - NOTE: For RTEMS work, the word 'pc386' is the specified - RTEMS_BSP (specified in the modules file) + 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 CFLAGS and/or LDFLAGS are modified as per the compiler config file for 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 $ gmake debug @@ -131,14 +143,14 @@ For example, the following fragments link the normal, debug, or 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 ${LIBMINE}: FORCEIT @@ -165,9 +177,6 @@ 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 @@ -186,9 +195,9 @@ 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: + RTEMS_MAKEFILE_PATH must point to the directory containing this file; eg: - /.../make/custom/pc386.cfg + export RTEMS_MAKEFILE_PATH=/.../pc386/ All leaf Makefile's also include either 'make/leaf.cfg' (or 'make/lib.cfg' for building libraries). These config files provide @@ -209,14 +218,6 @@ compiler ( make/compilers/??.cfg ) - private customization files - --------------------------- - - [ $(RTEMS_CUSTOM) ] - - Your own private configuration file. Specifies which of the above - files you want to include. - generic rules file ------------------ @@ -257,29 +258,32 @@ ----------------------- 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 - --------------------- + Makefile Variables + ------------------ + + RTEMS_BSP -- name of your 'bsp' eg: pc386, mvme136 + + RTEMS_CPU -- CPU architecture e.g.: i386, m68k - RTEMS_BSP -- name of your 'bsp' eg: pc386 + 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 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_BIN + PROJECT_INCLUDE PROJECT_TOOLS etc., which are used within the make config files themselves. @@ -289,7 +293,7 @@ Preset variables ---------------- - 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. @@ -305,16 +309,12 @@ -- 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-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. Normally "", but for 'make debug' it is "debug", @@ -355,14 +355,6 @@ -- 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 ------------------ @@ -389,10 +381,6 @@ 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. @@ -434,27 +422,44 @@ Since 'make clobber' includes 'make clean', 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 ------------- The following commands should only be called as make variables: - MAKE,INSTALL,SHELL + MAKE,INSTALL,INSTALL_VARIANT,SHELL - ECHO,CAT,RM,CP,MV,LN,MKDIR,CHMOD + ECHO,CAT,CP,MV,LN,MKDIR,CHMOD - ED,SED + 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 ---------------------------------- @@ -486,4 +491,5 @@ Template "directory" makefile. + -- cgit v1.2.3