bsd.README revision 23559
1# @(#)bsd.README 8.2 (Berkeley) 4/2/94 2# $Id$ 3 4XXX This document is seriously out of date, it is currenly being revised. 5 6This is the README file for the new make "include" files for the BSD 7source tree. The files are installed in /usr/share/mk, and are, by 8convention, named with the suffix ".mk". 9 10bsd.dep.mk - handle Makefile dependencies 11bsd.doc.mk - building troff system documents 12bsd.info.mk - building GNU Info hypertext system 13bsd.kern.mk - define warning flags for compiling the kernel 14bsd.kmod.mk - building loadable kernel modules 15bsd.lib.mk - support for building libraries 16bsd.libnames.mk - define library names 17bsd.man.mk - installing manual pages and their links 18bsd.obj.mk - creating 'obj' directories and cleaning up 19bsd.own.mk - define common variables 20bsd.port.mk - building ports 21bsd.port.subdir.mk - targets for building subdirectories for ports 22bsd.prog.mk - building programs from source files 23bsd.sgml.mk - building SGML documents 24bsd.subdir.mk - targets for building subdirectories 25 26 27Note, this file is not intended to replace reading through the .mk 28files for anything tricky. 29 30=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 31 32RANDOM THINGS WORTH KNOWING: 33 34The files are simply C-style #include files, and pretty much behave like 35you'd expect. The syntax is slightly different in that a single '.' is 36used instead of the hash mark, i.e. ".include <bsd.prog.mk>". 37 38One difference that will save you lots of debugging time is that inclusion 39of the file is normally done at the *end* of the Makefile. The reason for 40this is because .mk files often modify variables and behavior based on the 41values of variables set in the Makefile. To make this work, remember that 42the FIRST target found is the target that is used, i.e. if the Makefile has: 43 44 a: 45 echo a 46 a: 47 echo a number two 48 49the command "make a" will echo "a". To make things confusing, the SECOND 50variable assignment is the overriding one, i.e. if the Makefile has: 51 52 a= foo 53 a= bar 54 55 b: 56 echo ${a} 57 58the command "make b" will echo "bar". This is for compatibility with the 59way the V7 make behaved. 60 61It's fairly difficult to make the BSD .mk files work when you're building 62multiple programs in a single directory. It's a lot easier split up the 63programs than to deal with the problem. Most of the agony comes from making 64the "obj" directory stuff work right, not because we switch to a new version 65of make. So, don't get mad at us, figure out a better way to handle multiple 66architectures so we can quit using the symbolic link stuff. (Imake doesn't 67count.) 68 69The file .depend in the source directory is expected to contain dependencies 70for the source files. This file is read automatically by make after reading 71the Makefile. 72 73The variable DESTDIR works as before. It's not set anywhere but will change 74the tree where the file gets installed. 75 76The profiled libraries are no longer built in a different directory than 77the regular libraries. A new suffix, ".po", is used to denote a profiled 78object. 79 80=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 81 82The include file <sys.mk> has the default rules for all makes, in the BSD 83environment or otherwise. You probably don't want to touch this file. 84 85=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 86 87The include file <bsd.man.mk> handles installing manual pages and their 88links. 89 90It has a single target: 91 92 maninstall: 93 Install the manual pages and their links. 94 95It sets/uses the following variables: 96 97MANDIR Base path for manual installation. 98 99MANGRP Manual group. 100 101MANOWN Manual owner. 102 103MANMODE Manual mode. 104 105MANSUBDIR Subdirectory under the manual page section, i.e. "/vax" 106 or "/tahoe" for machine specific manual pages. 107 108MAN1 ... MAN8 The manual pages to be installed (use a .0 suffix). 109 110MLINKS List of manual page links (using a .1 - .8 suffix). The 111 linked-to file must come first, the linked file second, 112 and there may be multiple pairs. The files are soft-linked. 113 114The include file <bsd.man.mk> includes the include file <bsd.inc.mk>. 115 116=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 117 118The include file <bsd.own.mk> contains the owners, groups, etc. for both 119manual pages and binaries. 120 121It has no targets. 122 123It sets/uses the following variables: 124 125BINGRP Binary group. 126 127BINOWN Binary owner. 128 129BINMODE Binary mode. 130 131STRIP The flag passed to the install program to cause the binary 132 to be stripped. This is to be used when building your 133 own install script so that the entire system can be made 134 stripped/not-stripped using a single nob. 135 136MANDIR Base path for manual installation. 137 138MANGRP Manual group. 139 140MANOWN Manual owner. 141 142MANMODE Manual mode. 143 144This file is generally useful when building your own Makefiles so that 145they use the same default owners etc. as the rest of the tree. 146 147=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 148 149The include file <bsd.prog.mk> handles building programs from one or 150more source files, along with their manual pages. It has a limited number 151of suffixes, consistent with the current needs of the BSD tree. 152 153It has seven targets: 154 155 all: 156 build the program and its manual page 157 clean: 158 remove the program, any object files and the files a.out, 159 Errs, errs, mklog, and ${PROG}.core. 160 cleandir: 161 remove all of the files removed by the target clean, as 162 well as .depend, tags, and any manual pages. 163 depend: 164 make the dependencies for the source files, and store 165 them in the file .depend. 166 install: 167 install the program and its manual pages; if the Makefile 168 does not itself define the target install, the targets 169 beforeinstall and afterinstall may also be used to cause 170 actions immediately before and after the install target 171 is executed. 172 lint: 173 run lint on the source files 174 tags: 175 create a tags file for the source files. 176 177It sets/uses the following variables: 178 179BINGRP Binary group. 180 181BINOWN Binary owner. 182 183BINMODE Binary mode. 184 185CLEANFILES Additional files to remove and 186CLEANDIRS additional directories to remove during clean and cleandir 187 targets. "rm -f" and "rm -rf" used respectively. 188 189COPTS Additional flags to the compiler when creating C objects. 190 191HIDEGAME If HIDEGAME is defined, the binary is installed in 192 /usr/games/hide, and a symbolic link is created to 193 /usr/games/dm. 194 195LDADD Additional loader objects. Usually used for libraries. 196 For example, to load with the compatibility and utility 197 libraries, use: 198 199 LDFILES=-lutil -lcompat 200 201LDFLAGS Additional loader flags. 202 203LINKS The list of binary links; should be full pathnames, the 204 linked-to file coming first, followed by the linked 205 file. The files are hard-linked. For example, to link 206 /bin/test and /bin/[, use: 207 208 LINKS= ${DESTDIR}/bin/test ${DESTDIR}/bin/[ 209 210MAN1...MAN8 Manual pages (should end in .0). If no MAN variable is 211 defined, "MAN1=${PROG}.0" is assumed. 212 213PROG The name of the program to build. If not supplied, nothing 214 is built. 215 216SRCS List of source files to build the program. If PROG is not 217 defined, it's assumed to be ${PROG}.c. 218 219DPADD Additional dependencies for the program. Usually used for 220 libraries. For example, to depend on the compatibility and 221 utility libraries use: 222 223 SRCLIB=${LIBCOMPAT} ${LIBUTIL} 224 225 There is a predefined identifier for each (non-profiled, 226 non-shared) library and object. Library file names are 227 transformed to identifiers by removing the extension and 228 converting to upper case. 229 230 There are no special identifiers for profiled or shared 231 libraries or objects. The identifiers for the standard 232 libraries are used in DPADD. This works correctly iff all 233 the libraries are built at the same time. Unfortunately, 234 it causes unnecessary relinks to shared libraries when 235 only the static libraries have changed. Dependencies on 236 shared libraries should be only on the library version 237 numbers. 238 239STRIP The flag passed to the install program to cause the binary 240 to be stripped. 241 242SUBDIR A list of subdirectories that should be built as well. 243 Each of the targets will execute the same target in the 244 subdirectories. 245 246The include file <bsd.prog.mk> includes the include files <bsd.inc.mk> 247and <bsd.man.mk>. 248 249Some simple examples: 250 251To build foo from foo.c with a manual page foo.1, use: 252 253 PROG= foo 254 255 .include <bsd.prog.mk> 256 257To build foo from foo.c with a manual page foo.2, add the line: 258 259 MAN2= foo.0 260 261If foo does not have a manual page at all, add the line: 262 263 NOMAN= noman 264 265If foo has multiple source files, add the line: 266 267 SRCS= a.c b.c c.c d.c 268 269=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 270 271The include file <bsd.subdir.mk> contains the default targets for building 272subdirectories. It has the same seven targets as <bsd.prog.mk>: all, clean, 273cleandir, depend, install, lint, and tags. For all of the directories 274listed in the variable SUBDIRS, the specified directory will be visited 275and the target made. There is also a default target which allows the 276command "make subdir" where subdir is any directory listed in the variable 277SUBDIRS. 278 279=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 280 281The include file <bsd.lib.mk> has support for building libraries. It has 282the same seven targets as <bsd.prog.mk>: all, clean, cleandir, depend, 283install, lint, and tags. It has a limited number of suffixes, consistent 284with the current needs of the BSD tree. 285 286It sets/uses the following variables: 287 288LIBDIR Target directory for libraries. 289 290LINTLIBDIR Target directory for lint libraries. 291 292LIBGRP Library group. 293 294LIBOWN Library owner. 295 296LIBMODE Library mode. 297 298LDADD Additional loader objects. 299 300MAN1 ... MAN8 The manual pages to be installed (use a .0 suffix). 301 302SRCS List of source files to build the library. Suffix types 303 .s, .c, and .f are supported. Note, .s files are preferred 304 to .c files of the same name. (This is not the default for 305 versions of make.) 306 307The include file <bsd.lib.mk> includes the include files <bsd.inc.mk> 308and <bsd.man.mk>. 309 310It has rules for building profiled objects; profiled libraries are 311built by default. 312 313Libraries are ranlib'd before installation. 314