bsd.README revision 1.40
1# $NetBSD: bsd.README,v 1.40 1998/07/22 18:22:35 perry Exp $ 2# @(#)bsd.README 8.2 (Berkeley) 4/2/94 3 4This is the README file for the new make "include" files for the BSD 5source tree. The files are installed in /usr/share/mk, and are, by 6convention, named with the suffix ".mk". 7 8Note, this file is not intended to replace reading through the .mk 9files for anything tricky. 10 11=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 12 13RANDOM THINGS WORTH KNOWING: 14 15The files are simply C-style #include files, and pretty much behave like 16you'd expect. The syntax is slightly different in that a single '.' is 17used instead of the hash mark, i.e. ".include <bsd.prog.mk>". 18 19One difference that will save you lots of debugging time is that inclusion 20of the file is normally done at the *end* of the Makefile. The reason for 21this is because .mk files often modify variables and behavior based on the 22values of variables set in the Makefile. To make this work, remember that 23the FIRST target found is the target that is used, i.e. if the Makefile has: 24 25 a: 26 echo a 27 a: 28 echo a number two 29 30the command "make a" will echo "a". To make things confusing, the SECOND 31variable assignment is the overriding one, i.e. if the Makefile has: 32 33 a= foo 34 a= bar 35 36 b: 37 echo ${a} 38 39the command "make b" will echo "bar". This is for compatibility with the 40way the V7 make behaved. 41 42It's fairly difficult to make the BSD .mk files work when you're building 43multiple programs in a single directory. It's a lot easier split up the 44programs than to deal with the problem. Most of the agony comes from making 45the "obj" directory stuff work right, not because we switched to a new version 46of make. So, don't get mad at us, figure out a better way to handle multiple 47architectures so we can quit using the symbolic link stuff. (Imake doesn't 48count.) 49 50The file .depend in the source directory is expected to contain dependencies 51for the source files. This file is read automatically by make after reading 52the Makefile. 53 54The variable DESTDIR works as before. It's not set anywhere but will change 55the tree where the file gets installed. 56 57The profiled libraries are no longer built in a different directory than 58the regular libraries. A new suffix, ".po", is used to denote a profiled 59object, and ".so" denotes a shared (position-independent) object. 60 61There are two variables that control how things are made/installed that 62are not set by default: 63 64BUILD If set 'make install' checks that the targets in the source 65 directories are up-to-date and remakes them if they 66 are out of date, instead of blindly trying to install 67 out of date or non-existant targets. 68 69UPDATE 'make install' only installs targets that are more recently 70 modified in the source directories that their installed 71 counterparts. 72 73=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 74 75The include file <sys.mk> has the default rules for all makes, in the BSD 76environment or otherwise. You probably don't want to touch this file. 77 78=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 79 80The include file <bsd.man.mk> handles installing manual pages and their 81links. 82 83It has a two targets: 84 85 maninstall: 86 Install the manual page sources and their links. 87 catinstall: 88 Install the preformatted manual pages and their links. 89 90It sets/uses the following variables: 91 92MANDIR Base path for manual installation. 93 94MANGRP Manual group. 95 96MANOWN Manual owner. 97 98MANMODE Manual mode. 99 100MANSUBDIR Subdirectory under the manual page section, i.e. "/vax" 101 or "/tahoe" for machine specific manual pages. 102 103MAN The manual pages to be installed (use a .1 - .9 suffix). 104 105MLINKS List of manual page links (using a .1 - .9 suffix). The 106 linked-to file must come first, the linked file second, 107 and there may be multiple pairs. The files are soft-linked. 108 109The include file <bsd.man.mk> includes a file named "../Makefile.inc" if 110it exists. 111 112=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 113 114The include file <bsd.own.mk> contains source tree configuration parameters, 115such as the owners, groups, etc. for both manual pages and binaries, and 116a few global "feature configuration" parameters. 117 118It has no targets. 119 120To get system-specific configuration parameters, bsd.own.mk will try to 121include the file specified by the "MAKECONF" variable. If MAKECONF is not 122set, or no such file exists, the system make configuration file, /etc/mk.conf 123is included. These files may define any of the variables described below. 124 125bsd.own.mk sets the following variables, if they are not already defined 126(defaults are in brackets): 127 128 129 130BSDSRCDIR The real path to the system sources, so that 'make obj' 131 will work correctly. [/usr/src] 132 133BSDOBJDIR The real path to the system 'obj' tree, so that 'make obj' 134 will work correctly. [/usr/obj] 135 136BINGRP Binary group. [wheel] 137 138BINOWN Binary owner. [root] 139 140BINMODE Binary mode. [555] 141 142NONBINMODE Mode for non-executable files. [444] 143 144MANDIR Base path for manual installation. [/usr/share/man/cat] 145 146MANGRP Manual group. [wheel] 147 148MANOWN Manual owner. [root] 149 150MANMODE Manual mode. [${NONBINMODE}] 151 152MANINSTALL Manual installation type: maninstall, catinstall, or both 153 154LIBDIR Base path for library installation. [/usr/lib] 155 156LINTLIBDIR Base path for lint(1) library installation. [/usr/libdata/lint] 157 158LIBGRP Library group. [${BINGRP}] 159 160LIBOWN Library owner. [${BINOWN}] 161 162LIBMODE Library mode. [${NONBINMODE}] 163 164DOCDIR Base path for system documentation (e.g. PSD, USD, etc.) 165 installation. [/usr/share/doc] 166 167DOCGRP Documentation group. [wheel] 168 169DOCOWN Documentation owner. [root] 170 171DOCMODE Documentation mode. [${NONBINMODE}] 172 173NLSDIR Base path for National Language Support files installation. 174 [/usr/share/nls] 175 176NLSGRP National Language Support files group. [wheel] 177 178NLSOWN National Language Support files owner. [root] 179 180NLSMODE National Language Support files mode. [${NONBINMODE}] 181 182STRIPFLAG The flag passed to the install program to cause the binary 183 to be stripped. This is to be used when building your 184 own install script so that the entire system can be made 185 stripped/not-stripped using a single knob. [-s] 186 187COPY The flag passed to the install program to cause the binary 188 to be copied rather than moved. This is to be used when 189 building our own install script so that the entire system 190 can either be installed with copies, or with moves using 191 a single knob. [-c] 192 193Additionally, the following variables may be set by bsd.own.mk or in a 194make configuration file to modify the behaviour of the system build 195process (default values are in brackets along with comments, if set by 196bsd.own.mk): 197 198EXPORTABLE_SYSTEM 199 Do not build /usr/src/domestic, even if it is present. 200 201SKEY Compile in support for S/key authentication. [yes, set 202 unconditionally] 203 204KERBEROS Compile in support for Kerberos 4 authentication. 205 206KERBEROS5 Compile in support for Kerberos 5 authentication. 207 208MANZ Compress manual pages at installation time. 209 210SYS_INCLUDE Copy or symlink kernel include files into /usr/include. 211 Possible values are "symlinks" or "copies" (which is 212 the same as the variable being unset). 213 214NOPROFILE Do not build profiled versions of system libraries 215 216NOPIC Do not build PIC versions of system libraries, and 217 do not build shared libraries. [set if ${MACHINE_ARCH} 218 is "vax" "powerpc", unset otherwise.] 219 220NOLINT Do not build lint libraries. 221 222NOSHLIB Do not build shared libraries [set if ${MACHINE_ARCH} 223 is "powerpc", unset otherwise]. 224 225OBJECT_FMT Object file format. [set to "ELF" on ports that use 226 ELF -- currently if ${MACHINE_ARCH} is "alpha", "mips" 227 or "powerpc" or set to "a.out" on other ports]. 228 229 230bsd.own.mk is generally useful when building your own Makefiles so that 231they use the same default owners etc. as the rest of the tree. 232 233=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 234 235The include file <bsd.prog.mk> handles building programs from one or 236more source files, along with their manual pages. It has a limited number 237of suffixes, consistent with the current needs of the BSD tree. 238 239It has eight targets: 240 241 all: 242 build the program and its manual page 243 clean: 244 remove the program, any object files and the files a.out, 245 Errs, errs, mklog, and ${PROG}.core. 246 cleandir: 247 remove all of the files removed by the target clean, as 248 well as .depend, tags, and any manual pages. 249 depend: 250 make the dependencies for the source files, and store 251 them in the file .depend. 252 includes: 253 install any header files. 254 install: 255 install the program and its manual pages; if the Makefile 256 does not itself define the target install, the targets 257 beforeinstall and afterinstall may also be used to cause 258 actions immediately before and after the install target 259 is executed. 260 lint: 261 run lint on the source files 262 tags: 263 create a tags file for the source files. 264 265It sets/uses the following variables: 266 267BINGRP Binary group. 268 269BINOWN Binary owner. 270 271BINMODE Binary mode. 272 273CLEANFILES Additional files to remove for the clean and cleandir targets. 274 275COPTS Additional flags to the compiler when creating C objects. 276 277CPPFLAGS Additional flags to the C pre-processor 278 279LDADD Additional loader objects. Usually used for libraries. 280 For example, to load with the compatibility and utility 281 libraries, use: 282 283 LDADD+=-lutil -lcompat 284 285LDFLAGS Additional loader flags. 286 287LINKS The list of binary links; should be full pathnames, the 288 linked-to file coming first, followed by the linked 289 file. The files are hard-linked. For example, to link 290 /bin/test and /bin/[, use: 291 292 LINKS= ${DESTDIR}/bin/test ${DESTDIR}/bin/[ 293 294SYMLINKS The list of symbolic links; should be full pathnames. 295 Syntax is identical to LINKS. Note that DESTDIR is not 296 automatically included in the link. 297 298MAN Manual pages (should end in .1 - .9). If no MAN variable is 299 defined, "MAN=${PROG}.1" is assumed. 300 301PROG The name of the program to build. If not supplied, nothing 302 is built. 303 304PROGNAME The name that the above program will be installed as, if 305 different from ${PROG}. 306 307SRCS List of source files to build the program. If SRCS is not 308 defined, it's assumed to be ${PROG}.c. 309 310DPADD Additional dependencies for the program. Usually used for 311 libraries. For example, to depend on the compatibility and 312 utility libraries use: 313 314 DPADD+=${LIBCOMPAT} ${LIBUTIL} 315 316 The following libraries are predefined for DPADD: 317 318 LIBCRT0?= ${DESTDIR}/usr/lib/crt0.o 319 LIBC?= ${DESTDIR}/usr/lib/libc.a 320 LIBC_PIC?= ${DESTDIR}/usr/lib/libc_pic.a 321 LIBCOMPAT?= ${DESTDIR}/usr/lib/libcompat.a 322 LIBCRYPT?= ${DESTDIR}/usr/lib/libcrypt.a 323 LIBCURSES?= ${DESTDIR}/usr/lib/libcurses.a 324 LIBDBM?= ${DESTDIR}/usr/lib/libdbm.a 325 LIBDES?= ${DESTDIR}/usr/lib/libdes.a 326 LIBEDIT?= ${DESTDIR}/usr/lib/libedit.a 327 LIBGCC?= ${DESTDIR}/usr/lib/libgcc.a 328 LIBGNUMALLOC?= ${DESTDIR}/usr/lib/libgnumalloc.a 329 LIBKDB?= ${DESTDIR}/usr/lib/libkdb.a 330 LIBKRB?= ${DESTDIR}/usr/lib/libkrb.a 331 LIBKVM?= ${DESTDIR}/usr/lib/libkvm.a 332 LIBL?= ${DESTDIR}/usr/lib/libl.a 333 LIBM?= ${DESTDIR}/usr/lib/libm.a 334 LIBMP?= ${DESTDIR}/usr/lib/libmp.a 335 LIBNTP?= ${DESTDIR}/usr/lib/libntp.a 336 LIBPC?= ${DESTDIR}/usr/lib/libpc.a 337 LIBPCAP?= ${DESTDIR}/usr/lib/libpcap.a 338 LIBPLOT?= ${DESTDIR}/usr/lib/libplot.a 339 LIBPOSIX?= ${DESTDIR}/usr/lib/libposix.a 340 LIBRESOLV?= ${DESTDIR}/usr/lib/libresolv.a 341 LIBRPCSVC?= ${DESTDIR}/usr/lib/librpcsvc.a 342 LIBSKEY?= ${DESTDIR}/usr/lib/libskey.a 343 LIBTERMCAP?= ${DESTDIR}/usr/lib/libtermcap.a 344 LIBTELNET?= ${DESTDIR}/usr/lib/libtelnet.a 345 LIBUTIL?= ${DESTDIR}/usr/lib/libutil.a 346 LIBWRAP?= ${DESTDIR}/usr/lib/libwrap.a 347 LIBY?= ${DESTDIR}/usr/lib/liby.a 348 LIBZ?= ${DESTDIR}/usr/lib/libz.a 349 350 351SHAREDSTRINGS If defined, a new .c.o rule is used that results in shared 352 strings, using xstr(1). Note that this will not work with 353 parallel makes. 354 355STRIP The flag passed to the install program to cause the binary 356 to be stripped. 357 358SUBDIR A list of subdirectories that should be built as well. 359 Each of the targets will execute the same target in the 360 subdirectories. 361 362SCRIPTS A list of interpreter scripts [file.{sh,csh,pl,awk,...}]. 363 These are installed exactly like programs. 364 365SCRIPTSNAME The name that the above program will be installed as, if 366 different from ${SCRIPTS}. These can be further specialized 367 by setting SCRIPTSNAME_<script>. 368 369FILES A list of files to install. The installation is controlled 370 by the FILESNAME, FILESOWN, FILESGRP, FILESMODE, FILESDIR 371 variables that can be further specialized by FILES<VAR>_<file> 372 373The include file <bsd.prog.mk> includes the file named "../Makefile.inc" 374if it exists, as well as the include file <bsd.man.mk>. 375 376Some simple examples: 377 378To build foo from foo.c with a manual page foo.1, use: 379 380 PROG= foo 381 382 .include <bsd.prog.mk> 383 384To build foo from foo.c with a manual page foo.2, add the line: 385 386 MAN= foo.2 387 388If foo does not have a manual page at all, add the line: 389 390 NOMAN= noman 391 392If foo has multiple source files, add the line: 393 394 SRCS= a.c b.c c.c d.c 395 396=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 397 398The include file <bsd.subdir.mk> contains the default targets for building 399subdirectories. It has the same eight targets as <bsd.prog.mk>: all, 400clean, cleandir, depend, includes, install, lint, and tags. For all of 401the directories listed in the variable SUBDIRS, the specified directory 402will be visited and the target made. There is also a default target which 403allows the command "make subdir" where subdir is any directory listed in 404the variable SUBDIRS. 405 406=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 407 408The include file <bsd.links.mk> handles the LINKS and SYMLINKS variables 409and is included from from bsd.lib.mk and bsd.prog.mk. 410 411=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 412 413The include file <bsd.files.mk> handles the FILES variables and is included 414from bsd.lib.mk and bsd.prog.mk. 415 416=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 417 418The include file <bsd.inc.mk> defines the includes target and uses two 419variables: 420 421INCS The list of include files 422 423INCSDIR The location to install the include files. 424 425=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 426 427The include file <bsd.kinc.mk> defines the many targets (includes, 428subdirectories, etc.), and is used by kernel makefiles to handle 429include file installation. It is intended to be included alone, by 430kernel Makefiles. Please see bsd.kinc.mk for more details, and keep 431the documentation in that file up to date. 432 433=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 434 435The include file <bsd.sys.mk> is used by <bsd.prog.mk> and 436<bsd.lib.mk>. It contains overrides that are used when building 437the NetBSD source tree. For instance, if "PARALLEL" is defined by 438the program/library Makefile, it includes a set of rules for lex and 439yacc that allow multiple lex and yacc targets to be built in parallel. 440 441=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 442 443The include file <bsd.lib.mk> has support for building libraries. It has 444the same eight targets as <bsd.prog.mk>: all, clean, cleandir, depend, 445includes, install, lint, and tags. It has a limited number of suffixes, 446consistent with the current needs of the BSD tree. 447 448It sets/uses the following variables: 449 450LIB The name of the library to build. 451 452LIBDIR Target directory for libraries. 453 454LINTLIBDIR Target directory for lint libraries. 455 456LIBGRP Library group. 457 458LIBOWN Library owner. 459 460LIBMODE Library mode. 461 462LDADD Additional loader objects. 463 464MAN The manual pages to be installed (use a .1 - .9 suffix). 465 466SRCS List of source files to build the library. Suffix types 467 .s, .c, and .f are supported. Note, .s files are preferred 468 to .c files of the same name. (This is not the default for 469 versions of make.) 470 471The include file <bsd.lib.mk> includes the file named "../Makefile.inc" 472if it exists, as well as the include file <bsd.man.mk>. 473 474It has rules for building profiled objects; profiled libraries are 475built by default. 476 477Libraries are ranlib'd when made. 478 479=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 480 481The include file <bsd.port.mk> is used in the FreeBSD ports system. 482Various common definitions for use in the FreeBSD ports are specified 483here. The only main changes between the NetBSD version and the 484original FreeBSD version are that some NetBSD paths have been 485changed (PORTSDIR is now /usr/pkgsrc, rather than the /usr/ports 486directory used in FreeBSD, and PREFIX is now /usr/pkg, rather than 487/usr/local directory used in FreeBSD). 488 489=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 490 491The include file <bsd.port.subdir.mk> is used in the FreeBSD ports 492system, and controls the sub-directory usage in the system. Once 493again, the only change is the PORTSDIR veriable (now /usr/pkgsrc 494rather than the /usr/ports used in FreeBSD). 495