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 4This is the README file for the "include" files for the DragonFly 5source tree. The files are installed in /usr/share/mk, and are, by 6convention, named with the suffix ".mk". These files store several 7build options and should be handled with caution. 8 9Note, this file is not intended to replace reading through the .mk 10files for anything tricky. 11 12There are two main types of make include files. One type is the generally 13usable make include files, such as bsd.prog.mk and bsd.lib.mk. The other is 14the internal make include files, such as bsd.files.mk and bsd.man.mk, which 15can not/should not be used directly but are used by the other make include 16files. In most cases it is only interesting to include bsd.prog.mk or 17bsd.lib.mk. 18 19bsd.cpu.custom.mk - handle CPU flags for custom compilers 20bsd.cpu.gcc47.mk - handle GCC 4.7 specific CPU flags & variables 21bsd.cpu.gcc50.mk - handle GCC 5.0 specific CPU flags & variables 22bsd.cpu.mk - handle CPU flags & variables 23bsd.dep.mk - handle Makefile dependencies 24bsd.doc.mk - building troff system documents 25bsd.files.mk - install of general purpose files 26bsd.hostlib.mk - 27bsd.hostprog.mk - 28bsd.incs.mk - install of include files 29bsd.init.mk - initialization for the make include files 30bsd.kmod.mk - building loadable kernel modules 31bsd.lib.mk - support for building libraries 32bsd.libnames.mk - define library names 33bsd.links.mk - install of links (sym/hard) 34bsd.man.mk - install of manual pages and their links 35bsd.nls.mk - build and install of NLS catalogs 36bsd.obj.mk - creating 'obj' directories and cleaning up 37bsd.own.mk - define common variables 38bsd.patch.mk - 39bsd.prog.mk - building programs from source files 40bsd.subdir.mk - targets for building subdirectories 41bsd.sys.mk - common settings used for building FreeBSD sources 42sys.mk - default rules for all makes 43 44 45See also make(1), mkdep(1) and `PMake - A Tutorial', 46located in /usr/src/share/doc/psd/12.make. 47 48=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 49 50Random things worth knowing about this document: 51 52If appropriate when documenting the variables the default value is 53indicated using square brackets e.g. [gzip]. 54In some cases the default value depend on other values (e.g. system 55architecture). In these cases the most common value is indicated. 56 57This document contains some simple examples of the usage of the BSD make 58include files. For more examples look at the makefiles in the DragonFly 59source tree. 60 61=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 62 63RANDOM THINGS WORTH KNOWING: 64 65The files are like C-style #include files, and pretty much behave like 66you'd expect. The syntax is slightly different in that a single '.' is 67used instead of the hash mark, i.e. ".include <bsd.prog.mk>". 68 69One difference that will save you lots of debugging time is that inclusion 70of the file is normally done at the *end* of the Makefile. The reason for 71this is because .mk files often modify variables and behavior based on the 72values of variables set in the Makefile. To make this work, remember that 73the FIRST target found is the target that is used, i.e. if the Makefile has: 74 75 a: 76 echo a 77 a: 78 echo a number two 79 80the command "make a" will echo "a". To make things confusing, the SECOND 81variable assignment is the overriding one, i.e. if the Makefile has: 82 83 a= foo 84 a= bar 85 86 b: 87 echo ${a} 88 89the command "make b" will echo "bar". This is for compatibility with the 90way the V7 make behaved. 91 92It's fairly difficult to make the BSD .mk files work when you're building 93multiple programs in a single directory. It's a lot easier split up the 94programs than to deal with the problem. Most of the agony comes from making 95the "obj" directory stuff work right, not because we switch to a new version 96of make. So, don't get mad at us, figure out a better way to handle multiple 97architectures so we can quit using the symbolic link stuff. (Imake doesn't 98count.) 99 100The file .depend in the source directory is expected to contain dependencies 101for the source files. This file is read automatically by make after reading 102the Makefile. 103 104The variable DESTDIR works as before. It's not set anywhere but will change 105the tree where the file gets installed. 106 107The profiled libraries are no longer built in a different directory than 108the regular libraries. A new suffix, ".po", is used to denote a profiled 109object. 110 111=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 112 113The include file <sys.mk> has the default rules for all makes, in the BSD 114environment or otherwise. You probably don't want to touch this file. 115 116=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 117 118The include file <bsd.man.mk> handles installing manual pages and their 119links. 120 121It has three targets: 122 123 all-man: 124 build manual pages. 125 maninstall: 126 install the manual pages and their links. 127 manlint: 128 verify the validity of manual pages. 129 130It sets/uses the following variables: 131 132MANDIR Base path for manual installation. 133 134MANGRP Manual group. 135 136MANOWN Manual owner. 137 138MANMODE Manual mode. 139 140MANSUBDIR Subdirectory under the manual page section, i.e. "/vax" 141 or "/tahoe" for machine specific manual pages. 142 143MAN The manual pages to be installed (use a .1 - .9 suffix). 144 145MANINSTALLFLAGS Additional flags to pass to install(1). 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