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