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 for the clean and cleandir targets. 171 172COPTS Additional flags to the compiler when creating C objects. 173 174HIDEGAME If HIDEGAME is defined, the binary is installed in 175 /usr/games/hide, and a symbolic link is created to 176 /usr/games/dm. 177 178LDADD Additional loader objects. Usually used for libraries. 179 For example, to load with the compatibility and utility 180 libraries, use: 181 182 LDFILES=-lutil -lcompat 183 184LDFLAGS Additional loader flags. 185 186LINKS The list of binary links; should be full pathnames, the 187 linked-to file coming first, followed by the linked 188 file. The files are hard-linked. For example, to link 189 /bin/test and /bin/[, use: 190 191 LINKS= ${DESTDIR}/bin/test ${DESTDIR}/bin/[ 192 193MAN1...MAN8 Manual pages (should end in .0). If no MAN variable is 194 defined, "MAN1=${PROG}.0" is assumed. 195 196PROG The name of the program to build. If not supplied, nothing 197 is built. 198 199SRCS List of source files to build the program. If PROG is not 200 defined, it's assumed to be ${PROG}.c. 201 202DPADD Additional dependencies for the program. Usually used for 203 libraries. For example, to depend on the compatibility and 204 utility libraries use: 205 206 SRCLIB=${LIBCOMPAT} ${LIBUTIL} 207 208 There is a predefined identifier for each (non-profiled, 209 non-shared) library and object. Library file names are 210 transformed to identifiers by removing the extension and 211 converting to upper case. 212 213 There are no special identifiers for profiled or shared 214 libraries or objects. The identifiers for the standard 215 libraries are used in DPADD. This works correctly iff all 216 the libraries are built at the same time. Unfortunately, 217 it causes unnecessary relinks to shared libraries when 218 only the static libraries have changed. Dependencies on 219 shared libraries should be only on the library version 220 numbers. 221 222STRIP The flag passed to the install program to cause the binary 223 to be stripped. 224 225SUBDIR A list of subdirectories that should be built as well. 226 Each of the targets will execute the same target in the 227 subdirectories. 228 229The include file <bsd.prog.mk> includes the include files <bsd.inc.mk> 230and <bsd.man.mk>. 231 232Some simple examples: 233 234To build foo from foo.c with a manual page foo.1, use: 235 236 PROG= foo 237 238 .include <bsd.prog.mk> 239 240To build foo from foo.c with a manual page foo.2, add the line: 241 242 MAN2= foo.0 243 244If foo does not have a manual page at all, add the line: 245 246 NOMAN= noman 247 248If foo has multiple source files, add the line: 249 250 SRCS= a.c b.c c.c d.c 251 252=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 253 254The include file <bsd.subdir.mk> contains the default targets for building 255subdirectories. It has the same seven targets as <bsd.prog.mk>: all, clean, 256cleandir, depend, install, lint, and tags. For all of the directories 257listed in the variable SUBDIRS, the specified directory will be visited 258and the target made. There is also a default target which allows the 259command "make subdir" where subdir is any directory listed in the variable 260SUBDIRS. 261 262=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 263 264The include file <bsd.lib.mk> has support for building libraries. It has 265the same seven targets as <bsd.prog.mk>: all, clean, cleandir, depend, 266install, lint, and tags. It has a limited number of suffixes, consistent 267with the current needs of the BSD tree. 268 269It sets/uses the following variables: 270 271LIBDIR Target directory for libraries. 272 273LINTLIBDIR Target directory for lint libraries. 274 275LIBGRP Library group. 276 277LIBOWN Library owner. 278 279LIBMODE Library mode. 280 281LDADD Additional loader objects. 282 283MAN1 ... MAN8 The manual pages to be installed (use a .0 suffix). 284 285SRCS List of source files to build the library. Suffix types 286 .s, .c, and .f are supported. Note, .s files are preferred 287 to .c files of the same name. (This is not the default for 288 versions of make.) 289 290The include file <bsd.lib.mk> includes the include files <bsd.inc.mk> 291and <bsd.man.mk>. 292 293It has rules for building profiled objects; profiled libraries are 294built by default. 295 296Libraries are ranlib'd before installation. 297