bsd.README revision 94424
11638Srgrimes# @(#)bsd.README 8.2 (Berkeley) 4/2/94 250476Speter# $FreeBSD: head/share/mk/bsd.README 94424 2002-04-11 10:44:30Z 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 9383075SruIt has three targets: 941638Srgrimes 9583075Sru all-man: 9683075Sru build manual pages. 971638Srgrimes maninstall: 9883075Sru install the manual pages and their links. 9983075Sru manlint: 10083075Sru verify the validity of manual pages. 1011638Srgrimes 1021638SrgrimesIt sets/uses the following variables: 1031638Srgrimes 1041638SrgrimesMANDIR Base path for manual installation. 1051638Srgrimes 1061638SrgrimesMANGRP Manual group. 1071638Srgrimes 1081638SrgrimesMANOWN Manual owner. 1091638Srgrimes 1101638SrgrimesMANMODE Manual mode. 1111638Srgrimes 1121638SrgrimesMANSUBDIR Subdirectory under the manual page section, i.e. "/vax" 1131638Srgrimes or "/tahoe" for machine specific manual pages. 1141638Srgrimes 11574942SruMAN The manual pages to be installed (use a .1 - .9 suffix). 1161638Srgrimes 11758494SruMLINKS List of manual page links (using a .1 - .9 suffix). The 1181638Srgrimes linked-to file must come first, the linked file second, 1191638Srgrimes and there may be multiple pairs. The files are soft-linked. 1201638Srgrimes 12174942SruThe include file <bsd.man.mk> includes a file named "../Makefile.inc" if 12274942Sruit exists. 1231638Srgrimes 1241638Srgrimes=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 1251638Srgrimes 1261638SrgrimesThe include file <bsd.own.mk> contains the owners, groups, etc. for both 1271638Srgrimesmanual pages and binaries. 1281638Srgrimes 1291638SrgrimesIt has no targets. 1301638Srgrimes 1311638SrgrimesIt sets/uses the following variables: 1321638Srgrimes 1331638SrgrimesBINGRP Binary group. 1341638Srgrimes 1351638SrgrimesBINOWN Binary owner. 1361638Srgrimes 1371638SrgrimesBINMODE Binary mode. 1381638Srgrimes 1391638SrgrimesSTRIP The flag passed to the install program to cause the binary 1401638Srgrimes to be stripped. This is to be used when building your 1411638Srgrimes own install script so that the entire system can be made 1421638Srgrimes stripped/not-stripped using a single nob. 1431638Srgrimes 1441638SrgrimesMANDIR Base path for manual installation. 1451638Srgrimes 1461638SrgrimesMANGRP Manual group. 1471638Srgrimes 1481638SrgrimesMANOWN Manual owner. 1491638Srgrimes 1501638SrgrimesMANMODE Manual mode. 1511638Srgrimes 1521638SrgrimesThis file is generally useful when building your own Makefiles so that 1531638Srgrimesthey use the same default owners etc. as the rest of the tree. 1541638Srgrimes 1551638Srgrimes=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 1561638Srgrimes 1571638SrgrimesThe include file <bsd.prog.mk> handles building programs from one or 1581638Srgrimesmore source files, along with their manual pages. It has a limited number 1591638Srgrimesof suffixes, consistent with the current needs of the BSD tree. 1601638Srgrimes 1611638SrgrimesIt has seven targets: 1621638Srgrimes 1631638Srgrimes all: 1641638Srgrimes build the program and its manual page 1651638Srgrimes clean: 1661638Srgrimes remove the program, any object files and the files a.out, 1671638Srgrimes Errs, errs, mklog, and ${PROG}.core. 1681638Srgrimes cleandir: 1691638Srgrimes remove all of the files removed by the target clean, as 1701638Srgrimes well as .depend, tags, and any manual pages. 1711638Srgrimes depend: 1721638Srgrimes make the dependencies for the source files, and store 1731638Srgrimes them in the file .depend. 1741638Srgrimes install: 1751638Srgrimes install the program and its manual pages; if the Makefile 1761638Srgrimes does not itself define the target install, the targets 1771638Srgrimes beforeinstall and afterinstall may also be used to cause 1781638Srgrimes actions immediately before and after the install target 1791638Srgrimes is executed. 1801638Srgrimes lint: 1811638Srgrimes run lint on the source files 1821638Srgrimes tags: 1831638Srgrimes create a tags file for the source files. 1841638Srgrimes 1851638SrgrimesIt sets/uses the following variables: 1861638Srgrimes 1871638SrgrimesBINGRP Binary group. 1881638Srgrimes 1891638SrgrimesBINOWN Binary owner. 1901638Srgrimes 1911638SrgrimesBINMODE Binary mode. 1921638Srgrimes 19316437SphkCLEANFILES Additional files to remove and 19416437SphkCLEANDIRS additional directories to remove during clean and cleandir 19516437Sphk targets. "rm -f" and "rm -rf" used respectively. 1961638Srgrimes 1971638SrgrimesCOPTS Additional flags to the compiler when creating C objects. 1981638Srgrimes 19988055SruFILES A list of non-executable files. 20088055Sru The installation is controlled by the FILESNAME, FILESOWN, 20188055Sru FILESGRP, FILESMODE, FILESDIR variables that can be 20288055Sru further specialized by FILES<VAR>_<file>. 20388055Sru 2041638SrgrimesHIDEGAME If HIDEGAME is defined, the binary is installed in 2051638Srgrimes /usr/games/hide, and a symbolic link is created to 2061638Srgrimes /usr/games/dm. 2071638Srgrimes 2081638SrgrimesLDADD Additional loader objects. Usually used for libraries. 2091638Srgrimes For example, to load with the compatibility and utility 2101638Srgrimes libraries, use: 2111638Srgrimes 2121638Srgrimes LDFILES=-lutil -lcompat 2131638Srgrimes 2141638SrgrimesLDFLAGS Additional loader flags. 2151638Srgrimes 2161638SrgrimesLINKS The list of binary links; should be full pathnames, the 2171638Srgrimes linked-to file coming first, followed by the linked 2181638Srgrimes file. The files are hard-linked. For example, to link 2191638Srgrimes /bin/test and /bin/[, use: 2201638Srgrimes 2211638Srgrimes LINKS= ${DESTDIR}/bin/test ${DESTDIR}/bin/[ 2221638Srgrimes 22374942SruMAN Manual pages (should end in .1 - .9). If no MAN variable 22474942Sru is defined, "MAN=${PROG}.1" is assumed. 2251638Srgrimes 2261638SrgrimesPROG The name of the program to build. If not supplied, nothing 2271638Srgrimes is built. 2281638Srgrimes 22994424SruPROG_CXX If defined, the name of the program to build. Also 23094424Sru causes <bsd.prog.mk> to link the program with the 23194424Sru standard C++ library. PROG_CXX overrides the value 23294424Sru of PROG if PROG is also set. 23394424Sru 23475083SruPROGNAME The name that the above program will be installed as, if 23575083Sru different from ${PROG}. 23675083Sru 23753965SmharoSRCS List of source files to build the program. If SRCS is not 23894424Sru defined, it's assumed to be ${PROG}.c or, if PROG_CXX is 23994424Sru defined, ${PROG_CXX}.cc. 2401638Srgrimes 2411638SrgrimesDPADD Additional dependencies for the program. Usually used for 2421638Srgrimes libraries. For example, to depend on the compatibility and 2431638Srgrimes utility libraries use: 2441638Srgrimes 2451638Srgrimes SRCLIB=${LIBCOMPAT} ${LIBUTIL} 2461638Srgrimes 24714701Sbde There is a predefined identifier for each (non-profiled, 24814701Sbde non-shared) library and object. Library file names are 24914701Sbde transformed to identifiers by removing the extension and 25014701Sbde converting to upper case. 2511638Srgrimes 25214701Sbde There are no special identifiers for profiled or shared 25314701Sbde libraries or objects. The identifiers for the standard 25414701Sbde libraries are used in DPADD. This works correctly iff all 25514701Sbde the libraries are built at the same time. Unfortunately, 25614701Sbde it causes unnecessary relinks to shared libraries when 25714701Sbde only the static libraries have changed. Dependencies on 25814701Sbde shared libraries should be only on the library version 25914701Sbde numbers. 2601638Srgrimes 2611638SrgrimesSTRIP The flag passed to the install program to cause the binary 2621638Srgrimes to be stripped. 2631638Srgrimes 2641638SrgrimesSUBDIR A list of subdirectories that should be built as well. 2651638Srgrimes Each of the targets will execute the same target in the 2661638Srgrimes subdirectories. 2671638Srgrimes 26875284SruSCRIPTS A list of interpreter scripts [file.{sh,csh,pl,awk,...}]. 26975284Sru The installation is controlled by the SCRIPTSNAME, SCRIPTSOWN, 27075284Sru SCRIPTSGRP, SCRIPTSMODE, SCRIPTSDIR variables that can be 27175284Sru further specialized by SCRIPTS<VAR>_<script>. 27275284Sru 27374942SruThe include file <bsd.prog.mk> includes the file named "../Makefile.inc" 27474942Sruif it exists, as well as the include file <bsd.man.mk>. 2751638Srgrimes 2761638SrgrimesSome simple examples: 2771638Srgrimes 2781638SrgrimesTo build foo from foo.c with a manual page foo.1, use: 2791638Srgrimes 2801638Srgrimes PROG= foo 2811638Srgrimes 2821638Srgrimes .include <bsd.prog.mk> 2831638Srgrimes 2841638SrgrimesTo build foo from foo.c with a manual page foo.2, add the line: 2851638Srgrimes 28658494Sru MAN2= foo.2 2871638Srgrimes 2881638SrgrimesIf foo does not have a manual page at all, add the line: 2891638Srgrimes 2901638Srgrimes NOMAN= noman 2911638Srgrimes 2921638SrgrimesIf foo has multiple source files, add the line: 2931638Srgrimes 2941638Srgrimes SRCS= a.c b.c c.c d.c 2951638Srgrimes 2961638Srgrimes=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 2971638Srgrimes 2981638SrgrimesThe include file <bsd.subdir.mk> contains the default targets for building 2991638Srgrimessubdirectories. It has the same seven targets as <bsd.prog.mk>: all, clean, 3001638Srgrimescleandir, depend, install, lint, and tags. For all of the directories 3011638Srgrimeslisted in the variable SUBDIRS, the specified directory will be visited 3021638Srgrimesand the target made. There is also a default target which allows the 3031638Srgrimescommand "make subdir" where subdir is any directory listed in the variable 3041638SrgrimesSUBDIRS. 3051638Srgrimes 3061638Srgrimes=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 3071638Srgrimes 3081638SrgrimesThe include file <bsd.lib.mk> has support for building libraries. It has 3091638Srgrimesthe same seven targets as <bsd.prog.mk>: all, clean, cleandir, depend, 3101638Srgrimesinstall, lint, and tags. It has a limited number of suffixes, consistent 3111638Srgrimeswith the current needs of the BSD tree. 3121638Srgrimes 3131638SrgrimesIt sets/uses the following variables: 3141638Srgrimes 3151638SrgrimesLIBDIR Target directory for libraries. 3161638Srgrimes 3171638SrgrimesLINTLIBDIR Target directory for lint libraries. 3181638Srgrimes 3191638SrgrimesLIBGRP Library group. 3201638Srgrimes 3211638SrgrimesLIBOWN Library owner. 3221638Srgrimes 3231638SrgrimesLIBMODE Library mode. 3241638Srgrimes 3251638SrgrimesLDADD Additional loader objects. 3261638Srgrimes 32774942SruMAN The manual pages to be installed (use a .1 - .9 suffix). 3281638Srgrimes 3291638SrgrimesSRCS List of source files to build the library. Suffix types 3301638Srgrimes .s, .c, and .f are supported. Note, .s files are preferred 3311638Srgrimes to .c files of the same name. (This is not the default for 3321638Srgrimes versions of make.) 3331638Srgrimes 33474942SruThe include file <bsd.lib.mk> includes the file named "../Makefile.inc" 33574942Sruif it exists, as well as the include file <bsd.man.mk>. 3361638Srgrimes 3371638SrgrimesIt has rules for building profiled objects; profiled libraries are 3381638Srgrimesbuilt by default. 3391638Srgrimes 3401638SrgrimesLibraries are ranlib'd before installation. 341