makerules.4

创建一个符合iso-9660标准的iso文件系统

. \" @(#)makerules.4	1.2 97/02/14 Copyr 1996 J. Schilling
. \" System Manual page for makefile system
. \"
.if t .ds a \v'-0.55m'\h'0.00n'\z.\h'0.40n'\z.\v'0.55m'\h'-0.40n'a
.if t .ds o \v'-0.55m'\h'0.00n'\z.\h'0.45n'\z.\v'0.55m'\h'-0.45n'o
.if t .ds u \v'-0.55m'\h'0.00n'\z.\h'0.40n'\z.\v'0.55m'\h'-0.40n'u
.if t .ds A \v'-0.77m'\h'0.25n'\z.\h'0.45n'\z.\v'0.77m'\h'-0.70n'A
.if t .ds O \v'-0.77m'\h'0.25n'\z.\h'0.45n'\z.\v'0.77m'\h'-0.70n'O
.if t .ds U \v'-0.77m'\h'0.30n'\z.\h'0.45n'\z.\v'0.77m'\h'-.75n'U
.if t .ds s \(*b
.if t .ds S SS
.if n .ds a ae
.if n .ds o oe
.if n .ds u ue
.if n .ds s sz
.TH makefiles 4L "14. February 1997" "J\*org Schilling" "Schily\'s FILE FORMATS"
.\".TH makerules 4L "14. February 1997" "J\*org Schilling" "GMD FOKUS FILE FORMATS"
.SH NAME
makerules \- system programmers guide for compiling projects on different platforms
.SH SYNOPSIS
.B "SRCROOT=	.\|.
.br
.B "RULESDIR=	RULES
.br
.B "include		$(SRCROOT)/$(RULESDIR)/rules.top
.br
.I "local defines are here
.br
.B "include		$(SRCROOT)/$(RULESDIR)/rules.*
.PP
See chapter CURRENTLY SUPPORTED TARGET TYPES for possible values of
.BR "rules.*" .

.SH DESCRIPTION
Makerules is a set of rules that allows compiling of structured
projects with small and uniformly structured makefiles.
All rules are located in a central directory.
Compiling the projects on different platforms can be done without
the need to modify any of the makefiles that are located
in the projects directories.
.PP
Three make programs are currently supported:
.IR "Sunpro make" , 
.I "GNU make"
and
.IR smake .
If you want to add support for other make programs, read the 
sections about the minimum requirements for a make program
and about the structure of the 
.B "make rule 
system.
.PP
This manual will help programmers who need to make modifications
on the make rule system itself. If you want to know something 
on how to use the 
.B "makefile system
have a look at 
.BR makefiles (4).
.PP
The main design goal was to have no definition on more than place
in the make rules. This implies that system programmers who
want to add or modify rules must follow this goal in order not to
destroy functionality in other places.
.PP
The visible result for the user is a set of small and easy to read
makefiles, each located in the project's leaf directory and therefore 
called
.IR leaf -makefile.
.PP
Each of these 
.IR leaf -makefiles,
in fact contains no rule at all. It simply defines some macros
for the 
.IR make -program
and includes two files from a central make rule depository.
These included files define the rules that are needed to compile
the project.
.PP
Each 
.IR leaf -makefile
is formed in a really simple way:
.TP
\(bu
It first defines two macros that define the relative location
of the project's root directory and the name of the directory
that contains the complete set of of rules and then includes
the rule file 
.I rules.top
from the directory that forms the central rule depository.
You only have to edit the macro
.I SRCROOT
to reflect the relative location of the project's root directory.
.TP
\(bu
The next part of a 
.IR leaf -makefile
defines macros that describe the target and the source.
You can only have one target per 
.IR leaf -makefile.
Of course, there may be many source files, that are needed to create
that 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 files
and 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.
.TP
\(bu
Each
.IR leaf -makefile
finally includes a file from the rules directory that contains
rules for the appropriate type of target that is to be made
from this 
.IR leaf -makefile.
.PP
The makefile in each directory has to be called
.IR Makefile .
If you want to have more than one makefile in a specific directory,
you have to choose different names for the other makefiles.

.SH "Currently Supported Target Types
.PP
There are rules for the following type of targets:
.TP 20
commands
The make rules for user level commands like
.IR cat ", " ls 
etc. are located in the file 
.I rules.cmd
.TP
drivers
The make rules for device drivers
are located in the file 
.I rules.drv
.TP
libraries
The make rules for non shared libraries
are located in the file 
.I rules.lib
.TP
shared libraries
The make rules for shared libraries
are located in the file 
.I rules.shl
.TP
localized files
The make rules for localized files
are located in the file 
.I rules.loc
.TP
nonlocalized files
The make rules for non localized files
are located in the file 
.I rules.aux
.TP
shell scripts
The make rules for shell scripts (a variant of localized files)
are located in the file 
.I rules.scr
.TP
manual pages
The make rules for manual pages (a variant of localized files)
are located in the file 
.I rules.man
.TP
diverted makefiles
The make rules for projects that need to have more than
one makefile in a specific directory
are located in the file 
.I rules.mks
It contains a rule that diverts to the listed sub makefiles.
Each sub makefile may be of any type.
.TP
directories
The make rules for sub directories
are located in the file 
.I rules.dir

.SH "Minimum Requirements For A Make Program
The make rules currently have support for
.IR "Sunpro make" , 
.I "GNU make"
and
.IR smake .
If you like to add support for other make programs, 
they need to have some minimal features that go
beyond the capabilities of the standard 
.SM "UNIX
.B make
program.
.I BSDmake
could be supported if it supports pattern matching rules correctly.
.TP 20
include
The make program must be able to recursively include other files
from within a 
.I 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 that
if 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.
.TP
appending to a macro
A macro reference of the form:
.sp
.B "macro += addval
.sp
should append
.B addval
to the string that is currently in
.BR macro .
.TP
suffix macro replacement
A macro reference of the form:
.sp
.B "out= $(macro\|:\|string1\|=\|string2)
.sp
should replace a suffix
.I string1
to
.I string2
in all words that are in
.BR macro ,
where string1 is either a suffix, or a word to be replaced
in the macro definition, and string2 is the replacement 
suffix or word.
.I String1
and
.I string2
must be replaced correctly even if they are macros themselves.
Words in a macro value are separated by SPACE, 
TAB, and escaped NEWLINE characters.
.TP
pattern macro replacement
A macro reference of the form:
.sp
.B "out= $(macro\|:\|op%os\|=\|np%ns)
.sp
should replace a central pattern in 
.BR macro ,
where 
.B op 
is the existing (old) prefix and 
.B os
is the existing
(old) suffix,
.B np 
and 
.B ns 
are the new prefix and new suffix,
respectively, and the pattern matched by % (a string of zero
or more characters), is carried forward from the value being
replaced.
For example:
.sp
.B "PROGRAM=fabricate
.br
.B "DEBUG= $(PROGRAM:%=tmp/%\-g)
.sp
sets the value of DEBUG to tmp/fabricate\-g.
.IR Op ", " os ", " 
.IR np " and " ns
must be replaced correctly even if they are macros themselves.

.SH "Understanding Basic Algorithms
One of the basic algorithms used in the make rule system
is needed to set an undefined macro to a guaranteed default value.
Because not all make programs have support for
.I "if then else
structures, a different method has to be used.
.PP
The method used in
.B "make rules
is implemented by using
.B "suffix macro replacement
and
.BR "pattern macro replacement" .
.PP
.ne 5
First, a macro that contains a unique suffix is defined:
.sp
.B " # Define magic unique cookie
.br
.B " _UNIQ= 		.XxZzy\-
.sp
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 to
implement the phrase:
.B If 
.I $(MAKE_NAME)
contains a value, 
.B then
.I $(XMAKEPROG)
will be set to
.I $(MAKE_NAME)
.B else
.I $(XMAKEPROG)
will be set to
.IR $(MAKEPROG) .
.sp
.B " _MAKEPROG=	$(_UNIQ)$(MAKE_NAME)
.br
.B " __MAKEPROG=	$(_MAKEPROG:$(_UNIQ)=$(MAKEPROG))
.br
.B " XMAKEPROG=	$(__MAKEPROG:$(_UNIQ)%=%)
.sp
The first line in this example, sets the macro
.I _MAKEPROG
to the concatenation of the value of
.I MAKE_NAME
and
.BR .XxZzy\- .
If the macro
.I MAKE_NAME
is empty at this time, 
.I _MAKEPROG
will contain only 
.BR .XxZzy\- .
.PP
In the second line, 
.I __MAKEPROG
is set to the value of
.IR _MAKEPROG .
If 
.I _MAKEPROG
contains only 
.B .XxZzy\-
this implies, that
.B .XxZzy\-
is the suffix. This suffix is then replaced
by the value of
.IR MAKEPROG ,
in this case
.I __MAKEPROG
will contain the unmodified value of
.IR MAKEPROG .
If 
.I _MAKEPROG
contains a concatenation of
.B .XxZzy\-
and something else, 
.B .XxZzy\-
will not be a suffix, but a prefix of 
.I _MAKEPROG
and for this reason
.I __MAKEPROG
will contain the unmodified value of
.IR _MAKEPROG ,
which is a concatenation of
.B .XxZzy\-
and the value of
.IR MAKE_NAME .
.PP
In the third line, 
.I XMAKEPROG
is set to the value of
.IR __MAKEPROG .
If 
.I __MAKEPROG
has the prefix
.B .XxZzy\- 
at this time, 
.B .XxZzy\-
is stripped of.

.SH "The Structure in Make Macro names
.PP
The names used for 
.B "make macros
are structured in a way that allows to use 
.BR grep (1)
to look for the names in the 
.B make rules.
To allow this, no name must be a substring of another name.
.PP
If a command needs options that have to be specified
in macros, there is a 
.B "make macro
that is named
.I XXXFLAGS.
This is compliant to usual make file rules.
The are internal 
.B "make macros
called
.I XXXOPTS
and
.I XXXOPTX
that will be combined for 
.IR XXXFLAGS :
.sp
.B "LDFLAGS= $(LDOPTS) $(LDOPTX)
.sp
Where 
.I XXXOPTS
is the name of the macro that is used internally
and 
.I XXXOPTX
is the name of the macro that may be used from the
command line of the make program.
.I XXXOPTX
therefore is used to append to the content of 
.I XXXFLAGS
If the value of
.I XXXFLAGS
need to be overwritten, 
.I XXXOPTS
may be used within the command line flags of the make program.

.SH "The Structure Of The Make Rule System
.SH "The Structure Of The Basic Rules in rules.top
The file 
.B RULES/rules.top
first includes a rule file that depends on the 
make program that is used.
The name of this file is
.BI RULES/mk\- makeprog .id
where
.I makeprog
has to be replaced by the real name of
the makeprogram e.g.
.BR make ", " gmake ", " smake .
The purpose of this file is to set up a list of macros
that identify the system where the project is currently built.
These macros have values that contain only lower case letters and define:
.TP 28
the processor architecture
If two systems run the same operating system, this
is a unique value if a simple user level program will
not need to be recompiled in order to run on the other system.
Possible values are 
.BR sparc ", " mc68020 ", " pentium .
This is the output of
.BR "uname \-p" .
The value is stored in
.BR P_ARCH .
.TP
the kernel architecture
If two systems may use the same value for 
.B P_ARCH
but a heavily system dependent user level program
need to be recompiled in order to run on the other
system, These two systems have different 
kernel architectures.
This is the output of
.BR "uname \-m" .
Possible values are 
.BR sun3 ", " sun4c ", " sun4m .
The value is stored in
.BR K_ARCH .
.TP
the machine architecture
An outdated macro that is useful only on sun systems.
Do not use this, use 
.B P_ARCH 
instead.
This is the output of
.BR arch .
Possible values are 
.BR sun3 ", " sun4 .
The value is stored in
.BR M_ARCH .
.TP
the hostname
The name of the machine where the compilation takes place.
This is the output of
.BR "uname \-n" .
The value is stored in
.BR HOSTNAME .
.TP
the name of the operating system
This is the output of
.BR "uname \-s" .
Possible values are 
.BR sunos ", " dgux ", " hp\-ux ", " irix .
The value is stored in
.BR OSNAME .
.TP
the release of the operating system
This is the output of
.BR "uname \-r" .
Possible values are 
.BR 5.5 ", " 4.1.4 .
The value is stored in
.BR OSREL .
.PP
The next file to be included from
.B RULES/rules.top
is
.BI RULES/os\- "operating system" .id .
It defines the macros
.B O_ARCH
and
.B \-O_ARCH 
and may modify one of the macros that are defined
in
.BI RULES/mk\- makeprog .id .
The macros
.B O_ARCH
and
.B \-O_ARCH 
are used to distinguish between different operating systems.
The names of the compiler configuration files have