Annotation of src/share/mk/bsd.README, Revision 1.1
1.1 ! deraadt 1: # $NetBSD: bsd.README,v 1.12 1995/09/24 23:49:06 christos Exp $
! 2: # @(#)bsd.README 5.1 (Berkeley) 5/11/90
! 3:
! 4: This is the README file for the new make "include" files for the BSD
! 5: source tree. The files are installed in /usr/share/mk, and are, by
! 6: convention, named with the suffix ".mk".
! 7:
! 8: Note, this file is not intended to replace reading through the .mk
! 9: files for anything tricky.
! 10:
! 11: =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
! 12:
! 13: RANDOM THINGS WORTH KNOWING:
! 14:
! 15: The files are simply C-style #include files, and pretty much behave like
! 16: you'd expect. The syntax is slightly different in that a single '.' is
! 17: used instead of the hash mark, i.e. ".include <bsd.prog.mk>".
! 18:
! 19: One difference that will save you lots of debugging time is that inclusion
! 20: of the file is normally done at the *end* of the Makefile. The reason for
! 21: this is because .mk files often modify variables and behavior based on the
! 22: values of variables set in the Makefile. To make this work, remember that
! 23: the 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:
! 30: the command "make a" will echo "a". To make things confusing, the SECOND
! 31: variable 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:
! 39: the command "make b" will echo "bar". This is for compatibility with the
! 40: way the V7 make behaved.
! 41:
! 42: It's fairly difficult to make the BSD .mk files work when you're building
! 43: multiple programs in a single directory. It's a lot easier split up the
! 44: programs than to deal with the problem. Most of the agony comes from making
! 45: the "obj" directory stuff work right, not because we switch to a new version
! 46: of make. So, don't get mad at us, figure out a better way to handle multiple
! 47: architectures so we can quit using the symbolic link stuff. (Imake doesn't
! 48: count.)
! 49:
! 50: The file .depend in the source directory is expected to contain dependencies
! 51: for the source files. This file is read automatically by make after reading
! 52: the Makefile.
! 53:
! 54: The variable DESTDIR works as before. It's not set anywhere but will change
! 55: the tree where the file gets installed.
! 56:
! 57: The profiled libraries are no longer built in a different directory than
! 58: the regular libraries. A new suffix, ".po", is used to denote a profiled
! 59: object.
! 60:
! 61: =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
! 62:
! 63: The include file <sys.mk> has the default rules for all makes, in the BSD
! 64: environment or otherwise. You probably don't want to touch this file.
! 65:
! 66: =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
! 67:
! 68: The include file <bsd.man.mk> handles installing manual pages and their
! 69: links.
! 70:
! 71: It has a single target:
! 72:
! 73: maninstall:
! 74: Install the manual pages and their links.
! 75:
! 76: It sets/uses the following variables:
! 77:
! 78: MANDIR Base path for manual installation.
! 79:
! 80: MANGRP Manual group.
! 81:
! 82: MANOWN Manual owner.
! 83:
! 84: MANMODE Manual mode.
! 85:
! 86: MANSUBDIR Subdirectory under the manual page section, i.e. "/vax"
! 87: or "/tahoe" for machine specific manual pages.
! 88:
! 89: MAN The manual pages to be installed (use a .1 - .8 suffix).
! 90:
! 91: MLINKS List of manual page links (using a .1 - .8 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:
! 95: The include file <bsd.man.mk> includes a file named "../Makefile.inc" if
! 96: it exists.
! 97:
! 98: =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
! 99:
! 100: The include file <bsd.own.mk> contains the owners, groups, etc. for both
! 101: manual pages and binaries.
! 102:
! 103: It has no targets.
! 104:
! 105: It sets/uses the following variables:
! 106:
! 107: BINGRP Binary group.
! 108:
! 109: BINOWN Binary owner.
! 110:
! 111: BINMODE Binary mode.
! 112:
! 113: STRIP The flag passed to the install program to cause the binary
! 114: to be stripped. This is to be used when building your
! 115: own install script so that the entire system can be made
! 116: stripped/not-stripped using a single nob.
! 117:
! 118: COPY The flag passed to the install program to cause the binary
! 119: to be copied rather than moved. This is to be used when
! 120: building our own install script so that the entire system
! 121: can either be installed with copies, or with moves using
! 122: a single nob.
! 123:
! 124: MANDIR Base path for manual installation.
! 125:
! 126: MANGRP Manual group.
! 127:
! 128: MANOWN Manual owner.
! 129:
! 130: MANMODE Manual mode.
! 131:
! 132: This file is generally useful when building your own Makefiles so that
! 133: they use the same default owners etc. as the rest of the tree.
! 134:
! 135: =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
! 136:
! 137: The include file <bsd.prog.mk> handles building programs from one or
! 138: more source files, along with their manual pages. It has a limited number
! 139: of suffixes, consistent with the current needs of the BSD tree.
! 140:
! 141: It has seven targets:
! 142:
! 143: all:
! 144: build the program and its manual page
! 145: clean:
! 146: remove the program, any object files and the files a.out,
! 147: Errs, errs, mklog, and core.
! 148: cleandir:
! 149: remove all of the files removed by the target clean, as
! 150: well as .depend, tags, and any manual pages.
! 151: depend:
! 152: make the dependencies for the source files, and store
! 153: them in the file .depend.
! 154: install:
! 155: install the program and its manual pages; if the Makefile
! 156: does not itself define the target install, the targets
! 157: beforeinstall and afterinstall may also be used to cause
! 158: actions immediately before and after the install target
! 159: is executed.
! 160: lint:
! 161: run lint on the source files
! 162: tags:
! 163: create a tags file for the source files.
! 164:
! 165: It sets/uses the following variables:
! 166:
! 167: BINGRP Binary group.
! 168:
! 169: BINOWN Binary owner.
! 170:
! 171: BINMODE Binary mode.
! 172:
! 173: CLEANFILES Additional files to remove for the clean and cleandir targets.
! 174:
! 175: COPTS Additional flags to the compiler when creating C objects.
! 176:
! 177: HIDEGAME If HIDEGAME is defined, the binary is installed in
! 178: /usr/games/hide, and a symbolic link is created to
! 179: /usr/games/dm.
! 180:
! 181: LDADD Additional loader objects. Usually used for libraries.
! 182: For example, to load with the compatibility and utility
! 183: libraries, use:
! 184:
! 185: LDADD+=-lutil -lcompat
! 186:
! 187: LDFLAGS Additional loader flags.
! 188:
! 189: LINKS The list of binary links; should be full pathnames, the
! 190: linked-to file coming first, followed by the linked
! 191: file. The files are hard-linked. For example, to link
! 192: /bin/test and /bin/[, use:
! 193:
! 194: LINKS= ${DESTDIR}/bin/test ${DESTDIR}/bin/[
! 195:
! 196: MAN Manual pages (should end in .1 - .8). If no MAN variable is
! 197: defined, "MAN=${PROG}.1" is assumed.
! 198:
! 199: PROG The name of the program to build. If not supplied, nothing
! 200: is built.
! 201:
! 202: SRCS List of source files to build the program. If PROG is not
! 203: defined, it's assumed to be ${PROG}.c.
! 204:
! 205: DPADD Additional dependencies for the program. Usually used for
! 206: libraries. For example, to depend on the compatibility and
! 207: utility libraries use:
! 208:
! 209: DPADD+=${LIBCOMPAT} ${LIBUTIL}
! 210:
! 211: The following libraries are predefined for DPADD:
! 212:
! 213: LIBC /lib/libc.a
! 214: LIBCOMPAT /usr/lib/libcompat.a
! 215: LIBCRYPT /usr/lib/libcrypt.a
! 216: LIBCURSES /usr/lib/libcurses.a
! 217: LIBDBM /usr/lib/libdbm.a
! 218: LIBDES /usr/lib/libdes.a
! 219: LIBL /usr/lib/libl.a
! 220: LIBKDB /usr/lib/libkdb.a
! 221: LIBKRB /usr/lib/libkrb.a
! 222: LIBKVM /usr/lib/libkvm.a
! 223: LIBM /usr/lib/libm.a
! 224: LIBMP /usr/lib/libmp.a
! 225: LIBPC /usr/lib/libpc.a
! 226: LIBPLOT /usr/lib/libplot.a
! 227: LIBRPC /usr/lib/sunrpc.a
! 228: LIBTERM /usr/lib/libterm.a
! 229: LIBUTIL /usr/lib/libutil.a
! 230:
! 231: SHAREDSTRINGS If defined, a new .c.o rule is used that results in shared
! 232: strings, using xstr(1). Note that this will not work with
! 233: parallel makes.
! 234:
! 235: STRIP The flag passed to the install program to cause the binary
! 236: to be stripped.
! 237:
! 238: SUBDIR A list of subdirectories that should be built as well.
! 239: Each of the targets will execute the same target in the
! 240: subdirectories.
! 241:
! 242: The include file <bsd.prog.mk> includes the file named "../Makefile.inc"
! 243: if it exists, as well as the include file <bsd.man.mk>.
! 244:
! 245: Some simple examples:
! 246:
! 247: To build foo from foo.c with a manual page foo.1, use:
! 248:
! 249: PROG= foo
! 250:
! 251: .include <bsd.prog.mk>
! 252:
! 253: To build foo from foo.c with a manual page foo.2, add the line:
! 254:
! 255: MAN= foo.2
! 256:
! 257: If foo does not have a manual page at all, add the line:
! 258:
! 259: NOMAN= noman
! 260:
! 261: If foo has multiple source files, add the line:
! 262:
! 263: SRCS= a.c b.c c.c d.c
! 264:
! 265: =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
! 266:
! 267: The include file <bsd.subdir.mk> contains the default targets for building
! 268: subdirectories. It has the same seven targets as <bsd.prog.mk>: all, clean,
! 269: cleandir, depend, install, lint, and tags. For all of the directories
! 270: listed in the variable SUBDIRS, the specified directory will be visited
! 271: and the target made. There is also a default target which allows the
! 272: command "make subdir" where subdir is any directory listed in the variable
! 273: SUBDIRS.
! 274:
! 275: =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
! 276:
! 277: The include file <bsd.lib.mk> has support for building libraries. It has
! 278: the same seven targets as <bsd.prog.mk>: all, clean, cleandir, depend,
! 279: install, lint, and tags. It has a limited number of suffixes, consistent
! 280: with the current needs of the BSD tree.
! 281:
! 282: It sets/uses the following variables:
! 283:
! 284: LIB The name of the library to build.
! 285:
! 286: LIBDIR Target directory for libraries.
! 287:
! 288: LINTLIBDIR Target directory for lint libraries.
! 289:
! 290: LIBGRP Library group.
! 291:
! 292: LIBOWN Library owner.
! 293:
! 294: LIBMODE Library mode.
! 295:
! 296: LDADD Additional loader objects.
! 297:
! 298: MAN The manual pages to be installed (use a .1 - .8 suffix).
! 299:
! 300: SRCS List of source files to build the library. Suffix types
! 301: .s, .c, and .f are supported. Note, .s files are preferred
! 302: to .c files of the same name. (This is not the default for
! 303: versions of make.)
! 304:
! 305: The include file <bsd.lib.mk> includes the file named "../Makefile.inc"
! 306: if it exists, as well as the include file <bsd.man.mk>.
! 307:
! 308: It has rules for building profiled objects; profiled libraries are
! 309: built by default.
! 310:
! 311: Libraries are ranlib'd when made.