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