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