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