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