1# @(#)bsd.README 8.2 (Berkeley) 4/2/94 2# $FreeBSD$ 3 4This is the README file for the "include" files for the FreeBSD 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.arch.inc.mk - includes arch-specific Makefile.$arch 20bsd.compiler.mk - defined based on current compiler 21bsd.cpu.mk - sets CPU/arch-related variables (included from sys.mk) 22bsd.dep.mk - handle Makefile dependencies 23bsd.doc.mk - building troff system documents 24bsd.endian.mk - TARGET_ENDIAN=1234(little) or 4321 (big) for target 25bsd.files.mk - install of general purpose files 26bsd.incs.mk - install of include files 27bsd.info.mk - building GNU Info hypertext system (deprecated) 28bsd.init.mk - initialization for the make include files 29bsd.kmod.mk - building loadable kernel modules 30bsd.lib.mk - support for building libraries 31bsd.libnames.mk - define library names 32bsd.links.mk - install of links (sym/hard) 33bsd.man.mk - install of manual pages and their links 34bsd.nls.mk - build and install of NLS catalogs 35bsd.obj.mk - creating 'obj' directories and cleaning up 36bsd.own.mk - define common variables 37bsd.port.mk - building ports 38bsd.port.post.mk - building ports 39bsd.port.pre.mk - building ports 40bsd.port.subdir.mk - targets for building subdirectories for ports 41bsd.prog.mk - building programs from source files 42bsd.progs.mk - build multiple programs from sources (deprecated) 43bsd.snmpmod.mk - building modules for the SNMP daemon bsnmpd 44bsd.subdir.mk - targets for building subdirectories 45bsd.sys.mk - common settings used for building FreeBSD sources 46bsd.test.mk - building test programs from source files 47sys.mk - default rules for all makes 48 49This file does not document bsd.port*.mk. They are documented in ports(7). 50 51See also make(1), mkdep(1), style.Makefile(5) and `PMake - A 52Tutorial', located in /usr/share/doc/psd/12.make. 53 54=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 55 56Random things worth knowing about this document: 57 58If appropriate when documenting the variables the default value is 59indicated using square brackets e.g. [gzip]. 60In some cases the default value depend on other values (e.g. system 61architecture). In these cases the most common value is indicated. 62 63This document contains some simple examples of the usage of the BSD make 64include files. For more examples look at the makefiles in the FreeBSD 65source tree. 66 67=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 68 69RANDOM THINGS WORTH KNOWING: 70 71The files are like C-style #include files, and pretty much behave like 72you'd expect. The syntax is slightly different in that a single '.' is 73used instead of the hash mark, i.e. ".include <bsd.prog.mk>". 74 75One difference that will save you lots of debugging time is that inclusion 76of the file is normally done at the *end* of the Makefile. The reason for 77this is because .mk files often modify variables and behavior based on the 78values of variables set in the Makefile. To make this work, remember that 79the FIRST target found is the target that is used, i.e. if the Makefile has: 80 81 a: 82 echo a 83 a: 84 echo a number two 85 86the command "make a" will echo "a". To make things confusing, the SECOND 87variable assignment is the overriding one, i.e. if the Makefile has: 88 89 a= foo 90 a= bar 91 92 b: 93 echo ${a} 94 95the command "make b" will echo "bar". This is for compatibility with the 96way the V7 make behaved. 97 98It's fairly difficult to make the BSD .mk files work when you're building 99multiple programs in a single directory. It's a lot easier to split up 100the programs than to deal with the problem. Most of the agony comes from 101making the "obj" directory stuff work right, not because we switch to a new 102version of make. So, don't get mad at us, figure out a better way to handle 103multiple architectures so we can quit using the symbolic link stuff. 104(Imake doesn't count.) 105 106The file .depend in the source directory is expected to contain dependencies 107for the source files. This file is read automatically by make after reading 108the Makefile. 109 110The variable DESTDIR works as before. It's not set anywhere but will change 111the tree where the file gets installed. 112 113The profiled libraries are no longer built in a different directory than 114the regular libraries. A new suffix, ".po", is used to denote a profiled 115object. 116 117=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 118 119The following variables are common: 120 121CFLAGS.${COMPILER_TYPE} 122 Flags dependent on compiler added to CXXFLAGS. 123CFLAGS.${MACHINE_ARCH} 124 Architectural flags added to CFLAGS. 125CFLAGS_NO_SIMD Add this to CFLAGS for programs that don't want any SIMD 126 instructions generated. It is setup in bsd.cpu.mk to an 127 appropriate value for the compiler and target. 128CXXFLAGS.${COMPILER_TYPE} 129 Flags dependent on compiler added to CXXFLAGS. 130CXXFLAGS.${MACHINE_ARCH} 131 Architectural flags added to CXXFLAGS. 132COMPILER_FEATURES 133 A list of features that the compiler supports. Zero or 134 more of: 135 c++11 Supports full C++ 11 standard. 136 137COMPILER_TYPE Type of compiler, either clang or gcc, though other 138 values are possible. Don't assume != clang == gcc. 139 140COMPILER_VERSION 141 A numeric constant equal to: 142 major * 10000 + minor * 100 + tiny 143 for the compiler's self-reported version. 144 145=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 146 147The include file <sys.mk> has the default rules for all makes, in the BSD 148environment or otherwise. You probably don't want to touch this file. 149 150=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 151 152The include file <bsd.arch.inc.mk> includes other Makefiles for specific 153architectures, if they exist. It will include the first of the following 154files that it finds: Makefile.${MACHINE}, Makefile.${MACHINE_ARCH}, 155Makefile.${MACHINE_CPUARCH} 156 157=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 158 159The include file <bsd.man.mk> handles installing manual pages and their 160links. 161 162It has three targets: 163 164 all-man: 165 build manual pages. 166 maninstall: 167 install the manual pages and their links. 168 manlint: 169 verify the validity of manual pages. 170 171It sets/uses the following variables: 172 173MANDIR Base path for manual installation. 174 175MANGRP Manual group. 176 177MANOWN Manual owner. 178 179MANMODE Manual mode. 180 181MANSUBDIR Subdirectory under the manual page section, i.e. "/vax" 182 or "/tahoe" for machine specific manual pages. 183 184MAN The manual pages to be installed (use a .1 - .9 suffix). 185 186MLINKS List of manual page links (using a .1 - .9 suffix). The 187 linked-to file must come first, the linked file second, 188 and there may be multiple pairs. The files are hard-linked. 189 190The include file <bsd.man.mk> includes a file named "../Makefile.inc" if 191it exists. 192 193=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 194 195The include file <bsd.own.mk> contains the owners, groups, etc. for both 196manual pages and binaries. 197 198It has no targets. 199 200It sets/uses the following variables: 201 202BINGRP Binary group. 203 204BINOWN Binary owner. 205 206BINMODE Binary mode. 207 208MANDIR Base path for manual installation. 209 210MANGRP Manual group. 211 212MANOWN Manual owner. 213 214MANMODE Manual mode. 215 216This file is generally useful when building your own Makefiles so that 217they use the same default owners etc. as the rest of the tree. 218 219=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 220 221The include file <bsd.prog.mk> handles building programs from one or 222more source files, along with their manual pages. It has a limited number 223of suffixes, consistent with the current needs of the BSD tree. 224 225It has seven targets: 226 227 all: 228 build the program and its manual page 229 clean: 230 remove the program and any object files. 231 cleandir: 232 remove all of the files removed by the target clean, as 233 well as .depend, tags, and any manual pages. 234 depend: 235 make the dependencies for the source files, and store 236 them in the file .depend. 237 install: 238 install the program and its manual pages; if the Makefile 239 does not itself define the target install, the targets 240 beforeinstall and afterinstall may also be used to cause 241 actions immediately before and after the install target 242 is executed. 243 lint: 244 run lint on the source files 245 tags: 246 create a tags file for the source files. 247 248It sets/uses the following variables: 249 250BINGRP Binary group. 251 252BINOWN Binary owner. 253 254BINMODE Binary mode. 255 256CLEANFILES Additional files to remove and 257CLEANDIRS additional directories to remove during clean and cleandir 258 targets. "rm -f" and "rm -rf" used respectively. 259 260CFLAGS Flags to the compiler when creating C objects. 261 262FILES A list of non-executable files. 263 The installation is controlled by the FILESNAME, FILESOWN, 264 FILESGRP, FILESMODE, FILESDIR variables that can be 265 further specialized by FILES<VAR>_<file>. 266 267LDADD Additional loader objects. Usually used for libraries. 268 For example, to load with the compatibility and utility 269 libraries, use: 270 271 LDADD=-lutil -lcompat 272 273LDFLAGS Additional loader flags. Passed to the loader via CC, 274 since that's used to link programs as well, so loader 275 specific flags need to be prefixed with -Wl, to work. 276 277LINKS The list of binary links; should be full pathnames, the 278 linked-to file coming first, followed by the linked 279 file. The files are hard-linked. For example, to link 280 /bin/test and /bin/[, use: 281 282 LINKS= ${DESTDIR}/bin/test ${DESTDIR}/bin/[ 283 284MAN Manual pages (should end in .1 - .9). If no MAN variable 285 is defined, "MAN=${PROG}.1" is assumed. 286 287PROG The name of the program to build. If not supplied, nothing 288 is built. 289 290PROG_CXX If defined, the name of the program to build. Also 291 causes <bsd.prog.mk> to link the program with the 292 standard C++ library. PROG_CXX overrides the value 293 of PROG if PROG is also set. 294 295PROGNAME The name that the above program will be installed as, if 296 different from ${PROG}. 297 298SRCS List of source files to build the program. If SRCS is not 299 defined, it's assumed to be ${PROG}.c or, if PROG_CXX is 300 defined, ${PROG_CXX}.cc. 301 302DPADD Additional dependencies for the program. Usually used for 303 libraries. For example, to depend on the compatibility and 304 utility libraries use: 305 306 DPADD=${LIBCOMPAT} ${LIBUTIL} 307 308 There is a predefined identifier for each (non-profiled, 309 non-shared) library and object. Library file names are 310 transformed to identifiers by removing the extension and 311 converting to upper case. 312 313 There are no special identifiers for profiled or shared 314 libraries or objects. The identifiers for the standard 315 libraries are used in DPADD. This works correctly iff all 316 the libraries are built at the same time. Unfortunately, 317 it causes unnecessary relinks to shared libraries when 318 only the static libraries have changed. Dependencies on 319 shared libraries should be only on the library version 320 numbers. 321 322STRIP The flag passed to the install program to cause the binary 323 to be stripped. This is to be used when building your 324 own install script so that the entire system can be made 325 stripped/not-stripped using a single nob. 326 327SUBDIR A list of subdirectories that should be built as well. 328 Each of the targets will execute the same target in the 329 subdirectories. 330 331SCRIPTS A list of interpreter scripts [file.{sh,csh,pl,awk,...}]. 332 The installation is controlled by the SCRIPTSNAME, SCRIPTSOWN, 333 SCRIPTSGRP, SCRIPTSMODE, SCRIPTSDIR variables that can be 334 further specialized by SCRIPTS<VAR>_<script>. 335 336The include file <bsd.prog.mk> includes the file named "../Makefile.inc" 337if it exists, as well as the include file <bsd.man.mk>. 338 339Some simple examples: 340 341To build foo from foo.c with a manual page foo.1, use: 342 343 PROG= foo 344 345 .include <bsd.prog.mk> 346 347To build foo from foo.c with a manual page foo.2, add the line: 348 349 MAN= foo.2 350 351If foo does not have a manual page at all, add the line: 352 353 MAN= 354 355If foo has multiple source files, add the line: 356 357 SRCS= a.c b.c c.c d.c 358 359=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 360 361The include file <bsd.subdir.mk> contains the default targets for building 362subdirectories. It has the same seven targets as <bsd.prog.mk>: all, clean, 363cleandir, depend, install, lint, and tags. For all of the directories 364listed in the variable SUBDIRS, the specified directory will be visited 365and the target made. There is also a default target which allows the 366command "make subdir" where subdir is any directory listed in the variable 367SUBDIRS. 368 369=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 370 371The include file <bsd.lib.mk> has support for building libraries. It has 372the same seven targets as <bsd.prog.mk>: all, clean, cleandir, depend, 373install, lint, and tags. It has a limited number of suffixes, consistent 374with the current needs of the BSD tree. 375 376It sets/uses the following variables: 377 378LIB The name of the library to build. 379 380LIB_CXX The name of the library to build. It also causes 381 <bsd.lib.mk> to link the library with the 382 standard C++ library. LIB_CXX overrides the value 383 of LIB if LIB is also set. 384 385LIBDIR Target directory for libraries. 386 387LINTLIBDIR Target directory for lint libraries. 388 389LIBGRP Library group. 390 391LIBOWN Library owner. 392 393LIBMODE Library mode. 394 395LDADD Additional loader objects. 396 397MAN The manual pages to be installed (use a .1 - .9 suffix). 398 399SRCS List of source files to build the library. Suffix types 400 .s, .c, and .f are supported. Note, .s files are preferred 401 to .c files of the same name. (This is not the default for 402 versions of make.) 403 404SHLIB_LDSCRIPT Template file to generate shared library linker script. 405 Unless used, a simple symlink is created to the real 406 shared object. 407 408LIBRARIES_ONLY Do not build or install files other than the library. 409 410The include file <bsd.lib.mk> includes the file named "../Makefile.inc" 411if it exists, as well as the include file <bsd.man.mk>. 412 413It has rules for building profiled objects; profiled libraries are 414built by default. 415 416Libraries are ranlib'd before installation. 417 418=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 419 420The include file <bsd.test.mk> handles building one or more test programs 421intended to be used in the FreeBSD Test Suite under /usr/tests/. 422 423It has seven targets: 424 425 all: 426 build the test programs. 427 clean: 428 remove the test programs and any object files. 429 cleandir: 430 remove all of the files removed by the target clean, as 431 well as .depend and tags. 432 depend: 433 make the dependencies for the source files, and store 434 them in the file .depend. 435 install: 436 install the test programs and their data files; if the 437 Makefile does not itself define the target install, the 438 targets beforeinstall and afterinstall may also be used 439 to cause actions immediately before and after the 440 install target is executed. 441 lint: 442 run lint on the source files. 443 tags: 444 create a tags file for the source files. 445 test: 446 runs the test programs from the object directory; if the 447 Makefile does not itself define the target test, the 448 targets beforetest and aftertest may also be used to 449 cause actions immediately before and after the test 450 target is executed. 451 452It sets/uses the following variables, among many others: 453 454TESTDIR Path to the installed tests. Must be a subdirectory of 455 TESTSBASE and the subpath should match the relative 456 location of the tests within the src tree. 457 458KYUAFILE If 'auto' (the default), generate a Kyuafile out of the 459 test programs defined in the Makefile. If 'yes', then a 460 manually-crafted Kyuafile must be supplied with the 461 sources. If 'no', no Kyuafile is installed (useful for 462 subdirectories providing helper programs or data files 463 only). 464 465ATF_TESTS_C The names of the ATF C test programs to build. 466 467ATF_TESTS_CXX The names of the ATF C++ test programs to build. 468 469ATF_TESTS_SH The names of the ATF sh test programs to build. 470 471PLAIN_TESTS_C The names of the plain (legacy) programs to build. 472 473PLAIN_TESTS_CXX The names of the plain (legacy) test programs to build. 474 475PLAIN_TESTS_SH The names of the plain (legacy) test programs to build. 476 477TAP_PERL_INTERPRETER 478 Path to the Perl interpreter to be used for 479 TAP-compliant test programs that are written in Perl. 480 Refer to TAP_TESTS_PERL for details. 481 482TAP_TESTS_C The names of the TAP-compliant C test programs to build. 483 484TAP_TESTS_CXX The names of the TAP-compliant C++ test programs to 485 build. 486 487TAP_TESTS_PERL The names of the TAP-compliant Perl test programs to 488 build. The corresponding source files should end with 489 the .pl extension; the test program is marked as 490 requiring Perl; and TAP_PERL_INTERPRETER is used in the 491 built scripts as the interpreter of choice. 492 493TAP_TESTS_SH The names of the TAP-compliant sh test programs to 494 build. 495 496TESTS_SUBDIRS List of subdirectories containing tests into which to 497 recurse. Differs from SUBDIR in that these directories 498 get registered into the automatically-generated 499 Kyuafile (if any). 500 501NOT_FOR_TEST_SUITE 502 If defined, none of the built test programs get 503 installed under /usr/tests/ and no Kyuafile is 504 automatically generated. Should not be used within the 505 FreeBSD source tree but is provided for the benefit of 506 third-parties. 507 508The actual building of the test programs is performed by <bsd.prog.mk>. 509Please see the documentation above for this other file for additional 510details on the behavior of <bsd.test.mk>. 511