bsd.README revision 58494
11638Srgrimes# @(#)bsd.README 8.2 (Berkeley) 4/2/94 250476Speter# $FreeBSD: head/share/mk/bsd.README 58494 2000-03-23 16:48:04Z ru $ 31638Srgrimes 43470SrgrimesXXX This document is seriously out of date, it is currenly being revised. 53470Srgrimes 61638SrgrimesThis is the README file for the new make "include" files for the BSD 723559Swoschsource tree. The files are installed in /usr/share/mk, and are, by 823559Swoschconvention, named with the suffix ".mk". 91638Srgrimes 1023559Swoschbsd.dep.mk - handle Makefile dependencies 1123559Swoschbsd.doc.mk - building troff system documents 1223559Swoschbsd.info.mk - building GNU Info hypertext system 1323559Swoschbsd.kern.mk - define warning flags for compiling the kernel 1423559Swoschbsd.kmod.mk - building loadable kernel modules 1523559Swoschbsd.lib.mk - support for building libraries 1623559Swoschbsd.libnames.mk - define library names 1723559Swoschbsd.man.mk - installing manual pages and their links 1823559Swoschbsd.obj.mk - creating 'obj' directories and cleaning up 1923559Swoschbsd.own.mk - define common variables 2023559Swoschbsd.port.mk - building ports 2123559Swoschbsd.port.subdir.mk - targets for building subdirectories for ports 2223559Swoschbsd.prog.mk - building programs from source files 2323559Swoschbsd.sgml.mk - building SGML documents 2423559Swoschbsd.subdir.mk - targets for building subdirectories 2523559Swosch 2623559Swosch 271638SrgrimesNote, this file is not intended to replace reading through the .mk 281638Srgrimesfiles for anything tricky. 291638Srgrimes 3023578SwoschSee also make(1), mkdep(1) and `PMake - A Tutorial', 3123578Swoschlocated in /usr/share/doc/psd/12.make. 3223578Swosch 331638Srgrimes=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 341638Srgrimes 351638SrgrimesRANDOM THINGS WORTH KNOWING: 361638Srgrimes 371638SrgrimesThe files are simply C-style #include files, and pretty much behave like 381638Srgrimesyou'd expect. The syntax is slightly different in that a single '.' is 391638Srgrimesused instead of the hash mark, i.e. ".include <bsd.prog.mk>". 401638Srgrimes 411638SrgrimesOne difference that will save you lots of debugging time is that inclusion 421638Srgrimesof the file is normally done at the *end* of the Makefile. The reason for 431638Srgrimesthis is because .mk files often modify variables and behavior based on the 441638Srgrimesvalues of variables set in the Makefile. To make this work, remember that 451638Srgrimesthe FIRST target found is the target that is used, i.e. if the Makefile has: 461638Srgrimes 471638Srgrimes a: 481638Srgrimes echo a 491638Srgrimes a: 501638Srgrimes echo a number two 511638Srgrimes 521638Srgrimesthe command "make a" will echo "a". To make things confusing, the SECOND 531638Srgrimesvariable assignment is the overriding one, i.e. if the Makefile has: 541638Srgrimes 551638Srgrimes a= foo 561638Srgrimes a= bar 571638Srgrimes 581638Srgrimes b: 591638Srgrimes echo ${a} 601638Srgrimes 611638Srgrimesthe command "make b" will echo "bar". This is for compatibility with the 621638Srgrimesway the V7 make behaved. 631638Srgrimes 641638SrgrimesIt's fairly difficult to make the BSD .mk files work when you're building 651638Srgrimesmultiple programs in a single directory. It's a lot easier split up the 661638Srgrimesprograms than to deal with the problem. Most of the agony comes from making 671638Srgrimesthe "obj" directory stuff work right, not because we switch to a new version 681638Srgrimesof make. So, don't get mad at us, figure out a better way to handle multiple 691638Srgrimesarchitectures so we can quit using the symbolic link stuff. (Imake doesn't 701638Srgrimescount.) 711638Srgrimes 721638SrgrimesThe file .depend in the source directory is expected to contain dependencies 731638Srgrimesfor the source files. This file is read automatically by make after reading 741638Srgrimesthe Makefile. 751638Srgrimes 761638SrgrimesThe variable DESTDIR works as before. It's not set anywhere but will change 771638Srgrimesthe tree where the file gets installed. 781638Srgrimes 791638SrgrimesThe profiled libraries are no longer built in a different directory than 801638Srgrimesthe regular libraries. A new suffix, ".po", is used to denote a profiled 811638Srgrimesobject. 821638Srgrimes 831638Srgrimes=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 841638Srgrimes 851638SrgrimesThe include file <sys.mk> has the default rules for all makes, in the BSD 861638Srgrimesenvironment or otherwise. You probably don't want to touch this file. 871638Srgrimes 881638Srgrimes=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 891638Srgrimes 901638SrgrimesThe include file <bsd.man.mk> handles installing manual pages and their 911638Srgrimeslinks. 921638Srgrimes 931638SrgrimesIt has a single target: 941638Srgrimes 951638Srgrimes maninstall: 961638Srgrimes Install the manual pages and their links. 971638Srgrimes 981638SrgrimesIt sets/uses the following variables: 991638Srgrimes 1001638SrgrimesMANDIR Base path for manual installation. 1011638Srgrimes 1021638SrgrimesMANGRP Manual group. 1031638Srgrimes 1041638SrgrimesMANOWN Manual owner. 1051638Srgrimes 1061638SrgrimesMANMODE Manual mode. 1071638Srgrimes 1081638SrgrimesMANSUBDIR Subdirectory under the manual page section, i.e. "/vax" 1091638Srgrimes or "/tahoe" for machine specific manual pages. 1101638Srgrimes 11158494SruMAN1 ... MAN9 The manual pages to be installed (use a .1 - .9 suffix). 1121638Srgrimes 11358494SruMLINKS List of manual page links (using a .1 - .9 suffix). The 1141638Srgrimes linked-to file must come first, the linked file second, 1151638Srgrimes and there may be multiple pairs. The files are soft-linked. 1161638Srgrimes 1173470SrgrimesThe include file <bsd.man.mk> includes the include file <bsd.inc.mk>. 1181638Srgrimes 1191638Srgrimes=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 1201638Srgrimes 1211638SrgrimesThe include file <bsd.own.mk> contains the owners, groups, etc. for both 1221638Srgrimesmanual pages and binaries. 1231638Srgrimes 1241638SrgrimesIt has no targets. 1251638Srgrimes 1261638SrgrimesIt sets/uses the following variables: 1271638Srgrimes 1281638SrgrimesBINGRP Binary group. 1291638Srgrimes 1301638SrgrimesBINOWN Binary owner. 1311638Srgrimes 1321638SrgrimesBINMODE Binary mode. 1331638Srgrimes 1341638SrgrimesSTRIP The flag passed to the install program to cause the binary 1351638Srgrimes to be stripped. This is to be used when building your 1361638Srgrimes own install script so that the entire system can be made 1371638Srgrimes stripped/not-stripped using a single nob. 1381638Srgrimes 1391638SrgrimesMANDIR Base path for manual installation. 1401638Srgrimes 1411638SrgrimesMANGRP Manual group. 1421638Srgrimes 1431638SrgrimesMANOWN Manual owner. 1441638Srgrimes 1451638SrgrimesMANMODE Manual mode. 1461638Srgrimes 1471638SrgrimesThis file is generally useful when building your own Makefiles so that 1481638Srgrimesthey use the same default owners etc. as the rest of the tree. 1491638Srgrimes 1501638Srgrimes=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 1511638Srgrimes 1521638SrgrimesThe include file <bsd.prog.mk> handles building programs from one or 1531638Srgrimesmore source files, along with their manual pages. It has a limited number 1541638Srgrimesof suffixes, consistent with the current needs of the BSD tree. 1551638Srgrimes 1561638SrgrimesIt has seven targets: 1571638Srgrimes 1581638Srgrimes all: 1591638Srgrimes build the program and its manual page 1601638Srgrimes clean: 1611638Srgrimes remove the program, any object files and the files a.out, 1621638Srgrimes Errs, errs, mklog, and ${PROG}.core. 1631638Srgrimes cleandir: 1641638Srgrimes remove all of the files removed by the target clean, as 1651638Srgrimes well as .depend, tags, and any manual pages. 1661638Srgrimes depend: 1671638Srgrimes make the dependencies for the source files, and store 1681638Srgrimes them in the file .depend. 1691638Srgrimes install: 1701638Srgrimes install the program and its manual pages; if the Makefile 1711638Srgrimes does not itself define the target install, the targets 1721638Srgrimes beforeinstall and afterinstall may also be used to cause 1731638Srgrimes actions immediately before and after the install target 1741638Srgrimes is executed. 1751638Srgrimes lint: 1761638Srgrimes run lint on the source files 1771638Srgrimes tags: 1781638Srgrimes create a tags file for the source files. 1791638Srgrimes 1801638SrgrimesIt sets/uses the following variables: 1811638Srgrimes 1821638SrgrimesBINGRP Binary group. 1831638Srgrimes 1841638SrgrimesBINOWN Binary owner. 1851638Srgrimes 1861638SrgrimesBINMODE Binary mode. 1871638Srgrimes 18816437SphkCLEANFILES Additional files to remove and 18916437SphkCLEANDIRS additional directories to remove during clean and cleandir 19016437Sphk targets. "rm -f" and "rm -rf" used respectively. 1911638Srgrimes 1921638SrgrimesCOPTS Additional flags to the compiler when creating C objects. 1931638Srgrimes 1941638SrgrimesHIDEGAME If HIDEGAME is defined, the binary is installed in 1951638Srgrimes /usr/games/hide, and a symbolic link is created to 1961638Srgrimes /usr/games/dm. 1971638Srgrimes 1981638SrgrimesLDADD Additional loader objects. Usually used for libraries. 1991638Srgrimes For example, to load with the compatibility and utility 2001638Srgrimes libraries, use: 2011638Srgrimes 2021638Srgrimes LDFILES=-lutil -lcompat 2031638Srgrimes 2041638SrgrimesLDFLAGS Additional loader flags. 2051638Srgrimes 2061638SrgrimesLINKS The list of binary links; should be full pathnames, the 2071638Srgrimes linked-to file coming first, followed by the linked 2081638Srgrimes file. The files are hard-linked. For example, to link 2091638Srgrimes /bin/test and /bin/[, use: 2101638Srgrimes 2111638Srgrimes LINKS= ${DESTDIR}/bin/test ${DESTDIR}/bin/[ 2121638Srgrimes 21358494SruMAN1...MAN9 Manual pages (should end in .1 - .9). If no MAN variable 21458494Sru is defined, "MAN1=${PROG}.1" is assumed. 2151638Srgrimes 2161638SrgrimesPROG The name of the program to build. If not supplied, nothing 2171638Srgrimes is built. 2181638Srgrimes 21953965SmharoSRCS List of source files to build the program. If SRCS is not 2201638Srgrimes defined, it's assumed to be ${PROG}.c. 2211638Srgrimes 2221638SrgrimesDPADD Additional dependencies for the program. Usually used for 2231638Srgrimes libraries. For example, to depend on the compatibility and 2241638Srgrimes utility libraries use: 2251638Srgrimes 2261638Srgrimes SRCLIB=${LIBCOMPAT} ${LIBUTIL} 2271638Srgrimes 22814701Sbde There is a predefined identifier for each (non-profiled, 22914701Sbde non-shared) library and object. Library file names are 23014701Sbde transformed to identifiers by removing the extension and 23114701Sbde converting to upper case. 2321638Srgrimes 23314701Sbde There are no special identifiers for profiled or shared 23414701Sbde libraries or objects. The identifiers for the standard 23514701Sbde libraries are used in DPADD. This works correctly iff all 23614701Sbde the libraries are built at the same time. Unfortunately, 23714701Sbde it causes unnecessary relinks to shared libraries when 23814701Sbde only the static libraries have changed. Dependencies on 23914701Sbde shared libraries should be only on the library version 24014701Sbde numbers. 2411638Srgrimes 2421638SrgrimesSTRIP The flag passed to the install program to cause the binary 2431638Srgrimes to be stripped. 2441638Srgrimes 2451638SrgrimesSUBDIR A list of subdirectories that should be built as well. 2461638Srgrimes Each of the targets will execute the same target in the 2471638Srgrimes subdirectories. 2481638Srgrimes 2493470SrgrimesThe include file <bsd.prog.mk> includes the include files <bsd.inc.mk> 2503470Srgrimesand <bsd.man.mk>. 2511638Srgrimes 2521638SrgrimesSome simple examples: 2531638Srgrimes 2541638SrgrimesTo build foo from foo.c with a manual page foo.1, use: 2551638Srgrimes 2561638Srgrimes PROG= foo 2571638Srgrimes 2581638Srgrimes .include <bsd.prog.mk> 2591638Srgrimes 2601638SrgrimesTo build foo from foo.c with a manual page foo.2, add the line: 2611638Srgrimes 26258494Sru MAN2= foo.2 2631638Srgrimes 2641638SrgrimesIf foo does not have a manual page at all, add the line: 2651638Srgrimes 2661638Srgrimes NOMAN= noman 2671638Srgrimes 2681638SrgrimesIf foo has multiple source files, add the line: 2691638Srgrimes 2701638Srgrimes SRCS= a.c b.c c.c d.c 2711638Srgrimes 2721638Srgrimes=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 2731638Srgrimes 2741638SrgrimesThe include file <bsd.subdir.mk> contains the default targets for building 2751638Srgrimessubdirectories. It has the same seven targets as <bsd.prog.mk>: all, clean, 2761638Srgrimescleandir, depend, install, lint, and tags. For all of the directories 2771638Srgrimeslisted in the variable SUBDIRS, the specified directory will be visited 2781638Srgrimesand the target made. There is also a default target which allows the 2791638Srgrimescommand "make subdir" where subdir is any directory listed in the variable 2801638SrgrimesSUBDIRS. 2811638Srgrimes 2821638Srgrimes=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 2831638Srgrimes 2841638SrgrimesThe include file <bsd.lib.mk> has support for building libraries. It has 2851638Srgrimesthe same seven targets as <bsd.prog.mk>: all, clean, cleandir, depend, 2861638Srgrimesinstall, lint, and tags. It has a limited number of suffixes, consistent 2871638Srgrimeswith the current needs of the BSD tree. 2881638Srgrimes 2891638SrgrimesIt sets/uses the following variables: 2901638Srgrimes 2911638SrgrimesLIBDIR Target directory for libraries. 2921638Srgrimes 2931638SrgrimesLINTLIBDIR Target directory for lint libraries. 2941638Srgrimes 2951638SrgrimesLIBGRP Library group. 2961638Srgrimes 2971638SrgrimesLIBOWN Library owner. 2981638Srgrimes 2991638SrgrimesLIBMODE Library mode. 3001638Srgrimes 3011638SrgrimesLDADD Additional loader objects. 3021638Srgrimes 30358494SruMAN1 ... MAN9 The manual pages to be installed (use a .1 - .9 suffix). 3041638Srgrimes 3051638SrgrimesSRCS List of source files to build the library. Suffix types 3061638Srgrimes .s, .c, and .f are supported. Note, .s files are preferred 3071638Srgrimes to .c files of the same name. (This is not the default for 3081638Srgrimes versions of make.) 3091638Srgrimes 3103470SrgrimesThe include file <bsd.lib.mk> includes the include files <bsd.inc.mk> 3113470Srgrimesand <bsd.man.mk>. 3121638Srgrimes 3131638SrgrimesIt has rules for building profiled objects; profiled libraries are 3141638Srgrimesbuilt by default. 3151638Srgrimes 3161638SrgrimesLibraries are ranlib'd before installation. 317