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.gcc80.mk - handle GCC 8.0 specific CPU flags & variables 22bsd.cpu.mk - handle CPU flags & variables 23bsd.crunchgen.mk - building crunched binaries using crunchgen(1) 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.init.mk - initialization for the make include files 31bsd.kmod.mk - building loadable kernel modules 32bsd.lib.mk - support for building libraries 33bsd.libnames.mk - define library names 34bsd.links.mk - install of links (sym/hard) 35bsd.man.mk - install of manual pages and their links 36bsd.nls.mk - build and install of NLS catalogs 37bsd.obj.mk - creating 'obj' directories and cleaning up 38bsd.own.mk - define common variables 39bsd.prog.mk - building programs from source files 40bsd.subdir.mk - targets for building subdirectories 41bsd.sys.mk - common settings used for building DragonFly 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 233LDADD Additional loader objects. Usually used for libraries. 234 For example, to load with the compatibility and utility 235 libraries, use: 236 237 LDFILES=-lutil -lcompat 238 239LDFLAGS Additional loader flags. 240 241LINKS The list of binary links; should be full pathnames, the 242 linked-to file coming first, followed by the linked 243 file. The files are hard-linked. For example, to link 244 /bin/test and /bin/[, use: 245 246 LINKS= ${DESTDIR}/bin/test ${DESTDIR}/bin/[ 247 248MAN Manual pages (should end in .1 - .9). If no MAN variable 249 is defined, "MAN=${PROG}.1" is assumed. 250 251PROG The name of the program to build. If not supplied, nothing 252 is built. 253 254PROG_CXX If defined, the name of the program to build. Also 255 causes <bsd.prog.mk> to link the program with the 256 standard C++ library. PROG_CXX overrides the value 257 of PROG if PROG is also set. 258 259PROGNAME The name that the above program will be installed as, if 260 different from ${PROG}. 261 262SRCS List of source files to build the program. If SRCS is not 263 defined, it's assumed to be ${PROG}.c or, if PROG_CXX is 264 defined, ${PROG_CXX}.cc. 265 266DPADD Additional dependencies for the program. Usually used for 267 libraries. For example, to depend on the compatibility and 268 utility libraries use: 269 270 DPADD= ${LIBCOMPAT} ${LIBUTIL} 271 272 There is a predefined identifier for each (non-profiled, 273 non-shared) library and object. Library file names are 274 transformed to identifiers by removing the extension and 275 converting to upper case. 276 277 There are no special identifiers for profiled or shared 278 libraries or objects. The identifiers for the standard 279 libraries are used in DPADD. This works correctly iff all 280 the libraries are built at the same time. Unfortunately, 281 it causes unnecessary relinks to shared libraries when 282 only the static libraries have changed. Dependencies on 283 shared libraries should be only on the library version 284 numbers. 285 286STRIP The flag passed to the install program to cause the binary 287 to be stripped. This is to be used when building your 288 own install script so that the entire system can be made 289 stripped/not-stripped using a single knob. 290 291SUBDIR A list of subdirectories that should be built as well. 292 Each of the targets will execute the same target in the 293 subdirectories. 294 295SCRIPTS A list of interpreter scripts [file.{sh,csh,pl,awk,...}]. 296 The installation is controlled by the SCRIPTSNAME, SCRIPTSOWN, 297 SCRIPTSGRP, SCRIPTSMODE, SCRIPTSDIR variables that can be 298 further specialized by SCRIPTS<VAR>_<script>. 299 300The include file <bsd.prog.mk> includes the file named "../Makefile.inc" 301if it exists, as well as the include file <bsd.man.mk>. 302 303Some simple examples: 304 305To build foo from foo.c with a manual page foo.1, use: 306 307 PROG= foo 308 309 .include <bsd.prog.mk> 310 311To build foo from foo.c with a manual page foo.2, add the line: 312 313 MAN= foo.2 314 315If foo does not have a manual page at all, add the line: 316 317 NOMAN= noman 318 319If foo has multiple source files, add the line: 320 321 SRCS= a.c b.c c.c d.c 322 323=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 324 325The include file <bsd.subdir.mk> contains the default targets for building 326subdirectories. It has the same seven targets as <bsd.prog.mk>: all, clean, 327cleandir, depend, install, lint, and tags. For all of the directories 328listed in the variable SUBDIRS, the specified directory will be visited 329and the target made. There is also a default target which allows the 330command "make subdir" where subdir is any directory listed in the variable 331SUBDIRS. 332 333=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 334 335The include file <bsd.lib.mk> has support for building libraries. It has 336the same seven targets as <bsd.prog.mk>: all, clean, cleandir, depend, 337install, lint, and tags. It has a limited number of suffixes, consistent 338with the current needs of the BSD tree. 339 340It sets/uses the following variables: 341 342LIBDIR Target directory for libraries. 343 344LINTLIBDIR Target directory for lint libraries. 345 346LIBGRP Library group. 347 348LIBOWN Library owner. 349 350LIBMODE Library mode. 351 352LDADD Additional loader objects. 353 354MAN The manual pages to be installed (use a .1 - .9 suffix). 355 356SRCS List of source files to build the library. Suffix types 357 .s, .c, and .f are supported. Note, .s files are preferred 358 to .c files of the same name. (This is not the default for 359 versions of make.) 360 361The include file <bsd.lib.mk> includes the file named "../Makefile.inc" 362if it exists, as well as the include file <bsd.man.mk>. 363 364It has rules for building profiled objects; profiled libraries are 365built by default. 366 367Libraries are ranlib'd before installation. 368