1# $OpenBSD: bsd.README,v 1.59 2014/10/31 13:46:17 jsing 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.nls.mk - National Language Support 13bsd.obj.mk - creating 'obj' directories and cleaning up 14bsd.own.mk - define common variables 15bsd.port.mk - building ports 16bsd.port.arch.mk - glue for building ports with MD stuff 17bsd.port.subdir.mk - targets for building subdirectories for ports 18bsd.prog.mk - building programs from source files 19bsd.regress.mk - regression tests 20bsd.subdir.mk - targets for building subdirectories 21bsd.sys.mk - building bsd from the source tree 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 84The file .depend in the source directory is expected to contain dependencies 85for the source files. This file is read automatically by make after reading 86the Makefile. 87 88The variable DESTDIR works as before. It's not set anywhere but will change 89the tree where the file gets installed. 90 91The profiled libraries are no longer built in a different directory than 92the regular libraries. A new suffix, ".po", is used to denote a profiled 93object. 94 95=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 96 97The include file <sys.mk> has the default rules for all makes, in the BSD 98environment or otherwise. You probably don't want to touch this file. 99 100=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 101 102The include file <bsd.man.mk> handles installing manual pages and their 103links. 104 105It has a single target: 106 107 maninstall: 108 Install the manual pages and their links. 109 110It sets/uses the following variables: 111 112MANDIR Base path for manual installation. 113 114MANGRP Manual group. 115 116MANOWN Manual owner. 117 118MANMODE Manual mode. 119 120MANSUBDIR Subdirectory under the manual page section, i.e. "vax" 121 or "tahoe" for machine specific manual pages. 122 123MAN The manual pages to be installed (use a .1 - .9 suffix). 124 125MLINKS List of manual page links (using a .1 - .9 suffix). The 126 linked-to file must come first, the linked file second, 127 and there may be multiple pairs. The files are soft-linked. 128 129BEFOREMAN List of extra targets that must be already built before the 130 man target can be run. Those targets must be real files (and 131 not .PHONY targets). 132 133The include file <bsd.man.mk> includes a file named "../Makefile.inc" if 134it exists. 135 136=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 137 138The include file <bsd.own.mk> contains source tree configuration parameters, 139such as the owners, groups, etc. for both manual pages and binaries, and 140a few global "feature configuration" parameters. 141 142It has no targets. 143 144To get system-specific configuration parameters, bsd.own.mk will try to 145include the file specified by the "MAKECONF" variable. If MAKECONF is not 146set, or no such file exists, the system make configuration file, /etc/mk.conf 147is included. These files may define any of the variables described below. 148 149bsd.own.mk sets the following variables, if they are not already defined 150(defaults are in brackets): 151 152BSDSRCDIR The real path to the system sources, so that 'make obj' 153 will work correctly. [/usr/src] 154 155BSDOBJDIR The real path to the system 'obj' tree, so that 'make obj' 156 will work correctly. [/usr/obj] 157 158BINGRP Binary group. [bin] 159 160BINOWN Binary owner. [root] 161 162BINMODE Binary mode. [555] 163 164NONBINMODE Mode for non-executable files. [444] 165 166DIRMODE Mode for new directories. [755] 167 168MANDIR Base path for manual installation. [/usr/share/man/man] 169 170MANGRP Manual group. [bin] 171 172MANOWN Manual owner. [root] 173 174MANMODE Manual mode. [${NONBINMODE}] 175 176LIBDIR Base path for library installation. [/usr/lib] 177 178LIBGRP Library group. [${BINGRP}] 179 180LIBOWN Library owner. [${BINOWN}] 181 182LIBMODE Library mode. [${NONBINMODE}] 183 184DOCDIR Base path for system documentation 185 installation. [/usr/share/doc] 186 187DOCGRP Documentation group. [bin] 188 189DOCOWN Documentation owner. [root] 190 191DOCMODE Documentation mode. [${NONBINMODE}] 192 193NLSDIR Base path for National Language Support files installation. 194 [/usr/share/nls] 195 196NLSGRP National Language Support files group. [bin] 197 198NLSOWN National Language Support files owner. [root] 199 200NLSMODE National Language Support files 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 238DEBUGLIBS Create libraries with -g debug information, and install 239 them in /usr/lib/debug. 240 241WARNINGS Adds appropriate warning flags (defined in CDIAGFLAGS, 242 e.g., -Wall...) to compiles. [no] 243 244SUDO Command to run when doing "make install" portion of 245 "make build". If set to sudo, this allows one to run 246 "make build" as a user other than root (assuming sudo 247 is setup for that user). 248 249PIPE If set to "-pipe" gcc will be given the -pipe option 250 which can speed up compiles on machines with memory 251 to spare. Instead of using temp files, gcc uses pipes 252 for the temporary data. 253 254GLOBAL_AUTOCONF_CACHE 255 Set to the name of a file that all cached GNU autoconf 256 test results will be saved in. Reduces redundant tests. 257 Be careful! Redundant tests may not be redundant if you 258 are installing substantially updated gnu programs. 259 260bsd.own.mk is generally useful when building your own Makefiles so that 261they use the same default owners etc. as the rest of the tree. 262 263=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 264 265The include file <bsd.prog.mk> handles building programs from one or 266more source files, along with their manual pages. It has a limited number 267of suffixes, consistent with the current needs of the BSD tree. 268 269It has seven targets: 270 271 all: 272 build the program and its manual page 273 clean: 274 remove the program, any object files and the files a.out, 275 Errs, errs, mklog, and core. 276 cleandir: 277 remove all of the files removed by the target clean, as 278 well as .depend, tags, and any manual pages. 279 depend: 280 make the dependencies for the source files, and store 281 them in the file .depend. 282 includes: 283 install any header files. 284 install: 285 install the program and its manual pages; if the Makefile 286 does not itself define the target install, the targets 287 beforeinstall and afterinstall may also be used to cause 288 actions immediately before and after the install target 289 is executed. 290 tags: 291 create a tags file for the source files. 292 293It sets/uses the following variables: 294 295BINGRP Binary group. 296 297BINOWN Binary owner. 298 299BINMODE Binary mode. 300 301CLEANFILES Additional files to remove for the clean and cleandir targets. 302 303COPTS Additional flags to the compiler when creating C objects. 304 305LDADD Additional loader objects. Usually used for libraries. 306 For example, to load with the crypto and utility 307 libraries, use: 308 309 LDADD+=-lutil -lcrypto 310 311LDFLAGS Additional loader flags. 312 313LINKS The list of binary links; should be full pathnames, the 314 linked-to file coming first, followed by the linked 315 file. The files are hard-linked. For example, to link 316 /bin/test and /bin/[, use: 317 318 LINKS= ${DESTDIR}/bin/test ${DESTDIR}/bin/[ 319 320MAN Manual pages (should end in .1 - .9). If no MAN variable is 321 defined, "MAN=${PROG}.1" is assumed. 322 323PROG The name of the program to build. If not supplied, nothing 324 is built. 325 326SRCS List of source files to build the program. If it's not 327 defined, it's assumed to be ${PROG}.c. 328 329DPADD Additional dependencies for the program. Usually used for 330 libraries. For example, to depend on the crypto and 331 utility libraries use: 332 333 DPADD+=${LIBCRYPTO} ${LIBUTIL} 334 335 The following libraries are predefined for DPADD: 336 337 LIBC /usr/lib/libc.a 338 LIBCRYPTO /usr/lib/libcrypto.a 339 LIBCURSES /usr/lib/libcurses.a 340 LIBEDIT /usr/lib/libedit.a 341 LIBEVENT /usr/lib/libevent.a 342 LIBEXPAT /usr/lib/libexpat.a 343 LIBFORM /usr/lib/libform.a 344 LIBFORMW /usr/lib/libformw.a 345 LIBKEYNOTE /usr/lib/libkeynote.a 346 LIBKVM /usr/lib/libkvm.a 347 LIBL /usr/lib/libl.a 348 LIBM /usr/lib/libm.a 349 LIBMENU /usr/lib/libmenu.a 350 LIBMENUW /usr/lib/libmenuw.a 351 LIBOLDCURSES /usr/lib/libocurses.a 352 LIBOSSAUDIO /usr/lib/libossaudio.a 353 LIBPANEL /usr/lib/libpanel.a 354 LIBPANELW /usr/lib/libpanelw.a 355 LIBPCAP /usr/lib/libpcap.a 356 LIBPERL /usr/lib/libperl.a 357 LIBPTHREAD /usr/lib/libpthread.a 358 LIBRPCSVC /usr/lib/librpcsvc.a 359 LIBSKEY /usr/lib/libskey.a 360 LIBSNDIO /usr/lib/libsndio.a 361 LIBSSL /usr/lib/libssl.a 362 LIBTERMCAP /usr/lib/libtermcap.a 363 LIBTERMLIB /usr/lib/libtermlib.a 364 LIBTLS /usr/lib/libtls.a 365 LIBUSB /usr/lib/libusbhid.a 366 LIBUTIL /usr/lib/libutil.a 367 LIBY /usr/lib/liby.a 368 LIBZ /usr/lib/libz.a 369 LIBARCH arch-dependent stuff 370 371STRIP The flag passed to the install program to cause the binary 372 to be stripped. 373 374SUBDIR A list of subdirectories that should be built as well. 375 Each of the targets will execute the same target in the 376 subdirectories. 377 378The include file <bsd.prog.mk> includes the file named "../Makefile.inc" 379if it exists, as well as the include file <bsd.man.mk>. 380 381Some simple examples: 382 383To build foo from foo.c with a manual page foo.1, use: 384 385 PROG= foo 386 387 .include <bsd.prog.mk> 388 389To build foo from foo.c with a manual page foo.2, add the line: 390 391 MAN= foo.2 392 393If foo does not have a manual page at all, add the line: 394 395 NOMAN= noman 396 397If foo has multiple source files, add the line: 398 399 SRCS= a.c b.c c.c d.c 400 401=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 402 403The include file <bsd.subdir.mk> contains the default targets for building 404subdirectories. It has the same seven targets as <bsd.prog.mk>: all, 405clean, cleandir, depend, includes, install, and tags. For all of 406the directories listed in the variable SUBDIR, the specified directory 407will be visited and the target made. There is also a default target which 408allows the command "make subdir" where subdir is any directory listed in 409the variable SUBDIR. 410 411=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 412 413The include file <bsd.sys.mk> is used by <bsd.prog.mk> and 414<bsd.lib.mk>. It contains overrides that are used when building 415the OpenBSD source tree. For instance, if "PARALLEL" is defined by 416the program/library Makefile, it includes a set of rules for lex and 417yacc that allow multiple lex and yacc targets to be built in parallel. 418 419=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 420 421The include file <bsd.lib.mk> has support for building libraries. It has 422the same seven targets as <bsd.prog.mk>: all, clean, cleandir, depend, 423includes, install, and tags. It has a limited number of suffixes, 424consistent with the current needs of the BSD tree. 425 426It sets/uses the following variables: 427 428LIB The name of the library to build. 429 430LIBDIR Target directory for libraries. 431 432LIBGRP Library group. 433 434LIBOWN Library owner. 435 436LIBMODE Library mode. 437 438LDADD Additional loader objects. 439 440MAN The manual pages to be installed (use a .1 - .9 suffix). 441 442SRCS List of source files to build the library. Suffix types 443 .s, .c, and .f are supported. Note, .s files are preferred 444 to .c files of the same name. (This is not the default for 445 versions of make.) 446 447The include file <bsd.lib.mk> includes the file named "../Makefile.inc" 448if it exists, as well as the include file <bsd.man.mk>. 449 450It has rules for building profiled objects; profiled libraries are 451built by default. 452 453Libraries are ranlib'd when made. 454 455In addition, a reduced version of a library, including just specific 456objects that are compiled with additional options to reduce their 457size may be built. This is used by the distrib/ tree and crunchgen 458when building ramdisks. This sets/uses the following variables: 459 460DIST_LIB The path of the library to build. [lib${LIB}_d.a] 461 462DIST_OBJS The (sub)set of .o files to include in ${DIST_LIB}. [${OBJS}] 463 464DIST_CFLAGS Additional flags for the C compiler and assembler. 465 [-Os] 466 467