bsd.README revision 1.53
1# $NetBSD: bsd.README,v 1.53 1999/11/23 13:22:37 blymn 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 61The following variables that control how things are made/installed that 62are not set by default. These should not be set by Makefiles; they're for 63the user to define in MAKECONF (see bsd.own.mk, below) or on the make(1) 64command line: 65 66BUILD If defined, 'make install' checks that the targets in the 67 source directories are up-to-date and remakes them if they 68 are out of date, instead of blindly trying to install 69 out of date or non-existant targets. 70 71UPDATE If defined, 'make install' only installs targets that are 72 more recently modified in the source directories that their 73 installed counterparts. 74 75UNPRIVILEGED If defined, don't set the owner/group/mode when installing 76 files or directories. This allows a non-root "make install". 77 78MKCATPAGES If "no", don't build or install the catman pages. 79 80MKDOC If "no", don't build or install the documentation. 81 82MKINFO If "no", don't build or install Info documentation from 83 Texinfo source files. 84 85MKLINT If "no", don't build or install the lint libraries. 86 87MKMAN If "no", don't build or install the man or catman pages. 88 Also acts as "MKCATPAGES=no" 89 90MKNLS If "no", don't build or install the NLS files. 91 92MKOBJ If "no", don't create objdirs. 93 94MKPIC If "no", don't build or install shared libraries. 95 96MKPICINSTALL If "no", don't install the *_pic.a libraries. 97 98MKPROFILE If "no", don't build or install the profiling libraries. 99 100MKSHARE If "no", act as "MKCATPAGES=no MKDOC=no MKINFO=no MKMAN=no 101 MKNLS=no". I.e, don't build catman pages, documentation, 102 Info documentation, man pages, NLS files, ... 103 104=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 105 106The include file <sys.mk> has the default rules for all makes, in the BSD 107environment or otherwise. You probably don't want to touch this file. 108 109=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 110 111The include file <bsd.man.mk> handles installing manual pages and their 112links. 113 114It has a two targets: 115 116 maninstall: 117 Install the manual page sources and their links. 118 catinstall: 119 Install the preformatted manual pages and their links. 120 121It sets/uses the following variables: 122 123MANDIR Base path for manual installation. 124 125MANGRP Manual group. 126 127MANOWN Manual owner. 128 129MANMODE Manual mode. 130 131MANSUBDIR Subdirectory under the manual page section, i.e. "/vax" 132 or "/tahoe" for machine specific manual pages. 133 134MAN The manual pages to be installed (use a .1 - .9 suffix). 135 136MLINKS List of manual page links (using a .1 - .9 suffix). The 137 linked-to file must come first, the linked file second, 138 and there may be multiple pairs. The files are soft-linked. 139 140The include file <bsd.man.mk> includes a file named "../Makefile.inc" if 141it exists. 142 143=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 144 145The include file <bsd.own.mk> contains source tree configuration parameters, 146such as the owners, groups, etc. for both manual pages and binaries, and 147a few global "feature configuration" parameters. 148 149It has no targets. 150 151To get system-specific configuration parameters, bsd.own.mk will try to 152include the file specified by the "MAKECONF" variable. If MAKECONF is not 153set, or no such file exists, the system make configuration file, /etc/mk.conf 154is included. These files may define any of the variables described below. 155 156bsd.own.mk sets the following variables, if they are not already defined 157(defaults are in brackets): 158 159BSDSRCDIR The real path to the system sources, so that 'make obj' 160 will work correctly. [/usr/src] 161 162BSDOBJDIR The real path to the system 'obj' tree, so that 'make obj' 163 will work correctly. [/usr/obj] 164 165BINGRP Binary group. [wheel] 166 167BINOWN Binary owner. [root] 168 169BINMODE Binary mode. [555] 170 171NONBINMODE Mode for non-executable files. [444] 172 173MANDIR Base path for manual installation. [/usr/share/man/cat] 174 175MANGRP Manual group. [wheel] 176 177MANOWN Manual owner. [root] 178 179MANMODE Manual mode. [${NONBINMODE}] 180 181MANINSTALL Manual installation type: maninstall, catinstall, or both 182 183LIBDIR Base path for library installation. [/usr/lib] 184 185LINTLIBDIR Base path for lint(1) library installation. [/usr/libdata/lint] 186 187LIBGRP Library group. [${BINGRP}] 188 189LIBOWN Library owner. [${BINOWN}] 190 191LIBMODE Library mode. [${NONBINMODE}] 192 193DOCDIR Base path for system documentation (e.g. PSD, USD, etc.) 194 installation. [/usr/share/doc] 195 196DOCGRP Documentation group. [wheel] 197 198DOCOWN Documentation owner. [root] 199 200DOCMODE Documentation mode. [${NONBINMODE}] 201 202NLSDIR Base path for National Language Support files installation. 203 [/usr/share/nls] 204 205NLSGRP National Language Support files group. [wheel] 206 207NLSOWN National Language Support files owner. [root] 208 209NLSMODE National Language Support files mode. [${NONBINMODE}] 210 211STRIPFLAG The flag passed to the install program to cause the binary 212 to be stripped. This is to be used when building your 213 own install script so that the entire system can be made 214 stripped/not-stripped using a single knob. [-s] 215 216COPY The flag passed to the install program to cause the binary 217 to be copied rather than moved. This is to be used when 218 building our own install script so that the entire system 219 can either be installed with copies, or with moves using 220 a single knob. [-c] 221 222Additionally, the following variables may be set by bsd.own.mk or in a 223make configuration file to modify the behaviour of the system build 224process (default values are in brackets along with comments, if set by 225bsd.own.mk): 226 227CRYPTOBASE Select which cryptography code base to use when building 228 cryptography support into the system. See the 229 bsd.crypto.mk section for more information. 230 231EXPORTABLE_SYSTEM 232 Forces CRYPTOBASE to the value "none" for compatibility 233 with older NetBSD build environments. See the bsd.crypto.mk 234 section for more information. 235 236SKEY Compile in support for S/key authentication. [yes, set 237 unconditionally] 238 239KERBEROS Compile in support for Kerberos 4 authentication. 240 241KERBEROS5 Compile in support for Kerberos 5 authentication. 242 243MANZ Compress manual pages at installation time. 244 245SYS_INCLUDE Copy or symlink kernel include files into /usr/include. 246 Possible values are "symlinks" or "copies" (which is 247 the same as the variable being unset). 248 249NOPROFILE Do not build profiled versions of system libraries 250 251NOPIC Do not build PIC versions of system libraries, and 252 do not build shared libraries. [set if ${MACHINE_ARCH} 253 is "sparc64", unset otherwise.] 254 255NOLINT Do not build lint libraries. 256 257OBJECT_FMT Object file format. [set to "ELF" on architectures that 258 use ELF -- currently if ${MACHINE_ARCH} is "alpha", 259 "mipsel", "mipseb", "powerpc", "sparc", "sparc64", 260 and "i386", or set to "a.out" on other architectures]. 261 262 263bsd.own.mk is generally useful when building your own Makefiles so that 264they use the same default owners etc. as the rest of the tree. 265 266=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 267 268The include file <bsd.prog.mk> handles building programs from one or 269more source files, along with their manual pages. It has a limited number 270of suffixes, consistent with the current needs of the BSD tree. 271 272It has eight targets: 273 274 all: 275 build the program and its manual page 276 clean: 277 remove the program, any object files and the files a.out, 278 Errs, errs, mklog, and ${PROG}.core. 279 cleandir: 280 remove all of the files removed by the target clean, as 281 well as .depend, tags, and any manual pages. 282 `distclean' is a synonym for `cleandir'. 283 depend: 284 make the dependencies for the source files, and store 285 them in the file .depend. 286 includes: 287 install any header files. 288 install: 289 install the program and its manual pages; if the Makefile 290 does not itself define the target install, the targets 291 beforeinstall and afterinstall may also be used to cause 292 actions immediately before and after the install target 293 is executed. 294 lint: 295 run lint on the source files 296 tags: 297 create a tags file for the source files. 298 299It sets/uses the following variables: 300 301BINGRP Binary group. 302 303BINOWN Binary owner. 304 305BINMODE Binary mode. 306 307CLEANFILES Additional files to remove for the clean and cleandir targets. 308 309COPTS Additional flags to the compiler when creating C objects. 310 311CPPFLAGS Additional flags to the C pre-processor 312 313LDADD Additional loader objects. Usually used for libraries. 314 For example, to load with the compatibility and utility 315 libraries, use: 316 317 LDADD+=-lutil -lcompat 318 319LDFLAGS Additional loader flags. 320 321LINKS The list of binary links; should be full pathnames, the 322 linked-to file coming first, followed by the linked 323 file. The files are hard-linked. For example, to link 324 /bin/test and /bin/[, use: 325 326 LINKS= ${DESTDIR}/bin/test ${DESTDIR}/bin/[ 327 328SYMLINKS The list of symbolic links; should be full pathnames. 329 Syntax is identical to LINKS. Note that DESTDIR is not 330 automatically included in the link. 331 332MAN Manual pages (should end in .1 - .9). If no MAN variable is 333 defined, "MAN=${PROG}.1" is assumed. 334 335PROG The name of the program to build. If not supplied, nothing 336 is built. 337 338PROGNAME The name that the above program will be installed as, if 339 different from ${PROG}. 340 341SRCS List of source files to build the program. If SRCS is not 342 defined, it's assumed to be ${PROG}.c. 343 344DPADD Additional dependencies for the program. Usually used for 345 libraries. For example, to depend on the compatibility and 346 utility libraries use: 347 348 DPADD+=${LIBCOMPAT} ${LIBUTIL} 349 350 The following libraries are predefined for DPADD: 351 352 LIBCRT0?= ${DESTDIR}/usr/lib/crt0.o 353 LIBC?= ${DESTDIR}/usr/lib/libc.a 354 LIBC_PIC?= ${DESTDIR}/usr/lib/libc_pic.a 355 LIBCOMPAT?= ${DESTDIR}/usr/lib/libcompat.a 356 LIBCRYPT?= ${DESTDIR}/usr/lib/libcrypt.a 357 LIBCURSES?= ${DESTDIR}/usr/lib/libcurses.a 358 LIBDBM?= ${DESTDIR}/usr/lib/libdbm.a 359 LIBDES?= ${DESTDIR}/usr/lib/libdes.a 360 LIBEDIT?= ${DESTDIR}/usr/lib/libedit.a 361 LIBGCC?= ${DESTDIR}/usr/lib/libgcc.a 362 LIBGNUMALLOC?= ${DESTDIR}/usr/lib/libgnumalloc.a 363 LIBIPSEC?= ${DESTDIR}/usr/lib/libipsec.a 364 LIBKDB?= ${DESTDIR}/usr/lib/libkdb.a 365 LIBKRB?= ${DESTDIR}/usr/lib/libkrb.a 366 LIBKVM?= ${DESTDIR}/usr/lib/libkvm.a 367 LIBL?= ${DESTDIR}/usr/lib/libl.a 368 LIBM?= ${DESTDIR}/usr/lib/libm.a 369 LIBMENU?= ${DESTDIR}/usr/lib/libmenu.a 370 LIBMP?= ${DESTDIR}/usr/lib/libmp.a 371 LIBNTP?= ${DESTDIR}/usr/lib/libntp.a 372 LIBPC?= ${DESTDIR}/usr/lib/libpc.a 373 LIBPCAP?= ${DESTDIR}/usr/lib/libpcap.a 374 LIBPLOT?= ${DESTDIR}/usr/lib/libplot.a 375 LIBPOSIX?= ${DESTDIR}/usr/lib/libposix.a 376 LIBRESOLV?= ${DESTDIR}/usr/lib/libresolv.a 377 LIBRPCSVC?= ${DESTDIR}/usr/lib/librpcsvc.a 378 LIBSKEY?= ${DESTDIR}/usr/lib/libskey.a 379 LIBTERMCAP?= ${DESTDIR}/usr/lib/libtermcap.a 380 LIBTELNET?= ${DESTDIR}/usr/lib/libtelnet.a 381 LIBUTIL?= ${DESTDIR}/usr/lib/libutil.a 382 LIBWRAP?= ${DESTDIR}/usr/lib/libwrap.a 383 LIBY?= ${DESTDIR}/usr/lib/liby.a 384 LIBZ?= ${DESTDIR}/usr/lib/libz.a 385 386 387SHAREDSTRINGS If defined, a new .c.o rule is used that results in shared 388 strings, using xstr(1). Note that this will not work with 389 parallel makes. 390 391STRIP The flag passed to the install program to cause the binary 392 to be stripped. 393 394SUBDIR A list of subdirectories that should be built as well. 395 Each of the targets will execute the same target in the 396 subdirectories. 397 398SCRIPTS A list of interpreter scripts [file.{sh,csh,pl,awk,...}]. 399 These are installed exactly like programs. 400 401SCRIPTSNAME The name that the above program will be installed as, if 402 different from ${SCRIPTS}. These can be further specialized 403 by setting SCRIPTSNAME_<script>. 404 405FILES A list of files to install. The installation is controlled 406 by the FILESNAME, FILESOWN, FILESGRP, FILESMODE, FILESDIR 407 variables that can be further specialized by FILES<VAR>_<file> 408 409The include file <bsd.prog.mk> includes the file named "../Makefile.inc" 410if it exists, as well as the include file <bsd.man.mk>. 411 412Some simple examples: 413 414To build foo from foo.c with a manual page foo.1, use: 415 416 PROG= foo 417 418 .include <bsd.prog.mk> 419 420To build foo from foo.c with a manual page foo.2, add the line: 421 422 MAN= foo.2 423 424If foo does not have a manual page at all, add the line: 425 426 NOMAN= noman 427 428If foo has multiple source files, add the line: 429 430 SRCS= a.c b.c c.c d.c 431 432=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 433 434The include file <bsd.subdir.mk> contains the default targets for building 435subdirectories. It has the same eight targets as <bsd.prog.mk>: all, 436clean, cleandir, depend, includes, install, lint, and tags. For all of 437the directories listed in the variable SUBDIRS, the specified directory 438will be visited and the target made. There is also a default target which 439allows the command "make subdir" where subdir is any directory listed in 440the variable SUBDIRS. 441 442=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 443 444The include file <bsd.links.mk> handles the LINKS and SYMLINKS variables 445and is included from from bsd.lib.mk and bsd.prog.mk. 446 447=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 448 449The include file <bsd.files.mk> handles the FILES variables and is included 450from bsd.lib.mk and bsd.prog.mk. 451 452=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 453 454The include file <bsd.inc.mk> defines the includes target and uses two 455variables: 456 457INCS The list of include files 458 459INCSDIR The location to install the include files. 460 461=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 462 463The include file <bsd.kinc.mk> defines the many targets (includes, 464subdirectories, etc.), and is used by kernel makefiles to handle 465include file installation. It is intended to be included alone, by 466kernel Makefiles. Please see bsd.kinc.mk for more details, and keep 467the documentation in that file up to date. 468 469=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 470 471The include file <bsd.info.mk> is used to generate and install GNU Info 472documentation from respective Texinfo source files. It defines three 473implicit targets (.txi.info, .texi.info, and .texinfo.info), and uses the 474following variables: 475 476TEXINFO List of Texinfo source files. Info documentation will 477 consist of single files with the extension replaced by 478 .info. 479 480INFOFLAGS Flags to pass to makeinfo. [] 481 482INSTALL_INFO Name of install-info program. [install-info] 483 484MAKEINFO Name of makeinfo program. [makeinfo] 485 486=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 487 488The include file <bsd.sys.mk> is used by <bsd.prog.mk> and 489<bsd.lib.mk>. It contains overrides that are used when building 490the NetBSD source tree. For instance, if "PARALLEL" is defined by 491the program/library Makefile, it includes a set of rules for lex and 492yacc that allow multiple lex and yacc targets to be built in parallel. 493 494=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 495 496The include file <bsd.lib.mk> has support for building libraries. It has 497the same eight targets as <bsd.prog.mk>: all, clean, cleandir, depend, 498includes, install, lint, and tags. Additionally, it has a checkver target 499which checks for installed shared object libraries whose version is greater 500that the version of the source. It has a limited number of suffixes, 501consistent with the current needs of the BSD tree. 502 503It sets/uses the following variables: 504 505LIB The name of the library to build. 506 507LIBDIR Target directory for libraries. 508 509LINTLIBDIR Target directory for lint libraries. 510 511LIBGRP Library group. 512 513LIBOWN Library owner. 514 515LIBMODE Library mode. 516 517LDADD Additional loader objects. 518 519MAN The manual pages to be installed (use a .1 - .9 suffix). 520 521MKLINKLIB If "no", act as "MKPICINSTALL=no MKPROFILE=no". 522 Also: 523 - don't install the .a libraries 524 - don't install _pic.a libraries on PIC systems 525 - don't build .a libraries on PIC systems 526 - don't install the .so symlink on ELF systems 527 I.e, only install the shared library (and the .so.major 528 symlink on ELF). 529 530NOCHECKVER_<library> 531NOCHECKVER If set, disables checking for installed shared object 532 libraries with versions greater than the source. A 533 particular library name, without the "lib" prefix, may 534 be appended to the variable name to disable the check for 535 only that library. 536 537SRCS List of source files to build the library. Suffix types 538 .s, .c, and .f are supported. Note, .s files are preferred 539 to .c files of the same name. (This is not the default for 540 versions of make.) 541 542The include file <bsd.lib.mk> includes the file named "../Makefile.inc" 543if it exists, as well as the include file <bsd.man.mk>. 544 545It has rules for building profiled objects; profiled libraries are 546built by default. 547 548Libraries are ranlib'd when made. 549 550=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 551 552The include file <bsd.crypto.mk> contains variables related to building 553cryptography support into the system. 554 555It has no targets. 556 557In order to get system-specific crypto configuration parameters, 558bsd.crypto.mk will include <bsd.own.mk>, which in turn will include 559the configuration file specified by the "MAKECONF" variable. See 560the <bsd.own.mk> section for more information. 561 562bsd.crypto.mk requires the "SRCTOP" variable to be defined before 563inclusion. This variable contains the relative path to the top of 564the source tree, with no trailing '/'. 565 566The variable "CRYPTOBASE" may be set by the user to select which 567cryptography code base will be used when building the system. If 568CRYPTOBASE is set to "none", no cryptography support will be built 569into the system. CRYPTOBASE should be set to the name of the crypto 570sub-tree in the SRCTOP directory. If CRYPTOBASE is not set, 571bsd.crypto.mk will use the following algorithm to set the variable: 572 573 .if exists(${SRCTOP}/crypto-us) 574 CRYPTOBASE=crypto-us 575 .elif exists(${SRCTOP}/crypto-intl) 576 CRYPTOBASE=crypto-intl 577 .else 578 undef CRYPTOBASE 579 .endif 580 581Note that it is legal for the user to set CRYPTOBASE to a relative 582path outside of the source directory. For example: 583 584 CRYPTOPATH= ../cryptosrc-intl/crypto-intl 585 586If CRYPTOBASE is set and not set to "none", bsd.crypto.mk will use 587CRYPTOBASE to set the "CRYPTOPATH" variable. CRYPTOPATH is set to 588the value "${SRCTOP}/${CRYPTOBASE}". 589 590Once CRYPTOPATH is set by bsd.crypto.mk, it checks to see if the 591path actually exists. If it does not exist, the variable is undefined. 592Program and library Makefiles may key off the definition of CRYPTOPATH 593to determine if cryptography support is to be included in that program. 594For example, a typical program Makefile should do the following: 595 596 SRCTOP= ../.. 597 .include <bsd.crypto.mk> 598 599 PROG= login 600 SRCS= login.c 601 . 602 . 603 . 604 .if defined(CRYPTOPATH) 605 .sinclude "${CRYPTOPATH}/usr.bin/login/Makefile.frag" 606 .endif 607 608The Makefile.frag included (if it exists) will now influence the build 609of the login(1) program, specifying additional source files, libraries, 610and CPP flags. 611 612The "EXPORTABLE_SYSTEM" variable, if set, causes CRYPTOBASE to be set 613to "none". This is for compatibilty with older NetBSD build environments. 614 615=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 616