1# $NetBSD: bsd.README,v 1.17 1996/04/13 02:08:08 thorpej Exp $ 2# @(#)bsd.README 5.1 (Berkeley) 5/11/90 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 switch 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. 60 61=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 62 63The include file <sys.mk> has the default rules for all makes, in the BSD 64environment or otherwise. You probably don't want to touch this file. 65 66=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 67 68The include file <bsd.man.mk> handles installing manual pages and their 69links. 70 71It has a single target: 72 73 maninstall: 74 Install the manual pages and their links. 75 76It sets/uses the following variables: 77 78MANDIR Base path for manual installation. 79 80MANGRP Manual group. 81 82MANOWN Manual owner. 83 84MANMODE Manual mode. 85 86MANSUBDIR Subdirectory under the manual page section, i.e. "/vax" 87 or "/tahoe" for machine specific manual pages. 88 89MAN The manual pages to be installed (use a .1 - .9 suffix). 90 91MLINKS List of manual page links (using a .1 - .9 suffix). The 92 linked-to file must come first, the linked file second, 93 and there may be multiple pairs. The files are soft-linked. 94 95The include file <bsd.man.mk> includes a file named "../Makefile.inc" if 96it exists. 97 98=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 99 100The include file <bsd.own.mk> contains source tree configuration parameters, 101such as the owners, groups, etc. for both manual pages and binaries, and 102a few global "feature configuration" parameters. 103 104It has no targets. 105 106To get system-specific configuration parameters, bsd.own.mk will try to 107include the file specified by the "MAKECONF" variable. If MAKECONF is not 108set, or no such file exists, the system make configuration file, /etc/mk.conf 109is included. These files may define any of the variables described below. 110 111bsd.own.mk sets the following variables, if they are not already defined 112(defaults are in brackets): 113 114BSDSRCDIR The real path to the system sources, so that 'make obj' 115 will work correctly. [/usr/src] 116 117BSDOBJDIR The real path to the system 'obj' tree, so that 'make obj' 118 will work correctly. [/usr/obj] 119 120BINGRP Binary group. [bin] 121 122BINOWN Binary owner. [bin] 123 124BINMODE Binary mode. [555] 125 126NONBINMODE Mode for non-executable files. [444] 127 128MANDIR Base path for manual installation. [/usr/share/man/cat] 129 130MANGRP Manual group. [bin] 131 132MANOWN Manual owner. [bin] 133 134MANMODE Manual mode. [${NONBINMODE}] 135 136LIBDIR Base path for library installation. [/usr/lib] 137 138LINTLIBDIR Base path for lint(1) library installation. [/usr/libdata/lint] 139 140LIBGRP Library group. [${BINGRP}] 141 142LIBOWN Library owner. [${BINOWN}] 143 144LIBMODE Library mode. [${NONBINMODE}] 145 146DOCDIR Base path for system documentation (e.g. PSD, USD, etc.) 147 installation. [/usr/share/doc] 148 149DOCGRP Documentation group. [bin] 150 151DOCOWN Documentation owner. [bin] 152 153DOCMODE Documentation mode. [${NONBINMODE}] 154 155NLSDIR Base path for National Language Support files installation. 156 [/usr/share/nls] 157 158NLSGRP National Language Support files group. [bin] 159 160NLSOWN National Language Support files owner. [bin] 161 162NLSMODE National Language Support files mode. [${NONBINMODE}] 163 164STRIP The flag passed to the install program to cause the binary 165 to be stripped. This is to be used when building your 166 own install script so that the entire system can be made 167 stripped/not-stripped using a single knob. [-s] 168 169COPY The flag passed to the install program to cause the binary 170 to be copied rather than moved. This is to be used when 171 building our own install script so that the entire system 172 can either be installed with copies, or with moves using 173 a single knob. [-c] 174 175Additionally, the following variables may be set by bsd.own.mk or in a 176make configuration file to modify the behaviour of the system build 177process (default values are in brackets along with comments, if set by 178bsd.own.mk): 179 180EXPORTABLE_SYSTEM 181 Do not build /usr/src/domestic, even if it is present. 182 183SKEY Compile in support for S/key authentication. [yes, set 184 unconditionally] 185 186KERBEROS Compile in support for Kerberos 4 authentication. 187 188KERBEROS5 Compile in support for Kerberos 5 authentication. 189 190MANZ Compress manual pages at installation time. 191 192SYS_INCLUDE Copy or symlink kernel include files into /usr/include. 193 Possible values are "symlinks" or "copies" (which is 194 the same as the variable being unset). 195 196NOPROFILE Do not build profiled versions of system libraries 197 198NOPIC Do not build PIC versions of system libraries, and 199 do not build shared libraries. [set if ${MACHINE_ARCH} 200 is "mips", "vax", or "alpha", unset otherwise.] 201 202NOLINT Do not build lint libraries. [set, set unconditionally] 203 204bsd.own.mk is generally useful when building your own Makefiles so that 205they use the same default owners etc. as the rest of the tree. 206 207=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 208 209The include file <bsd.prog.mk> handles building programs from one or 210more source files, along with their manual pages. It has a limited number 211of suffixes, consistent with the current needs of the BSD tree. 212 213It has eight targets: 214 215 all: 216 build the program and its manual page 217 clean: 218 remove the program, any object files and the files a.out, 219 Errs, errs, mklog, and core. 220 cleandir: 221 remove all of the files removed by the target clean, as 222 well as .depend, tags, and any manual pages. 223 depend: 224 make the dependencies for the source files, and store 225 them in the file .depend. 226 includes: 227 install any header files. 228 install: 229 install the program and its manual pages; if the Makefile 230 does not itself define the target install, the targets 231 beforeinstall and afterinstall may also be used to cause 232 actions immediately before and after the install target 233 is executed. 234 lint: 235 run lint on the source files 236 tags: 237 create a tags file for the source files. 238 239It sets/uses the following variables: 240 241BINGRP Binary group. 242 243BINOWN Binary owner. 244 245BINMODE Binary mode. 246 247CLEANFILES Additional files to remove for the clean and cleandir targets. 248 249COPTS Additional flags to the compiler when creating C objects. 250 251HIDEGAME If HIDEGAME is defined, the binary is installed in 252 /usr/games/hide, and a symbolic link is created to 253 /usr/games/dm. 254 255LDADD Additional loader objects. Usually used for libraries. 256 For example, to load with the compatibility and utility 257 libraries, use: 258 259 LDADD+=-lutil -lcompat 260 261LDFLAGS Additional loader flags. 262 263LINKS The list of binary links; should be full pathnames, the 264 linked-to file coming first, followed by the linked 265 file. The files are hard-linked. For example, to link 266 /bin/test and /bin/[, use: 267 268 LINKS= ${DESTDIR}/bin/test ${DESTDIR}/bin/[ 269 270MAN Manual pages (should end in .1 - .9). If no MAN variable is 271 defined, "MAN=${PROG}.1" is assumed. 272 273PROG The name of the program to build. If not supplied, nothing 274 is built. 275 276SRCS List of source files to build the program. If PROG is not 277 defined, it's assumed to be ${PROG}.c. 278 279DPADD Additional dependencies for the program. Usually used for 280 libraries. For example, to depend on the compatibility and 281 utility libraries use: 282 283 DPADD+=${LIBCOMPAT} ${LIBUTIL} 284 285 The following libraries are predefined for DPADD: 286 287 LIBC /lib/libc.a 288 LIBCOMPAT /usr/lib/libcompat.a 289 LIBCRYPT /usr/lib/libcrypt.a 290 LIBCURSES /usr/lib/libcurses.a 291 LIBDBM /usr/lib/libdbm.a 292 LIBDES /usr/lib/libdes.a 293 LIBL /usr/lib/libl.a 294 LIBKDB /usr/lib/libkdb.a 295 LIBKRB /usr/lib/libkrb.a 296 LIBKVM /usr/lib/libkvm.a 297 LIBM /usr/lib/libm.a 298 LIBMP /usr/lib/libmp.a 299 LIBPC /usr/lib/libpc.a 300 LIBPLOT /usr/lib/libplot.a 301 LIBRPC /usr/lib/sunrpc.a 302 LIBTERM /usr/lib/libterm.a 303 LIBUTIL /usr/lib/libutil.a 304 305SHAREDSTRINGS If defined, a new .c.o rule is used that results in shared 306 strings, using xstr(1). Note that this will not work with 307 parallel makes. 308 309STRIP The flag passed to the install program to cause the binary 310 to be stripped. 311 312SUBDIR A list of subdirectories that should be built as well. 313 Each of the targets will execute the same target in the 314 subdirectories. 315 316The include file <bsd.prog.mk> includes the file named "../Makefile.inc" 317if it exists, as well as the include file <bsd.man.mk>. 318 319Some simple examples: 320 321To build foo from foo.c with a manual page foo.1, use: 322 323 PROG= foo 324 325 .include <bsd.prog.mk> 326 327To build foo from foo.c with a manual page foo.2, add the line: 328 329 MAN= foo.2 330 331If foo does not have a manual page at all, add the line: 332 333 NOMAN= noman 334 335If foo has multiple source files, add the line: 336 337 SRCS= a.c b.c c.c d.c 338 339=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 340 341The include file <bsd.subdir.mk> contains the default targets for building 342subdirectories. It has the same eight targets as <bsd.prog.mk>: all, 343clean, cleandir, depend, includes, install, lint, and tags. For all of 344the directories listed in the variable SUBDIRS, the specified directory 345will be visited and the target made. There is also a default target which 346allows the command "make subdir" where subdir is any directory listed in 347the variable SUBDIRS. 348 349=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 350 351The include file <bsd.sys.mk> is used by <bsd.prog.mk> and 352<bsd.lib.mk>. It contains overrides that are used when building 353the NetBSD source tree. For instance, if "PARALLEL" is defined by 354the program/library Makefile, it includes a set of rules for lex and 355yacc that allow multiple lex and yacc targets to be built in parallel. 356 357=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 358 359The include file <bsd.lib.mk> has support for building libraries. It has 360the same eight targets as <bsd.prog.mk>: all, clean, cleandir, depend, 361includes, install, lint, and tags. It has a limited number of suffixes, 362consistent with the current needs of the BSD tree. 363 364It sets/uses the following variables: 365 366LIB The name of the library to build. 367 368LIBDIR Target directory for libraries. 369 370LINTLIBDIR Target directory for lint libraries. 371 372LIBGRP Library group. 373 374LIBOWN Library owner. 375 376LIBMODE Library mode. 377 378LDADD Additional loader objects. 379 380MAN The manual pages to be installed (use a .1 - .9 suffix). 381 382SRCS List of source files to build the library. Suffix types 383 .s, .c, and .f are supported. Note, .s files are preferred 384 to .c files of the same name. (This is not the default for 385 versions of make.) 386 387The include file <bsd.lib.mk> includes the file named "../Makefile.inc" 388if it exists, as well as the include file <bsd.man.mk>. 389 390It has rules for building profiled objects; profiled libraries are 391built by default. 392 393Libraries are ranlib'd when made. 394