bsd.README revision 83075
1286425Sdim# @(#)bsd.README 8.2 (Berkeley) 4/2/94 2286425Sdim# $FreeBSD: head/share/mk/bsd.README 83075 2001-09-05 11:24:34Z ru $ 3286425Sdim 4286425SdimXXX This document is seriously out of date, it is currenly being revised. 5286425Sdim 6286425SdimThis is the README file for the new make "include" files for the BSD 7286425Sdimsource tree. The files are installed in /usr/share/mk, and are, by 8286425Sdimconvention, named with the suffix ".mk". 9286425Sdim 10286425Sdimbsd.dep.mk - handle Makefile dependencies 11286425Sdimbsd.doc.mk - building troff system documents 12286425Sdimbsd.info.mk - building GNU Info hypertext system 13286425Sdimbsd.kern.mk - define warning flags for compiling the kernel 14286425Sdimbsd.kmod.mk - building loadable kernel modules 15296417Sdimbsd.lib.mk - support for building libraries 16296417Sdimbsd.libnames.mk - define library names 17296417Sdimbsd.man.mk - installing manual pages and their links 18296417Sdimbsd.obj.mk - creating 'obj' directories and cleaning up 19296417Sdimbsd.own.mk - define common variables 20296417Sdimbsd.port.mk - building ports 21296417Sdimbsd.port.subdir.mk - targets for building subdirectories for ports 22296417Sdimbsd.prog.mk - building programs from source files 23296417Sdimbsd.sgml.mk - building SGML documents 24296417Sdimbsd.subdir.mk - targets for building subdirectories 25296417Sdim 26296417Sdim 27296417SdimNote, this file is not intended to replace reading through the .mk 28296417Sdimfiles for anything tricky. 29296417Sdim 30296417SdimSee also make(1), mkdep(1) and `PMake - A Tutorial', 31296417Sdimlocated in /usr/share/doc/psd/12.make. 32296417Sdim 33296417Sdim=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 34296417Sdim 35296417SdimRANDOM THINGS WORTH KNOWING: 36296417Sdim 37296417SdimThe files are simply C-style #include files, and pretty much behave like 38296417Sdimyou'd expect. The syntax is slightly different in that a single '.' is 39296417Sdimused instead of the hash mark, i.e. ".include <bsd.prog.mk>". 40296417Sdim 41296417SdimOne difference that will save you lots of debugging time is that inclusion 42296417Sdimof the file is normally done at the *end* of the Makefile. The reason for 43296417Sdimthis is because .mk files often modify variables and behavior based on the 44296417Sdimvalues of variables set in the Makefile. To make this work, remember that 45296417Sdimthe FIRST target found is the target that is used, i.e. if the Makefile has: 46296417Sdim 47296417Sdim a: 48296417Sdim echo a 49296417Sdim a: 50296417Sdim echo a number two 51296417Sdim 52296417Sdimthe command "make a" will echo "a". To make things confusing, the SECOND 53296417Sdimvariable assignment is the overriding one, i.e. if the Makefile has: 54296417Sdim 55296417Sdim a= foo 56296417Sdim a= bar 57296417Sdim 58296417Sdim b: 59296417Sdim echo ${a} 60296417Sdim 61296417Sdimthe command "make b" will echo "bar". This is for compatibility with the 62296417Sdimway the V7 make behaved. 63296417Sdim 64296417SdimIt's fairly difficult to make the BSD .mk files work when you're building 65296417Sdimmultiple programs in a single directory. It's a lot easier split up the 66296417Sdimprograms than to deal with the problem. Most of the agony comes from making 67296417Sdimthe "obj" directory stuff work right, not because we switch to a new version 68296417Sdimof make. So, don't get mad at us, figure out a better way to handle multiple 69296417Sdimarchitectures so we can quit using the symbolic link stuff. (Imake doesn't 70296417Sdimcount.) 71296417Sdim 72296417SdimThe file .depend in the source directory is expected to contain dependencies 73296417Sdimfor the source files. This file is read automatically by make after reading 74296417Sdimthe Makefile. 75296417Sdim 76296417SdimThe variable DESTDIR works as before. It's not set anywhere but will change 77296417Sdimthe tree where the file gets installed. 78296417Sdim 79296417SdimThe profiled libraries are no longer built in a different directory than 80296417Sdimthe regular libraries. A new suffix, ".po", is used to denote a profiled 81296417Sdimobject. 82296417Sdim 83296417Sdim=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 84296417Sdim 85296417SdimThe include file <sys.mk> has the default rules for all makes, in the BSD 86296417Sdimenvironment or otherwise. You probably don't want to touch this file. 87296417Sdim 88296417Sdim=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 89296417Sdim 90296417SdimThe include file <bsd.man.mk> handles installing manual pages and their 91296417Sdimlinks. 92296417Sdim 93296417SdimIt has three targets: 94296417Sdim 95296417Sdim all-man: 96296417Sdim build manual pages. 97296417Sdim maninstall: 98296417Sdim install the manual pages and their links. 99296417Sdim manlint: 100296417Sdim verify the validity of manual pages. 101296417Sdim 102296417SdimIt sets/uses the following variables: 103296417Sdim 104296417SdimMANDIR Base path for manual installation. 105296417Sdim 106296417SdimMANGRP Manual group. 107296417Sdim 108296417SdimMANOWN Manual owner. 109296417Sdim 110296417SdimMANMODE Manual mode. 111296417Sdim 112296417SdimMANSUBDIR Subdirectory under the manual page section, i.e. "/vax" 113296417Sdim or "/tahoe" for machine specific manual pages. 114296417Sdim 115296417SdimMAN The manual pages to be installed (use a .1 - .9 suffix). 116296417Sdim 117296417SdimMLINKS List of manual page links (using a .1 - .9 suffix). The 118296417Sdim linked-to file must come first, the linked file second, 119296417Sdim and there may be multiple pairs. The files are soft-linked. 120296417Sdim 121296417SdimThe include file <bsd.man.mk> includes a file named "../Makefile.inc" if 122296417Sdimit exists. 123296417Sdim 124296417Sdim=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 125296417Sdim 126296417SdimThe include file <bsd.own.mk> contains the owners, groups, etc. for both 127296417Sdimmanual pages and binaries. 128296417Sdim 129296417SdimIt has no targets. 130296417Sdim 131296417SdimIt sets/uses the following variables: 132296417Sdim 133296417SdimBINGRP Binary group. 134296417Sdim 135296417SdimBINOWN Binary owner. 136296417Sdim 137296417SdimBINMODE Binary mode. 138296417Sdim 139296417SdimSTRIP The flag passed to the install program to cause the binary 140296417Sdim to be stripped. This is to be used when building your 141296417Sdim own install script so that the entire system can be made 142296417Sdim stripped/not-stripped using a single nob. 143296417Sdim 144296417SdimMANDIR Base path for manual installation. 145296417Sdim 146296417SdimMANGRP Manual group. 147296417Sdim 148296417SdimMANOWN Manual owner. 149296417Sdim 150296417SdimMANMODE Manual mode. 151296417Sdim 152296417SdimThis file is generally useful when building your own Makefiles so that 153296417Sdimthey use the same default owners etc. as the rest of the tree. 154296417Sdim 155296417Sdim=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 156296417Sdim 157296417SdimThe include file <bsd.prog.mk> handles building programs from one or 158296417Sdimmore source files, along with their manual pages. It has a limited number 159296417Sdimof suffixes, consistent with the current needs of the BSD tree. 160296417Sdim 161296417SdimIt has seven targets: 162296417Sdim 163296417Sdim all: 164296417Sdim build the program and its manual page 165296417Sdim clean: 166296417Sdim remove the program, any object files and the files a.out, 167296417Sdim Errs, errs, mklog, and ${PROG}.core. 168296417Sdim cleandir: 169296417Sdim remove all of the files removed by the target clean, as 170296417Sdim well as .depend, tags, and any manual pages. 171296417Sdim depend: 172296417Sdim make the dependencies for the source files, and store 173296417Sdim them in the file .depend. 174296417Sdim install: 175296417Sdim install the program and its manual pages; if the Makefile 176296417Sdim does not itself define the target install, the targets 177296417Sdim beforeinstall and afterinstall may also be used to cause 178296417Sdim actions immediately before and after the install target 179296417Sdim is executed. 180296417Sdim lint: 181296417Sdim run lint on the source files 182296417Sdim tags: 183296417Sdim create a tags file for the source files. 184296417Sdim 185296417SdimIt sets/uses the following variables: 186296417Sdim 187296417SdimBINGRP Binary group. 188296417Sdim 189296417SdimBINOWN Binary owner. 190296417Sdim 191296417SdimBINMODE Binary mode. 192296417Sdim 193296417SdimCLEANFILES Additional files to remove and 194296417SdimCLEANDIRS additional directories to remove during clean and cleandir 195296417Sdim targets. "rm -f" and "rm -rf" used respectively. 196296417Sdim 197296417SdimCOPTS Additional flags to the compiler when creating C objects. 198296417Sdim 199296417SdimHIDEGAME If HIDEGAME is defined, the binary is installed in 200296417Sdim /usr/games/hide, and a symbolic link is created to 201296417Sdim /usr/games/dm. 202296417Sdim 203296417SdimLDADD Additional loader objects. Usually used for libraries. 204296417Sdim For example, to load with the compatibility and utility 205296417Sdim libraries, use: 206296417Sdim 207296417Sdim LDFILES=-lutil -lcompat 208296417Sdim 209296417SdimLDFLAGS Additional loader flags. 210296417Sdim 211296417SdimLINKS The list of binary links; should be full pathnames, the 212296417Sdim linked-to file coming first, followed by the linked 213296417Sdim file. The files are hard-linked. For example, to link 214296417Sdim /bin/test and /bin/[, use: 215296417Sdim 216296417Sdim LINKS= ${DESTDIR}/bin/test ${DESTDIR}/bin/[ 217296417Sdim 218296417SdimMAN Manual pages (should end in .1 - .9). If no MAN variable 219296417Sdim is defined, "MAN=${PROG}.1" is assumed. 220296417Sdim 221296417SdimPROG The name of the program to build. If not supplied, nothing 222296417Sdim is built. 223296417Sdim 224296417SdimPROGNAME The name that the above program will be installed as, if 225296417Sdim different from ${PROG}. 226296417Sdim 227296417SdimSRCS List of source files to build the program. If SRCS is not 228296417Sdim defined, it's assumed to be ${PROG}.c. 229296417Sdim 230296417SdimDPADD Additional dependencies for the program. Usually used for 231296417Sdim libraries. For example, to depend on the compatibility and 232296417Sdim utility libraries use: 233296417Sdim 234296417Sdim SRCLIB=${LIBCOMPAT} ${LIBUTIL} 235296417Sdim 236296417Sdim There is a predefined identifier for each (non-profiled, 237296417Sdim non-shared) library and object. Library file names are 238296417Sdim transformed to identifiers by removing the extension and 239296417Sdim converting to upper case. 240296417Sdim 241296417Sdim There are no special identifiers for profiled or shared 242296417Sdim libraries or objects. The identifiers for the standard 243296417Sdim libraries are used in DPADD. This works correctly iff all 244296417Sdim the libraries are built at the same time. Unfortunately, 245296417Sdim it causes unnecessary relinks to shared libraries when 246296417Sdim only the static libraries have changed. Dependencies on 247296417Sdim shared libraries should be only on the library version 248296417Sdim numbers. 249296417Sdim 250296417SdimSTRIP The flag passed to the install program to cause the binary 251296417Sdim to be stripped. 252296417Sdim 253296417SdimSUBDIR A list of subdirectories that should be built as well. 254296417Sdim Each of the targets will execute the same target in the 255296417Sdim subdirectories. 256296417Sdim 257296417SdimSCRIPTS A list of interpreter scripts [file.{sh,csh,pl,awk,...}]. 258296417Sdim The installation is controlled by the SCRIPTSNAME, SCRIPTSOWN, 259296417Sdim SCRIPTSGRP, SCRIPTSMODE, SCRIPTSDIR variables that can be 260296417Sdim further specialized by SCRIPTS<VAR>_<script>. 261296417Sdim 262296417SdimThe include file <bsd.prog.mk> includes the file named "../Makefile.inc" 263296417Sdimif it exists, as well as the include file <bsd.man.mk>. 264296417Sdim 265296417SdimSome simple examples: 266296417Sdim 267296417SdimTo build foo from foo.c with a manual page foo.1, use: 268296417Sdim 269296417Sdim PROG= foo 270296417Sdim 271296417Sdim .include <bsd.prog.mk> 272296417Sdim 273296417SdimTo build foo from foo.c with a manual page foo.2, add the line: 274296417Sdim 275296417Sdim MAN2= foo.2 276296417Sdim 277296417SdimIf foo does not have a manual page at all, add the line: 278296417Sdim 279296417Sdim NOMAN= noman 280296417Sdim 281296417SdimIf foo has multiple source files, add the line: 282296417Sdim 283296417Sdim SRCS= a.c b.c c.c d.c 284296417Sdim 285296417Sdim=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 286296417Sdim 287296417SdimThe include file <bsd.subdir.mk> contains the default targets for building 288296417Sdimsubdirectories. It has the same seven targets as <bsd.prog.mk>: all, clean, 289296417Sdimcleandir, depend, install, lint, and tags. For all of the directories 290296417Sdimlisted in the variable SUBDIRS, the specified directory will be visited 291296417Sdimand the target made. There is also a default target which allows the 292296417Sdimcommand "make subdir" where subdir is any directory listed in the variable 293296417SdimSUBDIRS. 294296417Sdim 295296417Sdim=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 296296417Sdim 297296417SdimThe include file <bsd.lib.mk> has support for building libraries. It has 298296417Sdimthe same seven targets as <bsd.prog.mk>: all, clean, cleandir, depend, 299296417Sdiminstall, lint, and tags. It has a limited number of suffixes, consistent 300296417Sdimwith the current needs of the BSD tree. 301296417Sdim 302296417SdimIt sets/uses the following variables: 303296417Sdim 304296417SdimLIBDIR Target directory for libraries. 305296417Sdim 306296417SdimLINTLIBDIR Target directory for lint libraries. 307296417Sdim 308296417SdimLIBGRP Library group. 309296417Sdim 310296417SdimLIBOWN Library owner. 311296417Sdim 312296417SdimLIBMODE Library mode. 313296417Sdim 314296417SdimLDADD Additional loader objects. 315296417Sdim 316296417SdimMAN The manual pages to be installed (use a .1 - .9 suffix). 317296417Sdim 318296417SdimSRCS List of source files to build the library. Suffix types 319296417Sdim .s, .c, and .f are supported. Note, .s files are preferred 320296417Sdim to .c files of the same name. (This is not the default for 321296417Sdim versions of make.) 322296417Sdim 323296417SdimThe include file <bsd.lib.mk> includes the file named "../Makefile.inc" 324296417Sdimif it exists, as well as the include file <bsd.man.mk>. 325296417Sdim 326296417SdimIt has rules for building profiled objects; profiled libraries are 327296417Sdimbuilt by default. 328296417Sdim 329296417SdimLibraries are ranlib'd before installation. 330296417Sdim