bsd.README revision 125493
11638Srgrimes# @(#)bsd.README 8.2 (Berkeley) 4/2/94 250476Speter# $FreeBSD: head/share/mk/bsd.README 125493 2004-02-05 20:16:18Z ru $ 31638Srgrimes 4115103StrhodesThis is the README file for the "include" files for the FreeBSD 5115103Strhodessource tree. The files are installed in /usr/share/mk, and are by 6115103Strhodesconvention, named with the suffix ".mk". These files store several 7115103Strhodesbuild options and should be handled with caution. 83470Srgrimes 9115103StrhodesNote, this file is not intended to replace reading through the .mk 10115103Strhodesfiles for anything tricky. 111638Srgrimes 12115103StrhodesThere are two main types of make include files. One type is the generally 13115103Strhodesusable make include files, such as bsd.prog.mk and bsd.lib.mk. The other is 14115103Strhodesthe internal make include files, such as bsd.files.mk and bsd.man.mk, which 15115103Strhodescan not/should not be used directly but are used by the other make include 16115103Strhodesfiles. In most cases it is only interesting to include bsd.prog.mk or 17115103Strhodesbsd.lib.mk. 18115103Strhodes 19115103Strhodesbsd.cpu.mk - sets CPU/arch-related variables 2023559Swoschbsd.dep.mk - handle Makefile dependencies 2123559Swoschbsd.doc.mk - building troff system documents 22115103Strhodesbsd.files.mk - install of general purpose files 23115103Strhodesbsd.incs.mk - install of include files 2423559Swoschbsd.info.mk - building GNU Info hypertext system 25115103Strhodesbsd.init.mk - initialization for the make include files 2623559Swoschbsd.kmod.mk - building loadable kernel modules 2723559Swoschbsd.lib.mk - support for building libraries 2823559Swoschbsd.libnames.mk - define library names 29115103Strhodesbsd.links.mk - install of links (sym/hard) 30115103Strhodesbsd.man.mk - install of manual pages and their links 31115103Strhodesbsd.nls.mk - build and install of NLS catalogs 3223559Swoschbsd.obj.mk - creating 'obj' directories and cleaning up 3323559Swoschbsd.own.mk - define common variables 3423559Swoschbsd.port.mk - building ports 35115103Strhodesbsd.port.post.mk - building ports 36115103Strhodesbsd.port.pre.mk - building ports 3723559Swoschbsd.port.subdir.mk - targets for building subdirectories for ports 3823559Swoschbsd.prog.mk - building programs from source files 3923559Swoschbsd.subdir.mk - targets for building subdirectories 40115103Strhodesbsd.sys.mk - common settings used for building FreeBSD sources 41115103Strhodessys.mk - default rules for all makes 4223559Swosch 43115103StrhodesThis file does not document bsd.port*.mk. They are documented in ports(7). 4423559Swosch 45115103StrhodesSee also make(1), mkdep(1), style.Makefile(5) and `PMake - A 46115103StrhodesTutorial', located in /usr/share/doc/psd/12.make. 471638Srgrimes 48115103Strhodes=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 4923578Swosch 50115103StrhodesRandom things worth knowing about this document: 51115103Strhodes 52115103StrhodesIf appropriate when documenting the variables the default value is 53115103Strhodesindicated using square brackets e.g. [gzip]. 54115103StrhodesIn some cases the default value depend on other values (e.g. system 55115103Strhodesarchitecture). In these cases the most common value is indicated. 56115103Strhodes 57115103StrhodesThis document contains some simple examples of the usage of the BSD make 58115103Strhodesinclude files. For more examples look at the makefiles in the FreeBSD 59115103Strhodessource tree. 60115103Strhodes 611638Srgrimes=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 621638Srgrimes 631638SrgrimesRANDOM THINGS WORTH KNOWING: 641638Srgrimes 65115103StrhodesThe files are like C-style #include files, and pretty much behave like 661638Srgrimesyou'd expect. The syntax is slightly different in that a single '.' is 671638Srgrimesused instead of the hash mark, i.e. ".include <bsd.prog.mk>". 681638Srgrimes 691638SrgrimesOne difference that will save you lots of debugging time is that inclusion 701638Srgrimesof the file is normally done at the *end* of the Makefile. The reason for 711638Srgrimesthis is because .mk files often modify variables and behavior based on the 721638Srgrimesvalues of variables set in the Makefile. To make this work, remember that 731638Srgrimesthe FIRST target found is the target that is used, i.e. if the Makefile has: 741638Srgrimes 751638Srgrimes a: 761638Srgrimes echo a 771638Srgrimes a: 781638Srgrimes echo a number two 791638Srgrimes 801638Srgrimesthe command "make a" will echo "a". To make things confusing, the SECOND 811638Srgrimesvariable assignment is the overriding one, i.e. if the Makefile has: 821638Srgrimes 831638Srgrimes a= foo 841638Srgrimes a= bar 851638Srgrimes 861638Srgrimes b: 871638Srgrimes echo ${a} 881638Srgrimes 891638Srgrimesthe command "make b" will echo "bar". This is for compatibility with the 901638Srgrimesway the V7 make behaved. 911638Srgrimes 921638SrgrimesIt's fairly difficult to make the BSD .mk files work when you're building 931638Srgrimesmultiple programs in a single directory. It's a lot easier split up the 941638Srgrimesprograms than to deal with the problem. Most of the agony comes from making 951638Srgrimesthe "obj" directory stuff work right, not because we switch to a new version 961638Srgrimesof make. So, don't get mad at us, figure out a better way to handle multiple 971638Srgrimesarchitectures so we can quit using the symbolic link stuff. (Imake doesn't 981638Srgrimescount.) 991638Srgrimes 1001638SrgrimesThe file .depend in the source directory is expected to contain dependencies 1011638Srgrimesfor the source files. This file is read automatically by make after reading 1021638Srgrimesthe Makefile. 1031638Srgrimes 1041638SrgrimesThe variable DESTDIR works as before. It's not set anywhere but will change 1051638Srgrimesthe tree where the file gets installed. 1061638Srgrimes 1071638SrgrimesThe profiled libraries are no longer built in a different directory than 1081638Srgrimesthe regular libraries. A new suffix, ".po", is used to denote a profiled 1091638Srgrimesobject. 1101638Srgrimes 1111638Srgrimes=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 1121638Srgrimes 1131638SrgrimesThe include file <sys.mk> has the default rules for all makes, in the BSD 1141638Srgrimesenvironment or otherwise. You probably don't want to touch this file. 1151638Srgrimes 1161638Srgrimes=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 1171638Srgrimes 1181638SrgrimesThe include file <bsd.man.mk> handles installing manual pages and their 1191638Srgrimeslinks. 1201638Srgrimes 12183075SruIt has three targets: 1221638Srgrimes 12383075Sru all-man: 12483075Sru build manual pages. 1251638Srgrimes maninstall: 12683075Sru install the manual pages and their links. 12783075Sru manlint: 12883075Sru verify the validity of manual pages. 1291638Srgrimes 1301638SrgrimesIt sets/uses the following variables: 1311638Srgrimes 1321638SrgrimesMANDIR Base path for manual installation. 1331638Srgrimes 1341638SrgrimesMANGRP Manual group. 1351638Srgrimes 1361638SrgrimesMANOWN Manual owner. 1371638Srgrimes 1381638SrgrimesMANMODE Manual mode. 1391638Srgrimes 1401638SrgrimesMANSUBDIR Subdirectory under the manual page section, i.e. "/vax" 1411638Srgrimes or "/tahoe" for machine specific manual pages. 1421638Srgrimes 14374942SruMAN The manual pages to be installed (use a .1 - .9 suffix). 1441638Srgrimes 14558494SruMLINKS List of manual page links (using a .1 - .9 suffix). The 1461638Srgrimes linked-to file must come first, the linked file second, 1471638Srgrimes and there may be multiple pairs. The files are soft-linked. 1481638Srgrimes 14974942SruThe include file <bsd.man.mk> includes a file named "../Makefile.inc" if 15074942Sruit exists. 1511638Srgrimes 1521638Srgrimes=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 1531638Srgrimes 1541638SrgrimesThe include file <bsd.own.mk> contains the owners, groups, etc. for both 1551638Srgrimesmanual pages and binaries. 1561638Srgrimes 1571638SrgrimesIt has no targets. 1581638Srgrimes 1591638SrgrimesIt sets/uses the following variables: 1601638Srgrimes 1611638SrgrimesBINGRP Binary group. 1621638Srgrimes 1631638SrgrimesBINOWN Binary owner. 1641638Srgrimes 1651638SrgrimesBINMODE Binary mode. 1661638Srgrimes 1671638SrgrimesMANDIR Base path for manual installation. 1681638Srgrimes 1691638SrgrimesMANGRP Manual group. 1701638Srgrimes 1711638SrgrimesMANOWN Manual owner. 1721638Srgrimes 1731638SrgrimesMANMODE Manual mode. 1741638Srgrimes 1751638SrgrimesThis file is generally useful when building your own Makefiles so that 1761638Srgrimesthey use the same default owners etc. as the rest of the tree. 1771638Srgrimes 1781638Srgrimes=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 1791638Srgrimes 1801638SrgrimesThe include file <bsd.prog.mk> handles building programs from one or 1811638Srgrimesmore source files, along with their manual pages. It has a limited number 1821638Srgrimesof suffixes, consistent with the current needs of the BSD tree. 1831638Srgrimes 1841638SrgrimesIt has seven targets: 1851638Srgrimes 1861638Srgrimes all: 1871638Srgrimes build the program and its manual page 1881638Srgrimes clean: 1891638Srgrimes remove the program, any object files and the files a.out, 1901638Srgrimes Errs, errs, mklog, and ${PROG}.core. 1911638Srgrimes cleandir: 1921638Srgrimes remove all of the files removed by the target clean, as 1931638Srgrimes well as .depend, tags, and any manual pages. 1941638Srgrimes depend: 1951638Srgrimes make the dependencies for the source files, and store 1961638Srgrimes them in the file .depend. 1971638Srgrimes install: 1981638Srgrimes install the program and its manual pages; if the Makefile 1991638Srgrimes does not itself define the target install, the targets 2001638Srgrimes beforeinstall and afterinstall may also be used to cause 2011638Srgrimes actions immediately before and after the install target 2021638Srgrimes is executed. 2031638Srgrimes lint: 2041638Srgrimes run lint on the source files 2051638Srgrimes tags: 2061638Srgrimes create a tags file for the source files. 2071638Srgrimes 2081638SrgrimesIt sets/uses the following variables: 2091638Srgrimes 2101638SrgrimesBINGRP Binary group. 2111638Srgrimes 2121638SrgrimesBINOWN Binary owner. 2131638Srgrimes 2141638SrgrimesBINMODE Binary mode. 2151638Srgrimes 21616437SphkCLEANFILES Additional files to remove and 21716437SphkCLEANDIRS additional directories to remove during clean and cleandir 21816437Sphk targets. "rm -f" and "rm -rf" used respectively. 2191638Srgrimes 2201638SrgrimesCOPTS Additional flags to the compiler when creating C objects. 2211638Srgrimes 22288055SruFILES A list of non-executable files. 22388055Sru The installation is controlled by the FILESNAME, FILESOWN, 22488055Sru FILESGRP, FILESMODE, FILESDIR variables that can be 22588055Sru further specialized by FILES<VAR>_<file>. 22688055Sru 2271638SrgrimesLDADD Additional loader objects. Usually used for libraries. 2281638Srgrimes For example, to load with the compatibility and utility 2291638Srgrimes libraries, use: 2301638Srgrimes 2311638Srgrimes LDFILES=-lutil -lcompat 2321638Srgrimes 2331638SrgrimesLDFLAGS Additional loader flags. 2341638Srgrimes 2351638SrgrimesLINKS The list of binary links; should be full pathnames, the 2361638Srgrimes linked-to file coming first, followed by the linked 2371638Srgrimes file. The files are hard-linked. For example, to link 2381638Srgrimes /bin/test and /bin/[, use: 2391638Srgrimes 2401638Srgrimes LINKS= ${DESTDIR}/bin/test ${DESTDIR}/bin/[ 2411638Srgrimes 24274942SruMAN Manual pages (should end in .1 - .9). If no MAN variable 24374942Sru is defined, "MAN=${PROG}.1" is assumed. 2441638Srgrimes 2451638SrgrimesPROG The name of the program to build. If not supplied, nothing 2461638Srgrimes is built. 2471638Srgrimes 24894424SruPROG_CXX If defined, the name of the program to build. Also 24994424Sru causes <bsd.prog.mk> to link the program with the 25094424Sru standard C++ library. PROG_CXX overrides the value 25194424Sru of PROG if PROG is also set. 25294424Sru 25375083SruPROGNAME The name that the above program will be installed as, if 25475083Sru different from ${PROG}. 25575083Sru 25653965SmharoSRCS List of source files to build the program. If SRCS is not 25794424Sru defined, it's assumed to be ${PROG}.c or, if PROG_CXX is 25894424Sru defined, ${PROG_CXX}.cc. 2591638Srgrimes 2601638SrgrimesDPADD Additional dependencies for the program. Usually used for 2611638Srgrimes libraries. For example, to depend on the compatibility and 2621638Srgrimes utility libraries use: 2631638Srgrimes 2641638Srgrimes SRCLIB=${LIBCOMPAT} ${LIBUTIL} 2651638Srgrimes 26614701Sbde There is a predefined identifier for each (non-profiled, 26714701Sbde non-shared) library and object. Library file names are 26814701Sbde transformed to identifiers by removing the extension and 26914701Sbde converting to upper case. 2701638Srgrimes 27114701Sbde There are no special identifiers for profiled or shared 27214701Sbde libraries or objects. The identifiers for the standard 27314701Sbde libraries are used in DPADD. This works correctly iff all 27414701Sbde the libraries are built at the same time. Unfortunately, 27514701Sbde it causes unnecessary relinks to shared libraries when 27614701Sbde only the static libraries have changed. Dependencies on 27714701Sbde shared libraries should be only on the library version 27814701Sbde numbers. 2791638Srgrimes 2801638SrgrimesSTRIP The flag passed to the install program to cause the binary 281125493Sru to be stripped. This is to be used when building your 282125493Sru own install script so that the entire system can be made 283125493Sru stripped/not-stripped using a single nob. 2841638Srgrimes 2851638SrgrimesSUBDIR A list of subdirectories that should be built as well. 2861638Srgrimes Each of the targets will execute the same target in the 2871638Srgrimes subdirectories. 2881638Srgrimes 28975284SruSCRIPTS A list of interpreter scripts [file.{sh,csh,pl,awk,...}]. 29075284Sru The installation is controlled by the SCRIPTSNAME, SCRIPTSOWN, 29175284Sru SCRIPTSGRP, SCRIPTSMODE, SCRIPTSDIR variables that can be 29275284Sru further specialized by SCRIPTS<VAR>_<script>. 29375284Sru 29474942SruThe include file <bsd.prog.mk> includes the file named "../Makefile.inc" 29574942Sruif it exists, as well as the include file <bsd.man.mk>. 2961638Srgrimes 2971638SrgrimesSome simple examples: 2981638Srgrimes 2991638SrgrimesTo build foo from foo.c with a manual page foo.1, use: 3001638Srgrimes 3011638Srgrimes PROG= foo 3021638Srgrimes 3031638Srgrimes .include <bsd.prog.mk> 3041638Srgrimes 3051638SrgrimesTo build foo from foo.c with a manual page foo.2, add the line: 3061638Srgrimes 30758494Sru MAN2= foo.2 3081638Srgrimes 3091638SrgrimesIf foo does not have a manual page at all, add the line: 3101638Srgrimes 3111638Srgrimes NOMAN= noman 3121638Srgrimes 3131638SrgrimesIf foo has multiple source files, add the line: 3141638Srgrimes 3151638Srgrimes SRCS= a.c b.c c.c d.c 3161638Srgrimes 3171638Srgrimes=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 3181638Srgrimes 3191638SrgrimesThe include file <bsd.subdir.mk> contains the default targets for building 3201638Srgrimessubdirectories. It has the same seven targets as <bsd.prog.mk>: all, clean, 3211638Srgrimescleandir, depend, install, lint, and tags. For all of the directories 3221638Srgrimeslisted in the variable SUBDIRS, the specified directory will be visited 3231638Srgrimesand the target made. There is also a default target which allows the 3241638Srgrimescommand "make subdir" where subdir is any directory listed in the variable 3251638SrgrimesSUBDIRS. 3261638Srgrimes 3271638Srgrimes=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 3281638Srgrimes 3291638SrgrimesThe include file <bsd.lib.mk> has support for building libraries. It has 3301638Srgrimesthe same seven targets as <bsd.prog.mk>: all, clean, cleandir, depend, 3311638Srgrimesinstall, lint, and tags. It has a limited number of suffixes, consistent 3321638Srgrimeswith the current needs of the BSD tree. 3331638Srgrimes 3341638SrgrimesIt sets/uses the following variables: 3351638Srgrimes 3361638SrgrimesLIBDIR Target directory for libraries. 3371638Srgrimes 3381638SrgrimesLINTLIBDIR Target directory for lint libraries. 3391638Srgrimes 3401638SrgrimesLIBGRP Library group. 3411638Srgrimes 3421638SrgrimesLIBOWN Library owner. 3431638Srgrimes 3441638SrgrimesLIBMODE Library mode. 3451638Srgrimes 3461638SrgrimesLDADD Additional loader objects. 3471638Srgrimes 34874942SruMAN The manual pages to be installed (use a .1 - .9 suffix). 3491638Srgrimes 3501638SrgrimesSRCS List of source files to build the library. Suffix types 3511638Srgrimes .s, .c, and .f are supported. Note, .s files are preferred 3521638Srgrimes to .c files of the same name. (This is not the default for 3531638Srgrimes versions of make.) 3541638Srgrimes 35574942SruThe include file <bsd.lib.mk> includes the file named "../Makefile.inc" 35674942Sruif it exists, as well as the include file <bsd.man.mk>. 3571638Srgrimes 3581638SrgrimesIt has rules for building profiled objects; profiled libraries are 3591638Srgrimesbuilt by default. 3601638Srgrimes 3611638SrgrimesLibraries are ranlib'd before installation. 362