bsd.README revision 75284
11638Srgrimes# @(#)bsd.README 8.2 (Berkeley) 4/2/94 250476Speter# $FreeBSD: head/share/mk/bsd.README 75284 2001-04-07 11:13:46Z 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 774942Srusource 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 11174942SruMAN 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 11774942SruThe include file <bsd.man.mk> includes a file named "../Makefile.inc" if 11874942Sruit exists. 1191638Srgrimes 1201638Srgrimes=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 1211638Srgrimes 1221638SrgrimesThe include file <bsd.own.mk> contains the owners, groups, etc. for both 1231638Srgrimesmanual pages and binaries. 1241638Srgrimes 1251638SrgrimesIt has no targets. 1261638Srgrimes 1271638SrgrimesIt sets/uses the following variables: 1281638Srgrimes 1291638SrgrimesBINGRP Binary group. 1301638Srgrimes 1311638SrgrimesBINOWN Binary owner. 1321638Srgrimes 1331638SrgrimesBINMODE Binary mode. 1341638Srgrimes 1351638SrgrimesSTRIP The flag passed to the install program to cause the binary 1361638Srgrimes to be stripped. This is to be used when building your 1371638Srgrimes own install script so that the entire system can be made 1381638Srgrimes stripped/not-stripped using a single nob. 1391638Srgrimes 1401638SrgrimesMANDIR Base path for manual installation. 1411638Srgrimes 1421638SrgrimesMANGRP Manual group. 1431638Srgrimes 1441638SrgrimesMANOWN Manual owner. 1451638Srgrimes 1461638SrgrimesMANMODE Manual mode. 1471638Srgrimes 1481638SrgrimesThis file is generally useful when building your own Makefiles so that 1491638Srgrimesthey use the same default owners etc. as the rest of the tree. 1501638Srgrimes 1511638Srgrimes=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 1521638Srgrimes 1531638SrgrimesThe include file <bsd.prog.mk> handles building programs from one or 1541638Srgrimesmore source files, along with their manual pages. It has a limited number 1551638Srgrimesof suffixes, consistent with the current needs of the BSD tree. 1561638Srgrimes 1571638SrgrimesIt has seven targets: 1581638Srgrimes 1591638Srgrimes all: 1601638Srgrimes build the program and its manual page 1611638Srgrimes clean: 1621638Srgrimes remove the program, any object files and the files a.out, 1631638Srgrimes Errs, errs, mklog, and ${PROG}.core. 1641638Srgrimes cleandir: 1651638Srgrimes remove all of the files removed by the target clean, as 1661638Srgrimes well as .depend, tags, and any manual pages. 1671638Srgrimes depend: 1681638Srgrimes make the dependencies for the source files, and store 1691638Srgrimes them in the file .depend. 1701638Srgrimes install: 1711638Srgrimes install the program and its manual pages; if the Makefile 1721638Srgrimes does not itself define the target install, the targets 1731638Srgrimes beforeinstall and afterinstall may also be used to cause 1741638Srgrimes actions immediately before and after the install target 1751638Srgrimes is executed. 1761638Srgrimes lint: 1771638Srgrimes run lint on the source files 1781638Srgrimes tags: 1791638Srgrimes create a tags file for the source files. 1801638Srgrimes 1811638SrgrimesIt sets/uses the following variables: 1821638Srgrimes 1831638SrgrimesBINGRP Binary group. 1841638Srgrimes 1851638SrgrimesBINOWN Binary owner. 1861638Srgrimes 1871638SrgrimesBINMODE Binary mode. 1881638Srgrimes 18916437SphkCLEANFILES Additional files to remove and 19016437SphkCLEANDIRS additional directories to remove during clean and cleandir 19116437Sphk targets. "rm -f" and "rm -rf" used respectively. 1921638Srgrimes 1931638SrgrimesCOPTS Additional flags to the compiler when creating C objects. 1941638Srgrimes 1951638SrgrimesHIDEGAME If HIDEGAME is defined, the binary is installed in 1961638Srgrimes /usr/games/hide, and a symbolic link is created to 1971638Srgrimes /usr/games/dm. 1981638Srgrimes 1991638SrgrimesLDADD Additional loader objects. Usually used for libraries. 2001638Srgrimes For example, to load with the compatibility and utility 2011638Srgrimes libraries, use: 2021638Srgrimes 2031638Srgrimes LDFILES=-lutil -lcompat 2041638Srgrimes 2051638SrgrimesLDFLAGS Additional loader flags. 2061638Srgrimes 2071638SrgrimesLINKS The list of binary links; should be full pathnames, the 2081638Srgrimes linked-to file coming first, followed by the linked 2091638Srgrimes file. The files are hard-linked. For example, to link 2101638Srgrimes /bin/test and /bin/[, use: 2111638Srgrimes 2121638Srgrimes LINKS= ${DESTDIR}/bin/test ${DESTDIR}/bin/[ 2131638Srgrimes 21474942SruMAN Manual pages (should end in .1 - .9). If no MAN variable 21574942Sru is defined, "MAN=${PROG}.1" is assumed. 2161638Srgrimes 2171638SrgrimesPROG The name of the program to build. If not supplied, nothing 2181638Srgrimes is built. 2191638Srgrimes 22075083SruPROGNAME The name that the above program will be installed as, if 22175083Sru different from ${PROG}. 22275083Sru 22353965SmharoSRCS List of source files to build the program. If SRCS is not 2241638Srgrimes defined, it's assumed to be ${PROG}.c. 2251638Srgrimes 2261638SrgrimesDPADD Additional dependencies for the program. Usually used for 2271638Srgrimes libraries. For example, to depend on the compatibility and 2281638Srgrimes utility libraries use: 2291638Srgrimes 2301638Srgrimes SRCLIB=${LIBCOMPAT} ${LIBUTIL} 2311638Srgrimes 23214701Sbde There is a predefined identifier for each (non-profiled, 23314701Sbde non-shared) library and object. Library file names are 23414701Sbde transformed to identifiers by removing the extension and 23514701Sbde converting to upper case. 2361638Srgrimes 23714701Sbde There are no special identifiers for profiled or shared 23814701Sbde libraries or objects. The identifiers for the standard 23914701Sbde libraries are used in DPADD. This works correctly iff all 24014701Sbde the libraries are built at the same time. Unfortunately, 24114701Sbde it causes unnecessary relinks to shared libraries when 24214701Sbde only the static libraries have changed. Dependencies on 24314701Sbde shared libraries should be only on the library version 24414701Sbde numbers. 2451638Srgrimes 2461638SrgrimesSTRIP The flag passed to the install program to cause the binary 2471638Srgrimes to be stripped. 2481638Srgrimes 2491638SrgrimesSUBDIR A list of subdirectories that should be built as well. 2501638Srgrimes Each of the targets will execute the same target in the 2511638Srgrimes subdirectories. 2521638Srgrimes 25375284SruSCRIPTS A list of interpreter scripts [file.{sh,csh,pl,awk,...}]. 25475284Sru The installation is controlled by the SCRIPTSNAME, SCRIPTSOWN, 25575284Sru SCRIPTSGRP, SCRIPTSMODE, SCRIPTSDIR variables that can be 25675284Sru further specialized by SCRIPTS<VAR>_<script>. 25775284Sru 25874942SruThe include file <bsd.prog.mk> includes the file named "../Makefile.inc" 25974942Sruif it exists, as well as the include file <bsd.man.mk>. 2601638Srgrimes 2611638SrgrimesSome simple examples: 2621638Srgrimes 2631638SrgrimesTo build foo from foo.c with a manual page foo.1, use: 2641638Srgrimes 2651638Srgrimes PROG= foo 2661638Srgrimes 2671638Srgrimes .include <bsd.prog.mk> 2681638Srgrimes 2691638SrgrimesTo build foo from foo.c with a manual page foo.2, add the line: 2701638Srgrimes 27158494Sru MAN2= foo.2 2721638Srgrimes 2731638SrgrimesIf foo does not have a manual page at all, add the line: 2741638Srgrimes 2751638Srgrimes NOMAN= noman 2761638Srgrimes 2771638SrgrimesIf foo has multiple source files, add the line: 2781638Srgrimes 2791638Srgrimes SRCS= a.c b.c c.c d.c 2801638Srgrimes 2811638Srgrimes=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 2821638Srgrimes 2831638SrgrimesThe include file <bsd.subdir.mk> contains the default targets for building 2841638Srgrimessubdirectories. It has the same seven targets as <bsd.prog.mk>: all, clean, 2851638Srgrimescleandir, depend, install, lint, and tags. For all of the directories 2861638Srgrimeslisted in the variable SUBDIRS, the specified directory will be visited 2871638Srgrimesand the target made. There is also a default target which allows the 2881638Srgrimescommand "make subdir" where subdir is any directory listed in the variable 2891638SrgrimesSUBDIRS. 2901638Srgrimes 2911638Srgrimes=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 2921638Srgrimes 2931638SrgrimesThe include file <bsd.lib.mk> has support for building libraries. It has 2941638Srgrimesthe same seven targets as <bsd.prog.mk>: all, clean, cleandir, depend, 2951638Srgrimesinstall, lint, and tags. It has a limited number of suffixes, consistent 2961638Srgrimeswith the current needs of the BSD tree. 2971638Srgrimes 2981638SrgrimesIt sets/uses the following variables: 2991638Srgrimes 3001638SrgrimesLIBDIR Target directory for libraries. 3011638Srgrimes 3021638SrgrimesLINTLIBDIR Target directory for lint libraries. 3031638Srgrimes 3041638SrgrimesLIBGRP Library group. 3051638Srgrimes 3061638SrgrimesLIBOWN Library owner. 3071638Srgrimes 3081638SrgrimesLIBMODE Library mode. 3091638Srgrimes 3101638SrgrimesLDADD Additional loader objects. 3111638Srgrimes 31274942SruMAN The manual pages to be installed (use a .1 - .9 suffix). 3131638Srgrimes 3141638SrgrimesSRCS List of source files to build the library. Suffix types 3151638Srgrimes .s, .c, and .f are supported. Note, .s files are preferred 3161638Srgrimes to .c files of the same name. (This is not the default for 3171638Srgrimes versions of make.) 3181638Srgrimes 31974942SruThe include file <bsd.lib.mk> includes the file named "../Makefile.inc" 32074942Sruif it exists, as well as the include file <bsd.man.mk>. 3211638Srgrimes 3221638SrgrimesIt has rules for building profiled objects; profiled libraries are 3231638Srgrimesbuilt by default. 3241638Srgrimes 3251638SrgrimesLibraries are ranlib'd before installation. 326