makerules man page on Syllable

Man page or keyword search:  
man Server   2339 pages
apropos Keyword Search (all sections)
Output format
Syllable logo
[printable version]

makerules(4L)		    GMD FOKUS FILE FORMATS		 makerules(4L)

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:

       ·      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.

       ·      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.

       ·      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)
[top]
                             _         _         _ 
                            | |       | |       | |     
                            | |       | |       | |     
                         __ | | __ __ | | __ __ | | __  
                         \ \| |/ / \ \| |/ / \ \| |/ /  
                          \ \ / /   \ \ / /   \ \ / /   
                           \   /     \   /     \   /    
                            \_/       \_/       \_/ 
More information is available in HTML format for server Syllable

List of man pages available for Syllable

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net