makerules(4)
NAME
makerules - system programmers guide for compiling projects on differ-
ent platforms
SYNOPSIS
SRCROOT= ..
RULESDIR= RULES
include $(SRCROOT)/$(RULESDIR)/rules.top
local defines are here
include $(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 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 simultaneously without the need to modify any of
the makefiles that are located in the projects directories.
Makerules is a set of high level portability tools superior to autoconf
and easier to use.
Three make programs are currently supported: Sunpro make, GNU make and
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 make rule system.
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 makefile system have a look at makefiles(4).
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 functional-
ity in other places.
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 leaf-makefile.
Each of these leaf-makefiles, in fact contains no rule at all. It sim-
ply defines some macros for the 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.
Each leaf-makefile is formed in a really simple way:
o 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 rules.top from the directory that forms the central rule
depository. You only have to edit the macro SRCROOT to reflect
the relative location of the project's root directory.
o The next part of a leaf-makefile defines 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 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 make-
file 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 typi-
cal target this is as simple as filling in a form.
o Each leaf-makefile finally includes a file from the rules direc-
tory that contains rules for the appropriate type of target that
is to be made from this leaf-makefile.
The makefile in each directory has to be called Makefile. 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 like cat, ls
etc. are located in the file rules.cmd
drivers The make rules for device drivers are located in
the file rules.drv
libraries The make rules for non shared libraries are located
in the file rules.lib
shared libraries The make rules for shared libraries are located in
the file rules.shl
localized files The make rules for localized files are located in
the file rules.loc
nonlocalized files The make rules for non localized files are 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
than one makefile in a specific directory are
located in the file rules.mks It contains a rule
that diverts to the listed sub makefiles. Each sub
makefile may be of any type.
directories The make rules for sub directories are located in
the file rules.dir
Minimum Requirements For A Make Program
The make rules currently have support for Sunpro make, GNU make and
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 UNIX make program. BSDmake could be supported if it supports
pattern matching rules correctly.
include The make program must be able to recursively
include other files from 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 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.
appending to a macro
A macro reference of the form:
macro += addval
should append addval to the string that is cur-
rently in macro.
suffix macro replacement
A macro reference of the form:
out= $(macro:string1=string2)
should replace a suffix string1 to string2 in all
words that are in macro, where string1 is either a
suffix, or a word to be replaced in the macro defi-
nition, and string2 is the replacement suffix or
word. String1 and string2 must be replaced cor-
rectly 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 os is the existing
(old) suffix, np and 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 exam-
ple:
PROGRAM=fabricate
DEBUG= $(PROGRAM:%=tmp/%-g)
sets the value of DEBUG to tmp/fabricate-g. Op,
os, np and ns must be replaced correctly even if
they are macros themselves.
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 if then else structures, a different
method has to be used.
The method used in make rules is implemented by using suffix macro
replacement and pattern 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 to implement the phrase: If $(MAKE_NAME) con-
tains 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 _MAKEPROG to the con-
catenation of the value of MAKE_NAME and .XxZzy-. If the macro
MAKE_NAME is empty at this time, _MAKEPROG will contain only .XxZzy-.
In the second line, __MAKEPROG is set to the value of _MAKEPROG. If
_MAKEPROG contains only .XxZzy- this implies, that .XxZzy- is the suf-
fix. This suffix is then replaced by the value of MAKEPROG, in this
case __MAKEPROG will contain the unmodified value of MAKEPROG. If
_MAKEPROG contains a concatenation of .XxZzy- and something else,
.XxZzy- will not be a suffix, but a prefix of _MAKEPROG and for this
reason __MAKEPROG will contain the unmodified value of _MAKEPROG, which
is a concatenation of .XxZzy- and the value of MAKE_NAME.
In the third line, XMAKEPROG is set to the value of __MAKEPROG. If
__MAKEPROG has the prefix .XxZzy- at this time, .XxZzy- is stripped of.
The Structure in Make Macro names
The names used for make macros are 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 specified in macros, there
is a make macro that is named XXXFLAGS. This is compliant to usual
make file rules. The are internal make macros called XXXOPTS and
XXXOPTX that will be combined for XXXFLAGS:
LDFLAGS= $(LDOPTS) $(LDOPTX)
Where XXXOPTS is the name of the macro that is used internally and
XXXOPTX is the name of the macro that may be used from the command line
of the make program. XXXOPTX therefore is used to append to the con-
tent of XXXFLAGS If the value of XXXFLAGS need to be overwritten,
XXXOPTS may 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.top first includes a rule file that depends on the
make program that is used. The name of this file is RULES/mk-make-
prog.id where makeprog has to be replaced by the real name of the make-
program e.g. make, gmake, smake. The purpose of this file is to set
up a list of macros that identify the system where the project is cur-
rently built. These macros have values that contain only lower case
letters and define:
the processor architecture If two systems run the same operating sys-
tem, 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 sparc,
mc68020, pentium. This is the output of
uname -p. The value is stored in P_ARCH.
the kernel architecture If two systems may use the same value for
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 architec-
tures. This is the output of uname -m.
Possible values are sun3, sun4c, sun4m.
The value is stored in K_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 of arch. Pos-
sible values are sun3, sun4. The value is
stored in M_ARCH.
the hostname The name of the machine where the compila-
tion takes place. This is the output of
uname -n. The value is stored in HOSTNAME.
the name of the operating system
This is the output of uname -s. Possible
values are sunos, dgux, hp-ux, irix. The
value is stored in OSNAME.
the release of the operating system
This is the output of uname -r. Possible
values are 5.5, 4.1.4. The value is stored
in OSREL.
The next file to be included from RULES/rules.top is RULES/os-operating
system.id. It defines the macros O_ARCH and -O_ARCH and may modify one
of the macros that are defined in RULES/mk-makeprog.id. The macros
O_ARCH and -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. SunOS and DG-UX it is
necessary to distinguish between SunOS 4.x and SunOS 5.x or DG-UX 3.x
and DG-UX 4.x.
The next file to be included from RULES/rules.top is Defaults. It
defines the macros DEFCCOM , DEFINCDIRS , LDPATH , RUNPATH , INS_BASE
and INS_KBASE. If the definitions have to be different on different
systems, this file may contain a line int the form:
include $(SRCROOT)/Defaults.$(O_ARCH)
The actual definitions then have to be moved into these files.
Next, after setting up some internal defaults, RULES/rules.top includes
the compiler configuration file with the 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 com-
piler configuration files and modify a similar file for your needs.
Note that there are basically two criterias to that are important in a
compiler configuration file. One is whether the system uses the ELF
header format or not. The other is whether the system uses shared
libraries or not.
The Structure Of The Application Specific Rules
The application specific rule files are designed in such a way that
they include all necessary stuff that is needed for that specific task.
The application specific rule 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 rule system while doing
changes, try to use the -xM flag in the smake program. This flag will
print out the include dependency list (i.e. a list that tell you which
make rules is included from 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 to place the definitions into
separate rule files each for the appropriate make program. Have a look
into the RULES directory for 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 rules can be used with Sunpro make, Gnu make and smake.
Although Gnu make runs on many platforms, it has no useful debug out-
put.
Use Sunpro make or smake if you have problems with a makefile. Sunpro
make and smake, both have a -D flag, that allows you to watch the make-
files after the first expansion. Use this option, if you are in doubt
if your makefile gets expanded the right way and if the right rules 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.
Smake has an option -xM that shows you the include dependency for make
rules.
BUGS
Source Tree Hierarchy
The following outline gives a quick tour through a typical source hier-
archy:
.../ root directory of the source tree
Makefile
the top Makefile
Defaults
default definitions for that source tree. System
dependent definitions are in .../DEFAULTS/
Targetdirs
a file containing a list of directories that are needed
for that project. If the system needs different target
lists depending on 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
directories to the current directory
...
.../DEFAULTS/
default definitions for various target architectures are located
in this directory. Templates for some architectures can be found
in the .../TEMPLATES/ directory.
.../TARGETS/
target list definitions for various target architectures are
located 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
to target.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 directories
to 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 needed for that specific architecture.
myprog/
directory where the sources for a specific command are
located
Makefile
makefile for myprog
Makefile.man
makefile for the manual page of myprog
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 needed for that specific architecture.
libfoo/
directory where all source files for libfoo are located
...
.../kernel
directory for kernel modules
Makefile
the makefile for the kernel sub directory
Targetdirs.sun4m
a file containing a list of directories like drv (see
below) that are needed for that specific architecture.
drv/ directory where drivers are located
Makefile
the makefile for the drv sub directory
Targetdirs.sun4m
a file containing a list of directories like mydrv
(see below) that are needed for 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
compiling the project
sparc-sunos5-cc/
directory for binaries that belong to a specific system
...
.../libs
directory for libraries that are created/needed while compiling
the project
sparc-sunos5-cc/
directory for libraries that belong to a specific system
...
.../incs
directory for include files that are created/needed while
compiling the project
sparc-sunos5-cc/
directory for include files that belong to a specific
system
...
...
AUTHOR
Joerg Schilling
Seestr. 110
D-13353 Berlin
Germany
Mail bugs and suggestions to:
joerg@schily.isdn.cs.tu-berlin.de or js@cs.tu-berlin.de or
jes@fokus.gmd.de
Joerg Schilling 14. February 1997 makerules(4L)
Man(1) output converted with
man2html