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