1# $OpenBSD: bsd.README,v 1.86 2023/07/25 20:19:14 asou Exp $ 2# $NetBSD: bsd.README,v 1.17 1996/04/13 02:08:08 thorpej Exp $ 3# @(#)bsd.README 5.1 (Berkeley) 5/11/90 4 5This is the README file for the make "include" files for the BSD 6source tree. The files are installed in /usr/share/mk, and are, by 7convention, named with the suffix ".mk". 8 9bsd.dep.mk - handle Makefile dependencies 10bsd.lib.mk - support for building libraries 11bsd.man.mk - installing manual pages and their links 12bsd.obj.mk - creating 'obj' directories and cleaning up 13bsd.own.mk - define common variables 14bsd.port.mk - building ports (see bsd.port.mk(5)) 15bsd.port.arch.mk - glue for building ports with MD stuff 16bsd.port.subdir.mk - targets for building subdirectories for ports 17bsd.prog.mk - building programs from source files 18bsd.regress.mk - regression tests (see bsd.regress.mk(5)) 19bsd.subdir.mk - targets for building subdirectories 20bsd.sys.mk - overrides for <sys.mk> for building OpenBSD 21sys.mk - global default rules, mostly POSIX 22 23Note, this file is not intended to replace reading through the .mk 24files for anything tricky. 25 26=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 27 28RANDOM THINGS WORTH KNOWING: 29 30The files are simply C-style #include files, and pretty much behave like 31you'd expect. The syntax is slightly different in that a single '.' is 32used instead of the hash mark, i.e. ".include <bsd.prog.mk>". 33 34One difference that will save you lots of debugging time is that inclusion 35of the file is normally done at the *end* of the Makefile. The reason for 36this is because .mk files often modify variables and behavior based on the 37values of variables set in the Makefile. To make this work, remember that 38the FIRST target found is the target that is used, i.e. if the Makefile has: 39 40 a: 41 echo a 42 a: 43 echo a number two 44 45the command "make a" will echo "a". To make things confusing, the SECOND 46variable assignment is the overriding one, i.e. if the Makefile has: 47 48 a= foo 49 a= bar 50 51 b: 52 echo ${a} 53 54the command "make b" will echo "bar". This is for compatibility with the 55way the V7 make behaved. 56 57To make things even more confusing, make uses lazy evaluation. All 58variables are expanded only when needed. Which means that, in 59 60 a= foo 61 62 b: $(a) 63 echo $(.ALLSRC) 64 echo $(a) 65 66 foo: 67 touch foo 68 69 a= bar 70 71the command "make b" will echo "foo"; echo "bar". The first $(a) means 72"foo", because it's needed to generate the dependency rule when it's read, 73but the second $(a) is only expanded when needed, at which point a contains 74bar. 75 76It's fairly difficult to make the BSD .mk files work when you're building 77multiple programs in a single directory. It's a lot easier to split up the 78programs than to deal with the problem. Most of the agony comes from making 79the "obj" directory stuff work right, not because we switched to a new version 80of make. So, don't get mad at us, figure out a better way to handle multiple 81architectures so we can quit using the symbolic link stuff. (Imake doesn't 82count.) 83 84Dependencies are handled using the compiler's -M* options, resulting in 85lots of .d files. These are manually included through <bsd.dep.mk>. 86 87<bsd.dep.mk> also provides an empty depend target to <bsd.prog.mk> and 88<bsd.lib.mk>, for backward compatibility. 89 90The variable DESTDIR works as before. It's not set anywhere but will change 91the tree where the file gets installed. 92 93The profiled libraries are no longer built in a different directory than 94the regular libraries. A new suffix, ".po", is used to denote a profiled 95object. 96 97=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 98 99The include file <sys.mk> has the default rules for all makes, in the BSD 100environment or otherwise. You probably don't want to touch this file. 101 102=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 103 104The include file <bsd.sys.mk> is used by <bsd.prog.mk> and 105<bsd.lib.mk>. It overrides parts of <sys.mk> for building the 106OpenBSD source tree. For example, it contains a better yacc(1) 107rule assigning the proper names to all output files. 108 109=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 110 111The include file <bsd.man.mk> handles installing manual pages and their 112links. 113 114It has a single target: 115 116 maninstall: 117 Install the manual pages and their links. 118 119It sets/uses the following variables: 120 121MANDIR Base path for manual installation. 122 123MANGRP Manual group. 124 125MANOWN Manual owner. 126 127MANMODE Manual mode. 128 129MANSUBDIR Subdirectory under the manual page section, i.e. "amd64" 130 or "sparc64" for machine specific manual pages. 131 132MAN The manual pages to be installed (use a .1 - .9 suffix). 133 134MLINKS List of manual page links (using a .1 - .9 suffix). The 135 linked-to file must come first, the linked file second, 136 and there may be multiple pairs. The files are soft-linked. 137 138BEFOREMAN List of extra targets that must be already built before the 139 man target can be run. Those targets must be real files (and 140 not .PHONY targets). 141 142The include file <bsd.man.mk> includes a file named "../Makefile.inc" if 143it exists. 144 145=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 146 147The include file <bsd.own.mk> contains source tree configuration parameters, 148such as the owners, groups, etc. for both manual pages and binaries, and 149a few global "feature configuration" parameters. 150 151It has no targets. 152 153To get system-specific configuration parameters, bsd.own.mk will try to 154include the file specified by the "MAKECONF" variable. If MAKECONF is not 155set, or no such file exists, the system make configuration file, /etc/mk.conf 156is included. These files may define any of the variables described below. 157 158bsd.own.mk sets the following variables, if they are not already defined 159(defaults are in brackets): 160 161BSDSRCDIR The real path to the system sources, so that 'make obj' 162 will work correctly. [/usr/src] 163 164BSDOBJDIR The real path to the system 'obj' tree, so that 'make obj' 165 will work correctly. [/usr/obj] 166 167BINGRP Binary group. [bin] 168 169BINOWN Binary owner. [root] 170 171BINMODE Binary mode. [555] 172 173NONBINMODE Mode for non-executable files. [444] 174 175DIRMODE Mode for new directories. [755] 176 177MANDIR Base path for manual installation. [/usr/share/man/man] 178 179MANGRP Manual group. [bin] 180 181MANOWN Manual owner. [root] 182 183MANMODE Manual mode. [${NONBINMODE}] 184 185LIBDIR Base path for library installation. [/usr/lib] 186 187LIBGRP Library group. [${BINGRP}] 188 189LIBOWN Library owner. [${BINOWN}] 190 191LIBMODE Library mode. [${NONBINMODE}] 192 193DOCDIR Base path for system documentation 194 installation. [/usr/share/doc] 195 196DOCGRP Documentation group. [bin] 197 198DOCOWN Documentation owner. [root] 199 200DOCMODE Documentation mode. [${NONBINMODE}] 201 202INSTALL_STRIP The flag passed to the install program to cause the binary 203 to be stripped. This is to be used when building your 204 own install script so that the entire system can be made 205 stripped/not-stripped using a single knob. Note that 206 INSTALL_STRIP is not set if ${DEBUG} is defined. [-s] 207 208INSTALL_COPY The old usage of this flag is obsolescent since install(1) 209 now copies by default. However, it can also be used to 210 specify that a file not be copied unless it is different 211 (via the -p option). See install(1) for details. This 212 is to be used when building our own install script so 213 that the entire system can either be installed with copies, 214 or copy-if-different using a single knob. [-c] 215 216Additionally, the following variables may be set by bsd.own.mk or in a 217make configuration file to modify the behaviour of the system build 218process (default values are in brackets along with comments, if set by 219bsd.own.mk): 220 221SKEY Compile in support for S/key authentication. [yes, set 222 unconditionally] 223 224SYS_INCLUDE Copy or symlink kernel include files into /usr/include. 225 Possible values are "symlinks" or "copies" (which is 226 the same as the variable being unset). 227 228NOPROFILE Do not build profiled versions of system libraries. 229 230NOPIC Do not build PIC versions of system libraries, and 231 do not build shared libraries. 232 233NOPIE Do not build PIE objects or executables. 234 235DEBUG Add -g to assembly, C compiler and linking passes. Also 236 doesn't set STRIP to -s per default if defined. 237 238WARNINGS Adds appropriate warning flags (defined in CDIAGFLAGS, 239 e.g., -Wall...) to compiles. [no] 240 241SUDO Command to run when doing "make install" portion of 242 "make build". If set to /usr/bin/doas, this allows one 243 to run "make build" as a user other than root (assuming 244 doas is setup for that user). 245 246PIPE If set to "-pipe" gcc will be given the -pipe option 247 which can speed up compiles on machines with memory 248 to spare. Instead of using temp files, gcc uses pipes 249 for the temporary data. 250 251GLOBAL_AUTOCONF_CACHE 252 Set to the name of a file that all cached GNU autoconf 253 test results will be saved in. Reduces redundant tests. 254 Be careful! Redundant tests may not be redundant if you 255 are installing substantially updated gnu programs. 256 257bsd.own.mk is generally useful when building your own Makefiles so that 258they use the same default owners etc. as the rest of the tree. 259 260=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 261 262The include file <bsd.prog.mk> handles building programs from one or 263more source files, along with their manual pages. It has a limited number 264of suffixes, consistent with the current needs of the BSD tree. 265 266It has six targets: 267 268 all: 269 build the program and its manual page 270 clean: 271 remove the program, any object files, and some other 272 files that are automatically generated. 273 cleandir: 274 remove all of the files removed by the target clean, as 275 well as the tags file. 276 includes: 277 install any header files. 278 install: 279 install the program and its manual pages; if the Makefile 280 does not itself define the target install, the targets 281 beforeinstall and afterinstall may also be used to cause 282 actions immediately before and after the install target 283 is executed. 284 tags: 285 create a tags file for the source files. 286 287It uses the following variables: 288 289BINGRP Binary group. 290 291BINOWN Binary owner. 292 293BINMODE Binary mode. 294 295BUILDFIRST Stuff that needs to be built before anything else, in 296 terms of dependencies. 297 298BUILDAFTER Stuff that comes later (usually don't touch, defined correctly 299 by <bsd.prog.mk> and <bsd.lib.mk>) 300 301CLEANFILES Additional files to remove for the clean and cleandir targets. 302 303COPTS Additional flags to the compiler when creating C objects. 304 305CXXOPTS Additional flags to the compiler when creating C++ objects. 306 307LDADD Additional linker objects. Usually used for libraries. 308 For example, to link with the crypto and utility 309 libraries, use: 310 311 LDADD+=-lutil -lcrypto 312 313LDFLAGS Additional linker flags. 314 315LINKS The list of binary links; should be full pathnames, the 316 linked-to file coming first, followed by the linked 317 file. The files are hard-linked. For example, to link 318 /bin/test and /bin/[, use: 319 320 LINKS= ${DESTDIR}/bin/test ${DESTDIR}/bin/[ 321 322MAN Manual pages (should end in .1 - .9). If no MAN variable is 323 defined, "MAN=${PROG}.1" is assumed. 324 325PROG The name of the program to build. If not supplied, nothing 326 is built. 327 328SRCS List of source files to build the program. If it's not 329 defined, it's assumed to be ${PROG}.c. 330 331DPADD Additional dependencies for the program. Usually used for 332 libraries. For example, to depend on the crypto and 333 utility libraries use: 334 335 DPADD+=${LIBCRYPTO} ${LIBUTIL} 336 337 The following libraries are predefined for DPADD: 338 339 LIBC /usr/lib/libc.a 340 LIBCBOR /usr/lib/libcbor.a 341 LIBCRYPTO /usr/lib/libcrypto.a 342 LIBCURSES /usr/lib/libcurses.a 343 LIBEDIT /usr/lib/libedit.a 344 LIBELF /usr/lib/libelf.a 345 LIBEVENT /usr/lib/libevent.a 346 LIBEXPAT /usr/lib/libexpat.a 347 LIBFIDO2 /usr/lib/libfido2.a 348 LIBFORM /usr/lib/libform.a 349 LIBFORMW /usr/lib/libformw.a 350 LIBKEYNOTE /usr/lib/libkeynote.a 351 LIBKVM /usr/lib/libkvm.a 352 LIBL /usr/lib/libl.a 353 LIBM /usr/lib/libm.a 354 LIBMENU /usr/lib/libmenu.a 355 LIBMENUW /usr/lib/libmenuw.a 356 LIBRADIUS /usr/lib/libradius.a 357 LIBOSSAUDIO /usr/lib/libossaudio.a 358 LIBPANEL /usr/lib/libpanel.a 359 LIBPANELW /usr/lib/libpanelw.a 360 LIBPCAP /usr/lib/libpcap.a 361 LIBPERL /usr/lib/libperl.a 362 LIBPTHREAD /usr/lib/libpthread.a 363 LIBRPCSVC /usr/lib/librpcsvc.a 364 LIBSKEY /usr/lib/libskey.a 365 LIBSNDIO /usr/lib/libsndio.a 366 LIBSSL /usr/lib/libssl.a 367 LIBAGENTX /usr/lib/libagentx.a 368 LIBTERMCAP /usr/lib/libtermcap.a 369 LIBTERMLIB /usr/lib/libtermlib.a 370 LIBTLS /usr/lib/libtls.a 371 LIBUSBHID /usr/lib/libusbhid.a 372 LIBUTIL /usr/lib/libutil.a 373 LIBY /usr/lib/liby.a 374 LIBZ /usr/lib/libz.a 375 LIBARCH arch-dependent stuff 376 377STRIP The flag passed to the install program to cause the binary 378 to be stripped. 379 380SUBDIR A list of subdirectories that should be built as well. 381 Each of the targets will execute the same target in the 382 subdirectories. 383 384The include file <bsd.prog.mk> includes the file named "../Makefile.inc" 385if it exists, as well as the include file <bsd.man.mk>. 386 387Some simple examples: 388 389To build foo from foo.c with a manual page foo.1, use: 390 391 PROG= foo 392 393 .include <bsd.prog.mk> 394 395To build foo from foo.c with a manual page foo.2, add the line: 396 397 MAN= foo.2 398 399If foo does not have a manual page at all, add the line: 400 401 NOMAN= noman 402 403If foo has multiple source files, add the line: 404 405 SRCS= a.c b.c c.c d.c 406 407SRCS may contain lex and yacc files, in which case the framework will 408convert these files to C and header files first, before building anything 409else. 410 411SRCS may contain C++ files, in which case the C++ compiler will be used 412for linking. 413 414If YFLAGS contains -d, the header file will be named like the C file, 415and a proper rule tying both together will be generated. For instance, if 416SRCS contains grammar.y, then effectively you will have 417 418grammar.c grammar.h: grammar.y 419 ${YACC.Y} -o grammar.c grammar.y 420 421 422<bsd.prog.mk> provides a limited capability to build several 423programs in a single directory by defining the list of programs 424as PROGS instead of using PROG, for instance: PROGS = foo bar 425 426This only works if all programs in the directory use the same 427compiler and linker flags. Also, the programs cannot use source 428files with the same file name but different content. 429 430Each program of the list, for instance foo, will use SRCS_foo instead 431of SRCS to find its sources. SRCS_foo still defaults to foo.c, and 432MAN still defaults to section 1 manpages: MAN = foo.1 bar.1. 433 434Each program can have its separate LDADD_foo and DPADD_foo definitions. 435If not defined, these default to LDADD/DPADD. 436 437Some simple examples: 438To build foo from foo.c and bar from bar.c with manual pages foo.1 and bar.1: 439 440 PROGS = foo bar 441 442 .include <bsd.prog.mk> 443 444If bar has manual page bar.8 instead, add the line: 445 MAN = foo.1 bar.8 446 447If bar has multiple source files, add the line: 448 SRCS_bar = a.c b.c c.c d.c 449 450Note that foo and bar may share some source files, like so: 451 SRCS_foo = foo.c common.c 452 SRCS_bar = bar.c common.c 453 454=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 455 456The include file <bsd.subdir.mk> contains the default targets for building 457subdirectories. It has the same six targets as <bsd.prog.mk>: all, 458clean, cleandir, includes, install, and tags. For all of 459the directories listed in the variable SUBDIR, the specified directory 460will be visited and the target made. There is also a default target which 461allows the command "make subdir" where subdir is any directory listed in 462the variable SUBDIR. 463 464 465=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 466 467The include file <bsd.lib.mk> has support for building libraries. It has 468the same six targets as <bsd.prog.mk>: all, clean, cleandir, 469includes, install, and tags. It has a limited number of suffixes, 470consistent with the current needs of the BSD tree. 471 472It uses the following variables: 473 474BUILDFIRST/BUILDAFTER 475 See <bsd.prog.mk>. 476 477LIB The name of the library to build. 478 479LIBDIR Target directory for libraries. 480 481LIBGRP Library group. 482 483LIBOWN Library owner. 484 485LIBMODE Library mode. 486 487LDADD Additional linker objects. 488 489MAN The manual pages to be installed (use a .1 - .9 suffix). 490 491SRCS List of source files to build the library. Suffix types 492 .s, .c, and .f are supported. Note, .s files are preferred 493 to .c files of the same name. (This is not the default for 494 POSIX make without bsd.lib.mk). 495 496 The same support for yacc and lex files as <bsd.prog.mk> 497 is provided. 498 499The include file <bsd.lib.mk> includes the file named "../Makefile.inc" 500if it exists, as well as the include file <bsd.man.mk>. 501 502It has rules for building profiled objects; profiled libraries are 503built by default. 504 505Static libraries are ranlib'd when made. 506 507In addition, a reduced version of a library, including just specific 508objects that are compiled with additional options to reduce their 509size may be built. This is used by the distrib/ tree and crunchgen 510when building ramdisks. This sets/uses the following variables: 511 512DIST_LIB The path of the library to build. [lib${LIB}_d.a] 513 514DIST_OBJS The (sub)set of .o files to include in ${DIST_LIB}. [${OBJS}] 515 516DIST_CFLAGS Additional flags for the C compiler and assembler. 517 [-Oz] 518 519