11638Srgrimes# @(#)bsd.README 8.2 (Berkeley) 4/2/94 250476Speter# $FreeBSD$ 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 39152265Shartibsd.snmpmod.mk - building modules for the SNMP daemon bsnmpd 4023559Swoschbsd.subdir.mk - targets for building subdirectories 41115103Strhodesbsd.sys.mk - common settings used for building FreeBSD sources 42264483Sjmmvbsd.test.mk - building test programs from source files 43115103Strhodessys.mk - default rules for all makes 4423559Swosch 45115103StrhodesThis file does not document bsd.port*.mk. They are documented in ports(7). 4623559Swosch 47115103StrhodesSee also make(1), mkdep(1), style.Makefile(5) and `PMake - A 48115103StrhodesTutorial', located in /usr/share/doc/psd/12.make. 491638Srgrimes 50115103Strhodes=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 5123578Swosch 52115103StrhodesRandom things worth knowing about this document: 53115103Strhodes 54115103StrhodesIf appropriate when documenting the variables the default value is 55115103Strhodesindicated using square brackets e.g. [gzip]. 56115103StrhodesIn some cases the default value depend on other values (e.g. system 57115103Strhodesarchitecture). In these cases the most common value is indicated. 58115103Strhodes 59115103StrhodesThis document contains some simple examples of the usage of the BSD make 60115103Strhodesinclude files. For more examples look at the makefiles in the FreeBSD 61115103Strhodessource tree. 62115103Strhodes 631638Srgrimes=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 641638Srgrimes 651638SrgrimesRANDOM THINGS WORTH KNOWING: 661638Srgrimes 67115103StrhodesThe files are like C-style #include files, and pretty much behave like 681638Srgrimesyou'd expect. The syntax is slightly different in that a single '.' is 691638Srgrimesused instead of the hash mark, i.e. ".include <bsd.prog.mk>". 701638Srgrimes 711638SrgrimesOne difference that will save you lots of debugging time is that inclusion 721638Srgrimesof the file is normally done at the *end* of the Makefile. The reason for 731638Srgrimesthis is because .mk files often modify variables and behavior based on the 741638Srgrimesvalues of variables set in the Makefile. To make this work, remember that 751638Srgrimesthe FIRST target found is the target that is used, i.e. if the Makefile has: 761638Srgrimes 771638Srgrimes a: 781638Srgrimes echo a 791638Srgrimes a: 801638Srgrimes echo a number two 811638Srgrimes 821638Srgrimesthe command "make a" will echo "a". To make things confusing, the SECOND 831638Srgrimesvariable assignment is the overriding one, i.e. if the Makefile has: 841638Srgrimes 851638Srgrimes a= foo 861638Srgrimes a= bar 871638Srgrimes 881638Srgrimes b: 891638Srgrimes echo ${a} 901638Srgrimes 911638Srgrimesthe command "make b" will echo "bar". This is for compatibility with the 921638Srgrimesway the V7 make behaved. 931638Srgrimes 941638SrgrimesIt's fairly difficult to make the BSD .mk files work when you're building 95208420Smaximmultiple programs in a single directory. It's a lot easier to split up 96208420Smaximthe programs than to deal with the problem. Most of the agony comes from 97208420Smaximmaking the "obj" directory stuff work right, not because we switch to a new 98208420Smaximversion of make. So, don't get mad at us, figure out a better way to handle 99208420Smaximmultiple architectures so we can quit using the symbolic link stuff. 100208417Smaxim(Imake doesn't count.) 1011638Srgrimes 1021638SrgrimesThe file .depend in the source directory is expected to contain dependencies 1031638Srgrimesfor the source files. This file is read automatically by make after reading 1041638Srgrimesthe Makefile. 1051638Srgrimes 1061638SrgrimesThe variable DESTDIR works as before. It's not set anywhere but will change 1071638Srgrimesthe tree where the file gets installed. 1081638Srgrimes 1091638SrgrimesThe profiled libraries are no longer built in a different directory than 1101638Srgrimesthe regular libraries. A new suffix, ".po", is used to denote a profiled 1111638Srgrimesobject. 1121638Srgrimes 1131638Srgrimes=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 1141638Srgrimes 1151638SrgrimesThe include file <sys.mk> has the default rules for all makes, in the BSD 1161638Srgrimesenvironment or otherwise. You probably don't want to touch this file. 1171638Srgrimes 1181638Srgrimes=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 1191638Srgrimes 1201638SrgrimesThe include file <bsd.man.mk> handles installing manual pages and their 1211638Srgrimeslinks. 1221638Srgrimes 12383075SruIt has three targets: 1241638Srgrimes 12583075Sru all-man: 12683075Sru build manual pages. 1271638Srgrimes maninstall: 12883075Sru install the manual pages and their links. 12983075Sru manlint: 13083075Sru verify the validity of manual pages. 1311638Srgrimes 1321638SrgrimesIt sets/uses the following variables: 1331638Srgrimes 1341638SrgrimesMANDIR Base path for manual installation. 1351638Srgrimes 1361638SrgrimesMANGRP Manual group. 1371638Srgrimes 1381638SrgrimesMANOWN Manual owner. 1391638Srgrimes 1401638SrgrimesMANMODE Manual mode. 1411638Srgrimes 1421638SrgrimesMANSUBDIR Subdirectory under the manual page section, i.e. "/vax" 1431638Srgrimes or "/tahoe" for machine specific manual pages. 1441638Srgrimes 14574942SruMAN The manual pages to be installed (use a .1 - .9 suffix). 1461638Srgrimes 14758494SruMLINKS List of manual page links (using a .1 - .9 suffix). The 1481638Srgrimes linked-to file must come first, the linked file second, 1491638Srgrimes and there may be multiple pairs. The files are soft-linked. 1501638Srgrimes 15174942SruThe include file <bsd.man.mk> includes a file named "../Makefile.inc" if 15274942Sruit exists. 1531638Srgrimes 1541638Srgrimes=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 1551638Srgrimes 1561638SrgrimesThe include file <bsd.own.mk> contains the owners, groups, etc. for both 1571638Srgrimesmanual pages and binaries. 1581638Srgrimes 1591638SrgrimesIt has no targets. 1601638Srgrimes 1611638SrgrimesIt sets/uses the following variables: 1621638Srgrimes 1631638SrgrimesBINGRP Binary group. 1641638Srgrimes 1651638SrgrimesBINOWN Binary owner. 1661638Srgrimes 1671638SrgrimesBINMODE Binary mode. 1681638Srgrimes 1691638SrgrimesMANDIR Base path for manual installation. 1701638Srgrimes 1711638SrgrimesMANGRP Manual group. 1721638Srgrimes 1731638SrgrimesMANOWN Manual owner. 1741638Srgrimes 1751638SrgrimesMANMODE Manual mode. 1761638Srgrimes 1771638SrgrimesThis file is generally useful when building your own Makefiles so that 1781638Srgrimesthey use the same default owners etc. as the rest of the tree. 1791638Srgrimes 1801638Srgrimes=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 1811638Srgrimes 1821638SrgrimesThe include file <bsd.prog.mk> handles building programs from one or 1831638Srgrimesmore source files, along with their manual pages. It has a limited number 1841638Srgrimesof suffixes, consistent with the current needs of the BSD tree. 1851638Srgrimes 1861638SrgrimesIt has seven targets: 1871638Srgrimes 1881638Srgrimes all: 1891638Srgrimes build the program and its manual page 1901638Srgrimes clean: 191159721Syar remove the program and any object files. 1921638Srgrimes cleandir: 1931638Srgrimes remove all of the files removed by the target clean, as 1941638Srgrimes well as .depend, tags, and any manual pages. 1951638Srgrimes depend: 1961638Srgrimes make the dependencies for the source files, and store 1971638Srgrimes them in the file .depend. 1981638Srgrimes install: 1991638Srgrimes install the program and its manual pages; if the Makefile 2001638Srgrimes does not itself define the target install, the targets 2011638Srgrimes beforeinstall and afterinstall may also be used to cause 2021638Srgrimes actions immediately before and after the install target 2031638Srgrimes is executed. 2041638Srgrimes lint: 2051638Srgrimes run lint on the source files 2061638Srgrimes tags: 2071638Srgrimes create a tags file for the source files. 2081638Srgrimes 2091638SrgrimesIt sets/uses the following variables: 2101638Srgrimes 2111638SrgrimesBINGRP Binary group. 2121638Srgrimes 2131638SrgrimesBINOWN Binary owner. 2141638Srgrimes 2151638SrgrimesBINMODE Binary mode. 2161638Srgrimes 21716437SphkCLEANFILES Additional files to remove and 21816437SphkCLEANDIRS additional directories to remove during clean and cleandir 21916437Sphk targets. "rm -f" and "rm -rf" used respectively. 2201638Srgrimes 221133653SruCFLAGS Flags to the compiler when creating C objects. 2221638Srgrimes 22388055SruFILES A list of non-executable files. 22488055Sru The installation is controlled by the FILESNAME, FILESOWN, 22588055Sru FILESGRP, FILESMODE, FILESDIR variables that can be 22688055Sru further specialized by FILES<VAR>_<file>. 22788055Sru 2281638SrgrimesLDADD Additional loader objects. Usually used for libraries. 2291638Srgrimes For example, to load with the compatibility and utility 2301638Srgrimes libraries, use: 2311638Srgrimes 232235928Smarcel LDADD=-lutil -lcompat 2331638Srgrimes 2341638SrgrimesLDFLAGS Additional loader flags. 2351638Srgrimes 2361638SrgrimesLINKS The list of binary links; should be full pathnames, the 2371638Srgrimes linked-to file coming first, followed by the linked 2381638Srgrimes file. The files are hard-linked. For example, to link 2391638Srgrimes /bin/test and /bin/[, use: 2401638Srgrimes 2411638Srgrimes LINKS= ${DESTDIR}/bin/test ${DESTDIR}/bin/[ 2421638Srgrimes 24374942SruMAN Manual pages (should end in .1 - .9). If no MAN variable 24474942Sru is defined, "MAN=${PROG}.1" is assumed. 2451638Srgrimes 2461638SrgrimesPROG The name of the program to build. If not supplied, nothing 2471638Srgrimes is built. 2481638Srgrimes 24994424SruPROG_CXX If defined, the name of the program to build. Also 25094424Sru causes <bsd.prog.mk> to link the program with the 25194424Sru standard C++ library. PROG_CXX overrides the value 25294424Sru of PROG if PROG is also set. 25394424Sru 25475083SruPROGNAME The name that the above program will be installed as, if 25575083Sru different from ${PROG}. 25675083Sru 25753965SmharoSRCS List of source files to build the program. If SRCS is not 25894424Sru defined, it's assumed to be ${PROG}.c or, if PROG_CXX is 25994424Sru defined, ${PROG_CXX}.cc. 2601638Srgrimes 2611638SrgrimesDPADD Additional dependencies for the program. Usually used for 2621638Srgrimes libraries. For example, to depend on the compatibility and 2631638Srgrimes utility libraries use: 2641638Srgrimes 265235928Smarcel DPADD=${LIBCOMPAT} ${LIBUTIL} 2661638Srgrimes 26714701Sbde There is a predefined identifier for each (non-profiled, 26814701Sbde non-shared) library and object. Library file names are 26914701Sbde transformed to identifiers by removing the extension and 27014701Sbde converting to upper case. 2711638Srgrimes 27214701Sbde There are no special identifiers for profiled or shared 27314701Sbde libraries or objects. The identifiers for the standard 27414701Sbde libraries are used in DPADD. This works correctly iff all 27514701Sbde the libraries are built at the same time. Unfortunately, 27614701Sbde it causes unnecessary relinks to shared libraries when 27714701Sbde only the static libraries have changed. Dependencies on 27814701Sbde shared libraries should be only on the library version 27914701Sbde numbers. 2801638Srgrimes 2811638SrgrimesSTRIP The flag passed to the install program to cause the binary 282125493Sru to be stripped. This is to be used when building your 283125493Sru own install script so that the entire system can be made 284125493Sru stripped/not-stripped using a single nob. 2851638Srgrimes 2861638SrgrimesSUBDIR A list of subdirectories that should be built as well. 2871638Srgrimes Each of the targets will execute the same target in the 2881638Srgrimes subdirectories. 2891638Srgrimes 29075284SruSCRIPTS A list of interpreter scripts [file.{sh,csh,pl,awk,...}]. 29175284Sru The installation is controlled by the SCRIPTSNAME, SCRIPTSOWN, 29275284Sru SCRIPTSGRP, SCRIPTSMODE, SCRIPTSDIR variables that can be 29375284Sru further specialized by SCRIPTS<VAR>_<script>. 29475284Sru 29574942SruThe include file <bsd.prog.mk> includes the file named "../Makefile.inc" 29674942Sruif it exists, as well as the include file <bsd.man.mk>. 2971638Srgrimes 2981638SrgrimesSome simple examples: 2991638Srgrimes 3001638SrgrimesTo build foo from foo.c with a manual page foo.1, use: 3011638Srgrimes 3021638Srgrimes PROG= foo 3031638Srgrimes 3041638Srgrimes .include <bsd.prog.mk> 3051638Srgrimes 3061638SrgrimesTo build foo from foo.c with a manual page foo.2, add the line: 3071638Srgrimes 308156743Sru MAN= foo.2 3091638Srgrimes 3101638SrgrimesIf foo does not have a manual page at all, add the line: 3111638Srgrimes 312156502Simp NO_MAN= 3131638Srgrimes 3141638SrgrimesIf foo has multiple source files, add the line: 3151638Srgrimes 3161638Srgrimes SRCS= a.c b.c c.c d.c 3171638Srgrimes 3181638Srgrimes=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 3191638Srgrimes 3201638SrgrimesThe include file <bsd.subdir.mk> contains the default targets for building 3211638Srgrimessubdirectories. It has the same seven targets as <bsd.prog.mk>: all, clean, 3221638Srgrimescleandir, depend, install, lint, and tags. For all of the directories 3231638Srgrimeslisted in the variable SUBDIRS, the specified directory will be visited 3241638Srgrimesand the target made. There is also a default target which allows the 3251638Srgrimescommand "make subdir" where subdir is any directory listed in the variable 3261638SrgrimesSUBDIRS. 3271638Srgrimes 3281638Srgrimes=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 3291638Srgrimes 3301638SrgrimesThe include file <bsd.lib.mk> has support for building libraries. It has 3311638Srgrimesthe same seven targets as <bsd.prog.mk>: all, clean, cleandir, depend, 3321638Srgrimesinstall, lint, and tags. It has a limited number of suffixes, consistent 3331638Srgrimeswith the current needs of the BSD tree. 3341638Srgrimes 3351638SrgrimesIt sets/uses the following variables: 3361638Srgrimes 3371638SrgrimesLIBDIR Target directory for libraries. 3381638Srgrimes 3391638SrgrimesLINTLIBDIR Target directory for lint libraries. 3401638Srgrimes 3411638SrgrimesLIBGRP Library group. 3421638Srgrimes 3431638SrgrimesLIBOWN Library owner. 3441638Srgrimes 3451638SrgrimesLIBMODE Library mode. 3461638Srgrimes 3471638SrgrimesLDADD Additional loader objects. 3481638Srgrimes 34974942SruMAN The manual pages to be installed (use a .1 - .9 suffix). 3501638Srgrimes 3511638SrgrimesSRCS List of source files to build the library. Suffix types 3521638Srgrimes .s, .c, and .f are supported. Note, .s files are preferred 3531638Srgrimes to .c files of the same name. (This is not the default for 3541638Srgrimes versions of make.) 3551638Srgrimes 356235122SjlhSHLIB_LDSCRIPT Template file to generate shared library linker script. 357235122Sjlh Unless used, a simple symlink is created to the real 358235122Sjlh shared object. 359235122Sjlh 360245561SbrooksLIBRARIES_ONLY Do not build or install files other than the library. 361245561Sbrooks 36274942SruThe include file <bsd.lib.mk> includes the file named "../Makefile.inc" 36374942Sruif it exists, as well as the include file <bsd.man.mk>. 3641638Srgrimes 3651638SrgrimesIt has rules for building profiled objects; profiled libraries are 3661638Srgrimesbuilt by default. 3671638Srgrimes 3681638SrgrimesLibraries are ranlib'd before installation. 369264483Sjmmv 370264483Sjmmv=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 371264483Sjmmv 372264483SjmmvThe include file <bsd.test.mk> handles building one or more test programs 373264483Sjmmvintended to be used in the FreeBSD Test Suite under /usr/tests/. 374264483Sjmmv 375264483SjmmvIt has seven targets: 376264483Sjmmv 377264483Sjmmv all: 378264483Sjmmv build the test programs. 379264483Sjmmv clean: 380264483Sjmmv remove the test programs and any object files. 381264483Sjmmv cleandir: 382264483Sjmmv remove all of the files removed by the target clean, as 383264483Sjmmv well as .depend and tags. 384264483Sjmmv depend: 385264483Sjmmv make the dependencies for the source files, and store 386264483Sjmmv them in the file .depend. 387264483Sjmmv install: 388264483Sjmmv install the test programs and their data files; if the 389264483Sjmmv Makefile does not itself define the target install, the 390264483Sjmmv targets beforeinstall and afterinstall may also be used 391264483Sjmmv to cause actions immediately before and after the 392264483Sjmmv install target is executed. 393264483Sjmmv lint: 394264483Sjmmv run lint on the source files. 395264483Sjmmv tags: 396264483Sjmmv create a tags file for the source files. 397264483Sjmmv test: 398264483Sjmmv runs the test programs from the object directory; if the 399264483Sjmmv Makefile does not itself define the target test, the 400264483Sjmmv targets beforetest and aftertest may also be used to 401264483Sjmmv cause actions immediately before and after the test 402264483Sjmmv target is executed. 403264483Sjmmv 404264483SjmmvIt sets/uses the following variables, among many others: 405264483Sjmmv 406264483SjmmvTESTDIR Path to the installed tests. Must be a subdirectory of 407264483Sjmmv TESTSBASE and the subpath should match the relative 408264483Sjmmv location of the tests within the src tree. 409264483Sjmmv 410264483SjmmvKYUAFILE If 'auto' (the default), generate a Kyuafile out of the 411264483Sjmmv test programs defined in the Makefile. If 'yes', then a 412264483Sjmmv manually-crafted Kyuafile must be supplied with the 413264483Sjmmv sources. If 'no', no Kyuafile is installed (useful for 414264483Sjmmv subdirectories providing helper programs or data files 415264483Sjmmv only). 416264483Sjmmv 417264483SjmmvATF_TESTS_C The names of the ATF C test programs to build. 418264483Sjmmv 419264483SjmmvATF_TESTS_CXX The names of the ATF C++ test programs to build. 420264483Sjmmv 421264483SjmmvATF_TESTS_SH The names of the ATF sh test programs to build. 422264483Sjmmv 423264483SjmmvPLAIN_TESTS_C The names of the plain (legacy) programs to build. 424264483Sjmmv 425264483SjmmvPLAIN_TESTS_CXX The names of the plain (legacy) test programs to build. 426264483Sjmmv 427264483SjmmvPLAIN_TESTS_SH The names of the plain (legacy) test programs to build. 428264483Sjmmv 429264483SjmmvTAP_PERL_INTERPRETER 430264483Sjmmv Path to the Perl interpreter to be used for 431264483Sjmmv TAP-compliant test programs that are written in Perl. 432264483Sjmmv Refer to TAP_TESTS_PERL for details. 433264483Sjmmv 434264483SjmmvTAP_TESTS_C The names of the TAP-compliant C test programs to build. 435264483Sjmmv 436264483SjmmvTAP_TESTS_CXX The names of the TAP-compliant C++ test programs to 437264483Sjmmv build. 438264483Sjmmv 439264483SjmmvTAP_TESTS_PERL The names of the TAP-compliant Perl test programs to 440264483Sjmmv build. The corresponding source files should end with 441264483Sjmmv the .pl extension; the test program is marked as 442264483Sjmmv requiring Perl; and TAP_PERL_INTERPRETER is used in the 443264483Sjmmv built scripts as the interpreter of choice. 444264483Sjmmv 445264483SjmmvTAP_TESTS_SH The names of the TAP-compliant sh test programs to 446264483Sjmmv build. 447264483Sjmmv 448264483SjmmvTESTS_SUBDIRS List of subdirectories containing tests into which to 449264483Sjmmv recurse. Differs from SUBDIR in that these directories 450264483Sjmmv get registered into the automatically-generated 451264483Sjmmv Kyuafile (if any). 452264483Sjmmv 453264483SjmmvNOT_FOR_TEST_SUITE 454264483Sjmmv If defined, none of the built test programs get 455264483Sjmmv installed under /usr/tests/ and no Kyuafile is 456264483Sjmmv automatically generated. Should not be used within the 457264483Sjmmv FreeBSD source tree but is provided for the benefit of 458264483Sjmmv third-parties. 459264483Sjmmv 460264483SjmmvThe actual building of the test programs is performed by <bsd.prog.mk>. 461264483SjmmvPlease see the documentation above for this other file for additional 462264483Sjmmvdetails on the behavior of <bsd.test.mk>. 463