MAN page from Old RedHat 5.X cdrecord-1.8a21-1.i386.rpm
makefiles
Section: Schily\'s FILE FORMATS (4L)
Updated: 14. February 1997
Index NAME
makerules - system programmers guide for compiling projects on different platforms
SYNOPSIS
SRCROOT= ..RULESDIR= RULESinclude $(SRCROOT)/$(RULESDIR)/rules.toplocal defines are hereinclude $(SRCROOT)/$(RULESDIR)/rules.*See chapter CURRENTLY SUPPORTED TARGET TYPES for possible values of
rules.*.
DESCRIPTION
Makerules is a set of rules that allows compiling of structuredprojects with small and uniformly structured makefiles.All rules are located in a central directory.Compiling the projects on different platforms can be done withoutthe need to modify any of the makefiles that are locatedin the projects directories.
Three make programs are currently supported:Sunpro make,GNU makeandsmake.If you want to add support for other make programs, read the sections about the minimum requirements for a make programand about the structure of the make rule system.
This manual will help programmers who need to make modificationson the make rule system itself. If you want to know something on how to use the makefile systemhave a look at makefiles(4).
The main design goal was to have no definition on more than placein the make rules. This implies that system programmers whowant to add or modify rules must follow this goal in order not todestroy functionality in other places.
The visible result for the user is a set of small and easy to readmakefiles, each located in the project's leaf directory and therefore calledleaf-makefile.
Each of these leaf-makefiles,in fact contains no rule at all. It simply defines some macrosfor the make-programand includes two files from a central make rule depository.These included files define the rules that are needed to compilethe project.
Each leaf-makefileis formed in a really simple way:
- *
- It first defines two macros that define the relative locationof the project's root directory and the name of the directorythat contains the complete set of of rules and then includesthe rule file rules.topfrom the directory that forms the central rule depository.You only have to edit the macroSRCROOTto reflect the relative location of the project's root directory.
- *
- The next part of a leaf-makefiledefines macros that describe the target and the source.You can only have one target per leaf-makefile.Of course, there may be many source files, that are needed to createthat target.If you want to make more than one target in a specific directory,you have to put more than one makefile into that directory.This is the part of a makefile that describes a unique target.Edit this part to contain all source files, all local include filesand all non global compile time flags that are needed for your target.For a typical target this is as simple as filling in a form.
- *
- Eachleaf-makefilefinally includes a file from the rules directory that containsrules for the appropriate type of target that is to be madefrom this leaf-makefile.
The makefile in each directory has to be calledMakefile.If you want to have more than one makefile in a specific directory,you have to choose different names for the other makefiles.
Currently Supported Target Types
There are rules for the following type of targets:
- commands
- The make rules for user level commands likecat, lsetc. are located in the file rules.cmd
- drivers
- The make rules for device driversare located in the file rules.drv
- libraries
- The make rules for non shared librariesare located in the file rules.lib
- shared libraries
- The make rules for shared librariesare located in the file rules.shl
- localized files
- The make rules for localized filesare located in the file rules.loc
- nonlocalized files
- The make rules for non localized filesare located in the file rules.aux
- shell scripts
- The make rules for shell scripts (a variant of localized files)are located in the file rules.scr
- manual pages
- The make rules for manual pages (a variant of localized files)are located in the file rules.man
- diverted makefiles
- The make rules for projects that need to have more thanone makefile in a specific directoryare located in the file rules.mksIt contains a rule that diverts to the listed sub makefiles.Each sub makefile may be of any type.
- directories
- The make rules for sub directoriesare located in the file rules.dir
Minimum Requirements For A Make Program
The make rules currently have support for
Sunpro make,
GNU makeand
smake.If you like to add support for other make programs, they need to have some minimal features that gobeyond the capabilities of the standard
UNIXmakeprogram.
BSDmakecould be supported if it supports pattern matching rules correctly.
- include
- The make program must be able to recursively include other filesfrom within a makefile.The name if the file to include must be allowed to be a macro.The make program must be able to do this in a way thatif the file that should be included may be a result of make rule.e.g if the file to be included does not exist or is outdated,it should be built before an attempt is made to actually include it.
- appending to a macro
- A macro reference of the form:
macro += addval
should appendaddvalto the string that is currently inmacro.
- suffix macro replacement
- A macro reference of the form:
out= $(macro:string1=string2)
should replace a suffixstring1tostring2in all words that are inmacro,where string1 is either a suffix, or a word to be replacedin the macro definition, and string2 is the replacement suffix or word.String1andstring2must be replaced correctly even if they are macros themselves.Words in a macro value are separated by SPACE, TAB, and escaped NEWLINE characters.
- pattern macro replacement
- A macro reference of the form:
out= $(macro:op%os=np%ns)
should replace a central pattern in macro,where op is the existing (old) prefix and osis the existing(old) suffix,np and ns are the new prefix and new suffix,respectively, and the pattern matched by % (a string of zeroor more characters), is carried forward from the value beingreplaced.For example:
PROGRAM=fabricate
DEBUG= $(PROGRAM:%=tmp/%-g)
sets the value of DEBUG to tmp/fabricate-g.Op, os, np and nsmust be replaced correctly even if they are macros themselves.
Understanding Basic Algorithms
One of the basic algorithms used in the make rule systemis needed to set an undefined macro to a guaranteed default value.Because not all make programs have support for
if then elsestructures, a different method has to be used.
The method used inmake rulesis implemented by usingsuffix macro replacementandpattern macro replacement.
First, a macro that contains a unique suffix is defined:
# Define magic unique cookie
_UNIQ= .XxZzy-
This macro is used for all places where it is necessary to have
a macro with a guaranteed default value.The following example shows the basic algorithm that is used toimplement the phrase:If $(MAKE_NAME)contains a value, then$(XMAKEPROG)will be set to$(MAKE_NAME)else$(XMAKEPROG)will be set to$(MAKEPROG).
_MAKEPROG= $(_UNIQ)$(MAKE_NAME)
__MAKEPROG= $(_MAKEPROG:$(_UNIQ)=$(MAKEPROG))
XMAKEPROG= $(__MAKEPROG:$(_UNIQ)%=%)
The first line in this example, sets the macro
_MAKEPROGto the concatenation of the value ofMAKE_NAMEand.XxZzy-.If the macroMAKE_NAMEis empty at this time, _MAKEPROGwill contain only .XxZzy-.
In the second line, __MAKEPROGis set to the value of_MAKEPROG.If _MAKEPROGcontains only .XxZzy-this implies, that.XxZzy-is the suffix. This suffix is then replacedby the value ofMAKEPROG,in this case__MAKEPROGwill contain the unmodified value ofMAKEPROG.If _MAKEPROGcontains a concatenation of.XxZzy-and something else, .XxZzy-will not be a suffix, but a prefix of _MAKEPROGand for this reason__MAKEPROGwill contain the unmodified value of_MAKEPROG,which is a concatenation of.XxZzy-and the value ofMAKE_NAME.
In the third line, XMAKEPROGis set to the value of__MAKEPROG.If __MAKEPROGhas the prefix.XxZzy- at this time, .XxZzy-is stripped of.
The Structure in Make Macro names
The names used for make macrosare structured in a way that allows to use grep(1)to look for the names in the make rules.To allow this, no name must be a substring of another name.
If a command needs options that have to be specifiedin macros, there is a make macrothat is namedXXXFLAGS.This is compliant to usual make file rules.The are internal make macroscalledXXXOPTSandXXXOPTXthat will be combined for XXXFLAGS:
LDFLAGS= $(LDOPTS) $(LDOPTX)
Where XXXOPTSis the name of the macro that is used internallyand XXXOPTXis the name of the macro that may be used from thecommand line of the make program.XXXOPTXtherefore is used to append to the content of XXXFLAGSIf the value ofXXXFLAGSneed to be overwritten, XXXOPTSmay be used within the command line flags of the make program.
The Structure Of The Make Rule System
The Structure Of The Basic Rules in rules.top
The file
RULES/rules.topfirst includes a rule file that depends on the make program that is used.The name of this file is
RULES/mk-makeprog.idwhere
makeproghas to be replaced by the real name ofthe makeprogram e.g.
make,
gmake,
smake.The purpose of this file is to set up a list of macrosthat identify the system where the project is currently built.These macros have values that contain only lower case letters and define:
- the processor architecture
- If two systems run the same operating system, thisis a unique value if a simple user level program willnot need to be recompiled in order to run on the other system.Possible values are sparc, mc68020, pentium.This is the output ofuname -p.The value is stored inP_ARCH.
- the kernel architecture
- If two systems may use the same value for P_ARCHbut a heavily system dependent user level programneed to be recompiled in order to run on the othersystem, These two systems have different kernel architectures.This is the output ofuname -m.Possible values are sun3, sun4c, sun4m.The value is stored inK_ARCH.
- the machine architecture
- An outdated macro that is useful only on sun systems.Do not use this, use P_ARCH instead.This is the output ofarch.Possible values are sun3, sun4.The value is stored inM_ARCH.
- the hostname
- The name of the machine where the compilation takes place.This is the output ofuname -n.The value is stored inHOSTNAME.
- the name of the operating system
- This is the output ofuname -s.Possible values are sunos, dgux, hp-ux, irix.The value is stored inOSNAME.
- the release of the operating system
- This is the output ofuname -r.Possible values are 5.5, 4.1.4.The value is stored inOSREL.
The next file to be included fromRULES/rules.topisRULES/os-operating system.id.It defines the macrosO_ARCHand-O_ARCH and may modify one of the macros that are definedinRULES/mk-makeprog.id.The macrosO_ARCHand-O_ARCH are used to distinguish between different operating systems.The names of the compiler configuration files have-O_ARCH as a central part.On some operating systems e.g. SunOSandDG-UXit is necessary to distinguish between SunOS 4.xandSunOS 5.xorDG-UX 3.xand DG-UX 4.x.
The next file to be included fromRULES/rules.topisDefaults.It defines the macrosDEFCCOM,DEFINCDIRS,LDPATH,RUNPATH,INS_BASEand INS_KBASE.If the definitions have to be different ondifferent systems, this file may contain a line int the form:
include $(SRCROOT)/Defaults.$(O_ARCH)
The actual definitions then have to be moved intothese files.
Next, after setting up some internal defaults,RULES/rules.topincludes the compiler configuration file withthe name:
$(SRCROOT)/$(RULESDIR)/$(XARCH).rul
This file contains all necessary system dependent stuff that is needed to configure the C-compiler on the appropriate system.It is a bad idea to create a new one from scratch.Have a look at the other compiler configurationfiles and modify a similar file for your needs.Note that there are basically two criterias tothat are important in a compiler configuration file.One is whether the system uses theELFheader format or not. The other is whether the system usesshared librariesor not.
The Structure Of The Application Specific Rules
The application specific rule files are designed insuch a way that they include all necessary stuff thatis needed for that specific task. The application specificrule files are:
- $(RULES)/rules.aux
- Rules for installing non localized auxiliary files.
- $(RULES)/rules.cmd
- Rules for commands like sh.
- $(RULES)/rules.dir
- Rules for sub directories.
- $(RULES)/rules.drv
- Rules for lodable drivers.
- $(RULES)/rules.lib
- Rules for static libraries.
- $(RULES)/rules.loc
- Rules for installing localized auxiliary files.
- $(RULES)/rules.man
- Rules for installing localized manual pages.
- $(RULES)/rules.mks
- Rules for sub makefiles.
- $(RULES)/rules.mod
- Rules for lodable stream modules.
- $(RULES)/rules.scr
- Rules for installing localized shell scripts.
- $(RULES)/rules.shl
- Rules for shared libraries.
Understanding The Structure Of The Make Rule System
To understand the structure of the make rulesystem while doing changes, try to use the -xMflagin thesmakeprogram.This flag will print out the include dependency list(i.e. a list that tell you which make rules is includedfrom which other rule).
Note that some of the rules are make program dependent.If you want to make changes to these rules you may need toplace the definitions into separate rule fileseach for the appropriate make program.Have a look into theRULESdirectoryfor some examples.
FILES
.../RULES/*
.../DEFAULTS/*
.../TARGETS/*
.../TEMPLATES/*
SEE ALSO
makefiles(4),
make(1),
gmake(1),
smake(1).
DIAGNOSTICS
Diagnostic messages depend on the make program.Have a look at the appropriate man page.
NOTES
The make rulescan be used with Sunpro make, Gnu makeand smake.Although Gnu make runs on many platforms, it has no useful debugoutput.
UseSunpro make or smakeif you have problems with a makefile.Sunpro make and smake,both have a -D flag, that allows you to watch the makefilesafter the first expansion. Use this option, if you are in doubtif your makefile gets expanded the right way and if the rightrules are included.There is also a -d option that gives debugging output while make is running. If you want more output, use -dd, -ddd and so on.
Smakehas an option -xM that shows you the include dependency formake rules.
BUGS
Source Tree Hierarchy
The following outline gives a quick tour through a typicalsource hierarchy:
- .../
- root directory of the source tree
- Makefile
- the top Makefile
- Defaults
- default definitions for that source tree. System dependentdefinitions are in .../DEFAULTS/
- Targetdirs
- a file containing a list of directories that are neededfor that project.If the system needs different target lists dependingon the target system architecture , use target specific files in.../TARGETS/
- ...
- .../RULES/
- the location of makefiles (included rules)
- rules.top
- the mandatory include rules (needed to setup basic rules)
- rules.aux
- rules needed to install a non localized auxiliary file
- rules.cmd
- rules needed to make an ordinary command (like /bin/sh)
- rules.drv
- rules needed to make a device driver
- rules.lib
- rules needed to make a standard (nonshared) library
- rules.loc
- rules needed to install a localized auxiliary file
- rules.man
- rules needed to install a localized manual page
- rules.scr
- rules needed to install a localized shell script
- rules.shl
- rules needed to make a shared library
- rules.mks
- rules needed to make more than one target in a specific directory
- rules.dir
- rules needed to make targets that are located in sub directoriesto the current directory
- ...
- .../DEFAULTS/
- default definitions for various target architectures arelocated in this directory. Templates for some architectures canbe found in the.../TEMPLATES/directory.
- .../TARGETS/
- target list definitions for various target architectures arelocated in this directory.
- .../TEMPLATES/
- templates that should be used inside the project(rename to Makefile, if it is the only makefile on that directory, rename totarget.mk,if there is more than one target in that directory)
- Defaults
- Defaults file for the source root directory
- Defaults.linux
- Defaults file for linux.This sould be installed in the .../DEFAULTS/directory.
- Makefile.root
- Makefile for the source root directory
- Makefile.aux
- Makefile for a non localized auxiliary file
- Makefile.cmd
- Makefile for an ordinary command (like /bin/sh)
- Makefile.lib
- Makefile for a standard (nonshared) library
- Makefile.loc
- Makefile for a localized auxiliary file
- Makefile.man
- Makefile for a localized manual page
- Makefile_de.man
- Makefile for a localized manual page in the german locale
- Makefile.scr
- Makefile for a localized shell script
- Makefile.shl
- Makefile for a shared library
- Makefile.drv
- Makefile for a device driver
- Makefile.mks
- Makefile for more than one target in a specific directory
- Makefile.dir
- Makefile for targets that are located in sub directoriesto the current directory
- ...
- .../cmd/
- source tree for normal commands
- Makefile
- the makefile for the cmd sub directory
- Targetdirs.sun4m
- a file containing a list of directories like myprog (see below) that are neededfor that specific architecture.
- myprog/
- directory where the sources for a specific command are located
- Makefile
- makefile formyprog
- Makefile.man
- makefile for the manual page ofmyprog
- mprog.c
- source for myprog
- mprog.tr
- troff source for the manual page of myprog
- OBJ/
- directory where system specific sub directories are located
- sparc-sunos5-cc/
- directory for binaries that belong to a specific system
- ...
- ...
- ...
- .../lib/
- directory where the sources for a libraries are located
- Makefile
- the makefile for the lib sub directory
- Targetdirs.sun4m
- a file containing a list of directories like libfoo(see below) that are neededfor that specific architecture.
- libfoo/
- directory where all source files for libfoo are located
- ...
- .../kernel
- directory for kernel modules
- Makefile
- the makefile for the kernelsub directory
- Targetdirs.sun4m
- a file containing a list of directories like drv (see below) that are neededfor that specific architecture.
- drv/
- directory where drivers are located
- Makefile
- the makefile for the drvsub directory
- Targetdirs.sun4m
- a file containing a list of directories like mydrv(see below) that are neededfor that specific architecture.
- mydrv/
- source for a specific driver
- ...
- ...
- .../include
- directory for global include files that are used in that project
- .../bins
- directory for binary programs that are created/needed while compilingthe project
- sparc-sunos5-cc/
- directory for binaries that belong to a specific system
- ...
- .../libs
- directory for libraries that are created/needed while compilingthe project
- sparc-sunos5-cc/
- directory for libraries that belong to a specific system
- ...
- .../incs
- directory for include files that are created/needed while compilingthe project
- sparc-sunos5-cc/
- directory for include files that belong to a specific system
- ...
- ...
AUTHOR
Joerg SchillingSeestr. 110D-13353 BerlinGermany
Mail bugs and suggestions to:
joergAATTschily.isdn.cs.tu-berlin.deorjsAATTcs.tu-berlin.deorjesAATTfokus.gmd.de
Index
- NAME
- SYNOPSIS
- DESCRIPTION
- Currently Supported Target Types
- Minimum Requirements For A Make Program
- Understanding Basic Algorithms
- The Structure in Make Macro names
- The Structure Of The Make Rule System
- The Structure Of The Basic Rules in rules.top
- The Structure Of The Application Specific Rules
- Understanding The Structure Of The Make Rule System
- FILES
- SEE ALSO
- DIAGNOSTICS
- NOTES
- BUGS
- Source Tree Hierarchy
- AUTHOR
This document was created byman2html,using the manual pages.
