From bffb93879940c71c58d2c66410e1bd5e5e4dc979 Mon Sep 17 00:00:00 2001 From: Joel Sherrill Date: Tue, 20 Jan 1998 19:30:30 +0000 Subject: Removed PROJECT_HOME and CONFIG_DIR variables. --- make/README | 518 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 518 insertions(+) create mode 100644 make/README (limited to 'make/README') 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. + + + -- cgit v1.2.3