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 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 273LIBADD Additional libraries. This is for base system libraries 274 and is only valid inside of the /usr/src tree. 275 Rather than use LDADD=-lname use LIBADD=name. 276 277LDFLAGS Additional loader flags. Passed to the loader via CC, 278 since that's used to link programs as well, so loader 279 specific flags need to be prefixed with -Wl, to work. 280 281LINKS The list of binary links; should be full pathnames, the 282 linked-to file coming first, followed by the linked 283 file. The files are hard-linked. For example, to link 284 /bin/test and /bin/[, use: 285 286 LINKS= ${DESTDIR}/bin/test ${DESTDIR}/bin/[ 287 288MAN Manual pages (should end in .1 - .9). If no MAN variable 289 is defined, "MAN=${PROG}.1" is assumed. 290 291PROG The name of the program to build. If not supplied, nothing 292 is built. 293 294PROG_CXX If defined, the name of the program to build. Also 295 causes <bsd.prog.mk> to link the program with the 296 standard C++ library. PROG_CXX overrides the value 297 of PROG if PROG is also set. 298 299PROGS When used with <bsd.progs.mk>, allow building multiple 300PROGS_CXX PROG and PROGS_CXX in one Makefile. To define 301 individual variables for each program the VAR.prog 302 syntax should be used. For example: 303 304 PROGS= foo bar 305 SRCS.foo= foo_src.c 306 LDADD.foo= -lutil 307 SRCS.bar= bar_src.c 308 309 The supported variables are BINDIR BINGRP BINMODE BINOWN 310 CFLAGS CPPFLAGS CXXFLAGS DPADD DPLIBS DPSRCS LDADD 311 LDFLAGS LIBADD MAN MLINKS PROGNAME SRCS. 312 313PROGNAME The name that the above program will be installed as, if 314 different from ${PROG}. 315 316SRCS List of source files to build the program. If SRCS is not 317 defined, it's assumed to be ${PROG}.c or, if PROG_CXX is 318 defined, ${PROG_CXX}.cc. 319 320DPADD Additional dependencies for the program. Usually used for 321 libraries. For example, to depend on the compatibility and 322 utility libraries use: 323 324 DPADD=${LIBCOMPAT} ${LIBUTIL} 325 326 There is a predefined identifier for each (non-profiled, 327 non-shared) library and object. Library file names are 328 transformed to identifiers by removing the extension and 329 converting to upper case. 330 331 There are no special identifiers for profiled or shared 332 libraries or objects. The identifiers for the standard 333 libraries are used in DPADD. This works correctly iff all 334 the libraries are built at the same time. Unfortunately, 335 it causes unnecessary relinks to shared libraries when 336 only the static libraries have changed. Dependencies on 337 shared libraries should be only on the library version 338 numbers. 339 340STRIP The flag passed to the install program to cause the binary 341 to be stripped. This is to be used when building your 342 own install script so that the entire system can be made 343 stripped/not-stripped using a single nob. 344 345SUBDIR A list of subdirectories that should be built as well. 346 Each of the targets will execute the same target in the 347 subdirectories. 348 349SCRIPTS A list of interpreter scripts [file.{sh,csh,pl,awk,...}]. 350 The installation is controlled by the SCRIPTSNAME, SCRIPTSOWN, 351 SCRIPTSGRP, SCRIPTSMODE, SCRIPTSDIR variables that can be 352 further specialized by SCRIPTS<VAR>_<script>. 353 354The include file <bsd.prog.mk> includes the file named "../Makefile.inc" 355if it exists, as well as the include file <bsd.man.mk>. 356 357Some simple examples: 358 359To build foo from foo.c with a manual page foo.1, use: 360 361 PROG= foo 362 363 .include <bsd.prog.mk> 364 365To build foo from foo.c with a manual page foo.2, add the line: 366 367 MAN= foo.2 368 369If foo does not have a manual page at all, add the line: 370 371 MAN= 372 373If foo has multiple source files, add the line: 374 375 SRCS= a.c b.c c.c d.c 376 377=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 378 379The include file <bsd.subdir.mk> contains the default targets for building 380subdirectories. It has the same seven targets as <bsd.prog.mk>: all, clean, 381cleandir, depend, install, lint, and tags. For all of the directories 382listed in the variable SUBDIRS, the specified directory will be visited 383and the target made. There is also a default target which allows the 384command "make subdir" where subdir is any directory listed in the variable 385SUBDIRS. 386 387=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 388 389The include file <bsd.lib.mk> has support for building libraries. It has 390the same seven targets as <bsd.prog.mk>: all, clean, cleandir, depend, 391install, lint, and tags. It has a limited number of suffixes, consistent 392with the current needs of the BSD tree. 393 394It sets/uses the following variables: 395 396LIB The name of the library to build. 397 398LIB_CXX The name of the library to build. It also causes 399 <bsd.lib.mk> to link the library with the 400 standard C++ library. LIB_CXX overrides the value 401 of LIB if LIB is also set. 402 403LIBDIR Target directory for libraries. 404 405LINTLIBDIR Target directory for lint libraries. 406 407LIBGRP Library group. 408 409LIBOWN Library owner. 410 411LIBMODE Library mode. 412 413LDADD Additional loader objects. 414 415LIBADD Additional libraries. This is for base system libraries 416 and is only valid inside of the /usr/src tree. 417 Rather than use LDADD=-lname use LIBADD=name. 418 419MAN The manual pages to be installed (use a .1 - .9 suffix). 420 421SRCS List of source files to build the library. Suffix types 422 .s, .c, and .f are supported. Note, .s files are preferred 423 to .c files of the same name. (This is not the default for 424 versions of make.) 425 426SHLIB_LDSCRIPT Template file to generate shared library linker script. 427 Unless used, a simple symlink is created to the real 428 shared object. 429 430LIBRARIES_ONLY Do not build or install files other than the library. 431 432The include file <bsd.lib.mk> includes the file named "../Makefile.inc" 433if it exists, as well as the include file <bsd.man.mk>. 434 435It has rules for building profiled objects; profiled libraries are 436built by default. 437 438Libraries are ranlib'd before installation. 439 440=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 441 442The include file <bsd.test.mk> handles building one or more test programs 443intended to be used in the FreeBSD Test Suite under /usr/tests/. 444 445It has seven targets: 446 447 all: 448 build the test programs. 449 clean: 450 remove the test programs and any object files. 451 cleandir: 452 remove all of the files removed by the target clean, as 453 well as .depend and tags. 454 depend: 455 make the dependencies for the source files, and store 456 them in the file .depend. 457 install: 458 install the test programs and their data files; if the 459 Makefile does not itself define the target install, the 460 targets beforeinstall and afterinstall may also be used 461 to cause actions immediately before and after the 462 install target is executed. 463 lint: 464 run lint on the source files. 465 tags: 466 create a tags file for the source files. 467 test: 468 runs the test programs from the object directory; if the 469 Makefile does not itself define the target test, the 470 targets beforetest and aftertest may also be used to 471 cause actions immediately before and after the test 472 target is executed. 473 474It sets/uses the following variables, among many others: 475 476TESTDIR Path to the installed tests. Must be a subdirectory of 477 TESTSBASE and the subpath should match the relative 478 location of the tests within the src tree. 479 480KYUAFILE If 'auto' (the default), generate a Kyuafile out of the 481 test programs defined in the Makefile. If 'yes', then a 482 manually-crafted Kyuafile must be supplied with the 483 sources. If 'no', no Kyuafile is installed (useful for 484 subdirectories providing helper programs or data files 485 only). 486 487ATF_TESTS_C The names of the ATF C test programs to build. 488 489ATF_TESTS_CXX The names of the ATF C++ test programs to build. 490 491ATF_TESTS_SH The names of the ATF sh test programs to build. 492 493PLAIN_TESTS_C The names of the plain (legacy) programs to build. 494 495PLAIN_TESTS_CXX The names of the plain (legacy) test programs to build. 496 497PLAIN_TESTS_SH The names of the plain (legacy) test programs to build. 498 499TAP_PERL_INTERPRETER 500 Path to the Perl interpreter to be used for 501 TAP-compliant test programs that are written in Perl. 502 Refer to TAP_TESTS_PERL for details. 503 504TAP_TESTS_C The names of the TAP-compliant C test programs to build. 505 506TAP_TESTS_CXX The names of the TAP-compliant C++ test programs to 507 build. 508 509TAP_TESTS_PERL The names of the TAP-compliant Perl test programs to 510 build. The corresponding source files should end with 511 the .pl extension; the test program is marked as 512 requiring Perl; and TAP_PERL_INTERPRETER is used in the 513 built scripts as the interpreter of choice. 514 515TAP_TESTS_SH The names of the TAP-compliant sh test programs to 516 build. 517 518TESTS_SUBDIRS List of subdirectories containing tests into which to 519 recurse. Differs from SUBDIR in that these directories 520 get registered into the automatically-generated 521 Kyuafile (if any). 522 523NOT_FOR_TEST_SUITE 524 If defined, none of the built test programs get 525 installed under /usr/tests/ and no Kyuafile is 526 automatically generated. Should not be used within the 527 FreeBSD source tree but is provided for the benefit of 528 third-parties. 529 530The actual building of the test programs is performed by <bsd.prog.mk>. 531Please see the documentation above for this other file for additional 532details on the behavior of <bsd.test.mk>. 533