1 . \" @(#)makerules.4 1.2 97/02/14 Copyr 1996 J. Schilling
2 . \" System Manual page for makefile system
4 .if t .ds a \v'-0.55m'\h'0.00n'\z.\h'0.40n'\z.\v'0.55m'\h'-0.40n'a
5 .if t .ds o \v'-0.55m'\h'0.00n'\z.\h'0.45n'\z.\v'0.55m'\h'-0.45n'o
6 .if t .ds u \v'-0.55m'\h'0.00n'\z.\h'0.40n'\z.\v'0.55m'\h'-0.40n'u
7 .if t .ds A \v'-0.77m'\h'0.25n'\z.\h'0.45n'\z.\v'0.77m'\h'-0.70n'A
8 .if t .ds O \v'-0.77m'\h'0.25n'\z.\h'0.45n'\z.\v'0.77m'\h'-0.70n'O
9 .if t .ds U \v'-0.77m'\h'0.30n'\z.\h'0.45n'\z.\v'0.77m'\h'-.75n'U
16 .TH makefiles 4L "14. February 1997" "J\*org Schilling" "Schily\'s FILE FORMATS"
17 .\".TH makerules 4L "14. February 1997" "J\*org Schilling" "GMD FOKUS FILE FORMATS"
19 makerules \- system programmers guide for compiling projects on different platforms
25 .B "include $(SRCROOT)/$(RULESDIR)/rules.top
27 .I "local defines are here
29 .B "include $(SRCROOT)/$(RULESDIR)/rules.*
31 See chapter CURRENTLY SUPPORTED TARGET TYPES for possible values of
35 Makerules is a set of rules that allows compiling of structured
36 projects with small and uniformly structured makefiles.
37 All rules are located in a central directory.
38 Compiling the projects on different platforms can be done without
39 the need to modify any of the makefiles that are located
40 in the projects directories.
42 Three make programs are currently supported:
47 If you want to add support for other make programs, read the
48 sections about the minimum requirements for a make program
49 and about the structure of the
53 This manual will help programmers who need to make modifications
54 on the make rule system itself. If you want to know something
60 The main design goal was to have no definition on more than place
61 in the make rules. This implies that system programmers who
62 want to add or modify rules must follow this goal in order not to
63 destroy functionality in other places.
65 The visible result for the user is a set of small and easy to read
66 makefiles, each located in the project's leaf directory and therefore
72 in fact contains no rule at all. It simply defines some macros
75 and includes two files from a central make rule depository.
76 These included files define the rules that are needed to compile
81 is formed in a really simple way:
84 It first defines two macros that define the relative location
85 of the project's root directory and the name of the directory
86 that contains the complete set of of rules and then includes
89 from the directory that forms the central rule depository.
90 You only have to edit the macro
92 to reflect the relative location of the project's root directory.
97 defines macros that describe the target and the source.
98 You can only have one target per
100 Of course, there may be many source files, that are needed to create
102 If you want to make more than one target in a specific directory,
103 you have to put more than one makefile into that directory.
104 This is the part of a makefile that describes a unique target.
105 Edit this part to contain all source files, all local include files
106 and all non global compile time flags that are needed for your target.
107 For a typical target this is as simple as filling in a form.
112 finally includes a file from the rules directory that contains
113 rules for the appropriate type of target that is to be made
117 The makefile in each directory has to be called
119 If you want to have more than one makefile in a specific directory,
120 you have to choose different names for the other makefiles.
122 .SH "Currently Supported Target Types
124 There are rules for the following type of targets:
127 The make rules for user level commands like
129 etc. are located in the file
133 The make rules for device drivers
134 are located in the file
138 The make rules for non shared libraries
139 are located in the file
143 The make rules for shared libraries
144 are located in the file
148 The make rules for localized files
149 are located in the file
153 The make rules for non localized files
154 are located in the file
158 The make rules for shell scripts (a variant of localized files)
159 are located in the file
163 The make rules for manual pages (a variant of localized files)
164 are located in the file
168 The make rules for projects that need to have more than
169 one makefile in a specific directory
170 are located in the file
172 It contains a rule that diverts to the listed sub makefiles.
173 Each sub makefile may be of any type.
176 The make rules for sub directories
177 are located in the file
180 .SH "Minimum Requirements For A Make Program
181 The make rules currently have support for
186 If you like to add support for other make programs,
187 they need to have some minimal features that go
188 beyond the capabilities of the standard
193 could be supported if it supports pattern matching rules correctly.
196 The make program must be able to recursively include other files
199 The name if the file to include must be allowed to be a macro.
200 The make program must be able to do this in a way that
201 if the file that should be included may be a result of make rule.
202 e.g if the file to be included does not exist or is outdated,
203 it should be built before an attempt is made to actually include it.
206 A macro reference of the form:
212 to the string that is currently in
215 suffix macro replacement
216 A macro reference of the form:
218 .B "out= $(macro\|:\|string1\|=\|string2)
220 should replace a suffix
224 in all words that are in
226 where string1 is either a suffix, or a word to be replaced
227 in the macro definition, and string2 is the replacement
232 must be replaced correctly even if they are macros themselves.
233 Words in a macro value are separated by SPACE,
234 TAB, and escaped NEWLINE characters.
236 pattern macro replacement
237 A macro reference of the form:
239 .B "out= $(macro\|:\|op%os\|=\|np%ns)
241 should replace a central pattern in
245 is the existing (old) prefix and
252 are the new prefix and new suffix,
253 respectively, and the pattern matched by % (a string of zero
254 or more characters), is carried forward from the value being
258 .B "PROGRAM=fabricate
260 .B "DEBUG= $(PROGRAM:%=tmp/%\-g)
262 sets the value of DEBUG to tmp/fabricate\-g.
265 must be replaced correctly even if they are macros themselves.
267 .SH "Understanding Basic Algorithms
268 One of the basic algorithms used in the make rule system
269 is needed to set an undefined macro to a guaranteed default value.
270 Because not all make programs have support for
272 structures, a different method has to be used.
276 is implemented by using
277 .B "suffix macro replacement
279 .BR "pattern macro replacement" .
282 First, a macro that contains a unique suffix is defined:
284 .B " # Define magic unique cookie
288 This macro is used for all places where it is necessary to have
289 a macro with a guaranteed default value.
290 The following example shows the basic algorithm that is used to
291 implement the phrase:
304 .B " _MAKEPROG= $(_UNIQ)$(MAKE_NAME)
306 .B " __MAKEPROG= $(_MAKEPROG:$(_UNIQ)=$(MAKEPROG))
308 .B " XMAKEPROG= $(__MAKEPROG:$(_UNIQ)%=%)
310 The first line in this example, sets the macro
312 to the concatenation of the value of
318 is empty at this time,
325 is set to the value of
333 is the suffix. This suffix is then replaced
338 will contain the unmodified value of
342 contains a concatenation of
346 will not be a suffix, but a prefix of
350 will contain the unmodified value of
352 which is a concatenation of
359 is set to the value of
369 .SH "The Structure in Make Macro names
373 are structured in a way that allows to use
375 to look for the names in the
377 To allow this, no name must be a substring of another name.
379 If a command needs options that have to be specified
380 in macros, there is a
384 This is compliant to usual make file rules.
391 that will be combined for
394 .B "LDFLAGS= $(LDOPTS) $(LDOPTX)
398 is the name of the macro that is used internally
401 is the name of the macro that may be used from the
402 command line of the make program.
404 therefore is used to append to the content of
408 need to be overwritten,
410 may be used within the command line flags of the make program.
412 .SH "The Structure Of The Make Rule System
413 .SH "The Structure Of The Basic Rules in rules.top
416 first includes a rule file that depends on the
417 make program that is used.
418 The name of this file is
419 .BI RULES/mk\- makeprog .id
422 has to be replaced by the real name of
424 .BR make ", " gmake ", " smake .
425 The purpose of this file is to set up a list of macros
426 that identify the system where the project is currently built.
427 These macros have values that contain only lower case letters and define:
429 the processor architecture
430 If two systems run the same operating system, this
431 is a unique value if a simple user level program will
432 not need to be recompiled in order to run on the other system.
434 .BR sparc ", " mc68020 ", " pentium .
435 This is the output of
437 The value is stored in
440 the kernel architecture
441 If two systems may use the same value for
443 but a heavily system dependent user level program
444 need to be recompiled in order to run on the other
445 system, These two systems have different
446 kernel architectures.
447 This is the output of
450 .BR sun3 ", " sun4c ", " sun4m .
451 The value is stored in
454 the machine architecture
455 An outdated macro that is useful only on sun systems.
459 This is the output of
463 The value is stored in
467 The name of the machine where the compilation takes place.
468 This is the output of
470 The value is stored in
473 the name of the operating system
474 This is the output of
477 .BR sunos ", " dgux ", " hp\-ux ", " irix .
478 The value is stored in
481 the release of the operating system
482 This is the output of
486 The value is stored in
489 The next file to be included from
492 .BI RULES/os\- "operating system" .id .
493 It defines the macros
497 and may modify one of the macros that are defined
499 .BI RULES/mk\- makeprog .id .
504 are used to distinguish between different operating systems.
505 The names of the compiler configuration files have
508 On some operating systems e.g.
512 it is necessary to distinguish between
521 The next file to be included from
525 It defines the macros
537 If the definitions have to be different on
538 different systems, this file may contain a line int the form:
540 .BI include " $(SRCROOT)" /Defaults. $(O_ARCH)
542 The actual definitions then have to be moved into
545 Next, after setting up some internal defaults,
547 includes the compiler configuration file with
550 .I $(SRCROOT)/$(RULESDIR)/$(XARCH).rul
552 This file contains all necessary
554 stuff that is needed to configure the C-compiler
555 on the appropriate system.
556 It is a bad idea to create a new one from scratch.
557 Have a look at the other compiler configuration
558 files and modify a similar file for your needs.
559 Note that there are basically two criterias to
560 that are important in a compiler configuration file.
561 One is whether the system uses the
563 header format or not.
564 The other is whether the system uses
568 .SH "The Structure Of The Application Specific Rules
570 The application specific rule files are designed in
571 such a way that they include all necessary stuff that
572 is needed for that specific task. The application specific
576 Rules for installing non localized auxiliary files.
579 Rules for commands like
583 Rules for sub directories.
586 Rules for lodable drivers.
589 Rules for static libraries.
592 Rules for installing localized auxiliary files.
595 Rules for installing localized manual pages.
598 Rules for sub makefiles.
601 Rules for lodable stream modules.
604 Rules for installing localized shell scripts.
607 Rules for shared libraries.
609 .SH "Understanding The Structure Of The Make Rule System
611 To understand the structure of the
613 system while doing changes, try to use the
619 This flag will print out the include dependency list
620 (i.e. a list that tell you which make rules is included
621 from which other rule).
623 Note that some of the rules are make program dependent.
624 If you want to make changes to these rules you may need to
625 place the definitions into separate rule files
626 each for the appropriate make program.
639 \&.\|.\|./TEMPLATES/*
648 Diagnostic messages depend on the make program.
649 Have a look at the appropriate man page.
655 .IR "Sunpro make" ", " "Gnu make"
658 Although Gnu make runs on many platforms, it has no useful debug
662 .IR "Sunpro make" " or " "smake"
663 if you have problems with a makefile.
664 .IR "Sunpro make" " and " "smake" ,
665 both have a \-D flag, that allows you to watch the makefiles
666 after the first expansion. Use this option, if you are in doubt
667 if your makefile gets expanded the right way and if the right
669 There is also a \-d option that gives debugging output while
670 make is running. If you want more output, use \-dd, \-ddd and so on.
673 has an option \-xM that shows you the include dependency for
678 .SH "Source Tree Hierarchy
680 The following outline gives a quick tour through a typical
688 root directory of the source tree
696 default definitions for that source tree. System dependent
701 a file containing a list of directories that are needed
703 If the system needs different target lists depending
704 on the target system architecture , use target specific files in
712 the location of makefiles (included rules)
717 the mandatory include rules (needed to setup basic rules)
720 rules needed to install a non localized auxiliary file
723 rules needed to make an ordinary command (like /bin/sh)
726 rules needed to make a device driver
729 rules needed to make a standard (nonshared) library
732 rules needed to install a localized auxiliary file
735 rules needed to install a localized manual page
738 rules needed to install a localized shell script
741 rules needed to make a shared library
744 rules needed to make more than one target in a specific directory
747 rules needed to make targets that are located in sub directories
748 to the current directory
755 default definitions for various target architectures are
756 located in this directory. Templates for some architectures can
762 target list definitions for various target architectures are
763 located in this directory.
766 templates that should be used inside the project
767 (rename to Makefile, if it is the only makefile on that directory,
770 if there is more than one target in that directory)
775 Defaults file for the source root directory
780 This sould be installed in the
785 Makefile for the source root directory
788 Makefile for a non localized auxiliary file
791 Makefile for an ordinary command (like /bin/sh)
794 Makefile for a standard (nonshared) library
797 Makefile for a localized auxiliary file
800 Makefile for a localized manual page
803 Makefile for a localized manual page in the german locale
806 Makefile for a localized shell script
809 Makefile for a shared library
812 Makefile for a device driver
815 Makefile for more than one target in a specific directory
818 Makefile for targets that are located in sub directories
819 to the current directory
826 source tree for normal commands
836 a file containing a list of directories like
838 (see below) that are needed
839 for that specific architecture.
842 directory where the sources for a specific command are located
851 makefile for the manual page of
858 troff source for the manual page of myprog
861 directory where system specific sub directories are located
865 .B sparc\-sunos5\-cc/
866 directory for binaries that belong to a specific system
881 directory where the sources for a libraries are located
891 a file containing a list of directories like
893 (see below) that are needed
894 for that specific architecture.
897 directory where all source files for libfoo are located
904 directory for kernel modules
914 a file containing a list of directories like
916 (see below) that are needed
917 for that specific architecture.
920 directory where drivers are located
930 a file containing a list of directories like
932 (see below) that are needed
933 for that specific architecture.
936 source for a specific driver
947 directory for global include files that are used in that project
951 directory for binary programs that are created/needed while compiling
955 .B sparc\-sunos5\-cc/
956 directory for binaries that belong to a specific system
963 directory for libraries that are created/needed while compiling
967 .B sparc\-sunos5\-cc/
968 directory for libraries that belong to a specific system
975 directory for include files that are created/needed while compiling
979 .B sparc\-sunos5\-cc/
980 directory for include files that belong to a specific system
999 Mail bugs and suggestions to:
1002 joerg@schily.isdn.cs.tu-berlin.de
OSDN Git Service
