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