bsd.README revision 14701
11638Srgrimes# @(#)bsd.README 8.2 (Berkeley) 4/2/94 21638Srgrimes 33470SrgrimesXXX This document is seriously out of date, it is currenly being revised. 43470Srgrimes 53470Srgrimes Rod Grimes <rgrimes@freebsd.org> 63470Srgrimes 71638SrgrimesThis is the README file for the new make "include" files for the BSD 81638Srgrimessource tree. The files are installed in /usr/share/mk, and are, by 91638Srgrimesconvention, named with the suffix ".mk". Each ".mk" file has a 101638Srgrimescorresponding ".rd" file which is an explanation of the ".mk" file. 111638Srgrimes 121638SrgrimesNote, this file is not intended to replace reading through the .mk 131638Srgrimesfiles for anything tricky. 141638Srgrimes 151638Srgrimes=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 161638Srgrimes 171638SrgrimesRANDOM THINGS WORTH KNOWING: 181638Srgrimes 191638SrgrimesThe files are simply C-style #include files, and pretty much behave like 201638Srgrimesyou'd expect. The syntax is slightly different in that a single '.' is 211638Srgrimesused instead of the hash mark, i.e. ".include <bsd.prog.mk>". 221638Srgrimes 231638SrgrimesOne difference that will save you lots of debugging time is that inclusion 241638Srgrimesof the file is normally done at the *end* of the Makefile. The reason for 251638Srgrimesthis is because .mk files often modify variables and behavior based on the 261638Srgrimesvalues of variables set in the Makefile. To make this work, remember that 271638Srgrimesthe FIRST target found is the target that is used, i.e. if the Makefile has: 281638Srgrimes 291638Srgrimes a: 301638Srgrimes echo a 311638Srgrimes a: 321638Srgrimes echo a number two 331638Srgrimes 341638Srgrimesthe command "make a" will echo "a". To make things confusing, the SECOND 351638Srgrimesvariable assignment is the overriding one, i.e. if the Makefile has: 361638Srgrimes 371638Srgrimes a= foo 381638Srgrimes a= bar 391638Srgrimes 401638Srgrimes b: 411638Srgrimes echo ${a} 421638Srgrimes 431638Srgrimesthe command "make b" will echo "bar". This is for compatibility with the 441638Srgrimesway the V7 make behaved. 451638Srgrimes 461638SrgrimesIt's fairly difficult to make the BSD .mk files work when you're building 471638Srgrimesmultiple programs in a single directory. It's a lot easier split up the 481638Srgrimesprograms than to deal with the problem. Most of the agony comes from making 491638Srgrimesthe "obj" directory stuff work right, not because we switch to a new version 501638Srgrimesof make. So, don't get mad at us, figure out a better way to handle multiple 511638Srgrimesarchitectures so we can quit using the symbolic link stuff. (Imake doesn't 521638Srgrimescount.) 531638Srgrimes 541638SrgrimesThe file .depend in the source directory is expected to contain dependencies 551638Srgrimesfor the source files. This file is read automatically by make after reading 561638Srgrimesthe Makefile. 571638Srgrimes 581638SrgrimesThe variable DESTDIR works as before. It's not set anywhere but will change 591638Srgrimesthe tree where the file gets installed. 601638Srgrimes 611638SrgrimesThe profiled libraries are no longer built in a different directory than 621638Srgrimesthe regular libraries. A new suffix, ".po", is used to denote a profiled 631638Srgrimesobject. 641638Srgrimes 651638Srgrimes=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 661638Srgrimes 671638SrgrimesThe include file <sys.mk> has the default rules for all makes, in the BSD 681638Srgrimesenvironment or otherwise. You probably don't want to touch this file. 691638Srgrimes 701638Srgrimes=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 711638Srgrimes 721638SrgrimesThe include file <bsd.man.mk> handles installing manual pages and their 731638Srgrimeslinks. 741638Srgrimes 751638SrgrimesIt has a single target: 761638Srgrimes 771638Srgrimes maninstall: 781638Srgrimes Install the manual pages and their links. 791638Srgrimes 801638SrgrimesIt sets/uses the following variables: 811638Srgrimes 821638SrgrimesMANDIR Base path for manual installation. 831638Srgrimes 841638SrgrimesMANGRP Manual group. 851638Srgrimes 861638SrgrimesMANOWN Manual owner. 871638Srgrimes 881638SrgrimesMANMODE Manual mode. 891638Srgrimes 901638SrgrimesMANSUBDIR Subdirectory under the manual page section, i.e. "/vax" 911638Srgrimes or "/tahoe" for machine specific manual pages. 921638Srgrimes 931638SrgrimesMAN1 ... MAN8 The manual pages to be installed (use a .0 suffix). 941638Srgrimes 951638SrgrimesMLINKS List of manual page links (using a .1 - .8 suffix). The 961638Srgrimes linked-to file must come first, the linked file second, 971638Srgrimes and there may be multiple pairs. The files are soft-linked. 981638Srgrimes 993470SrgrimesThe include file <bsd.man.mk> includes the include file <bsd.inc.mk>. 1001638Srgrimes 1011638Srgrimes=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 1021638Srgrimes 1031638SrgrimesThe include file <bsd.own.mk> contains the owners, groups, etc. for both 1041638Srgrimesmanual pages and binaries. 1051638Srgrimes 1061638SrgrimesIt has no targets. 1071638Srgrimes 1081638SrgrimesIt sets/uses the following variables: 1091638Srgrimes 1101638SrgrimesBINGRP Binary group. 1111638Srgrimes 1121638SrgrimesBINOWN Binary owner. 1131638Srgrimes 1141638SrgrimesBINMODE Binary mode. 1151638Srgrimes 1161638SrgrimesSTRIP The flag passed to the install program to cause the binary 1171638Srgrimes to be stripped. This is to be used when building your 1181638Srgrimes own install script so that the entire system can be made 1191638Srgrimes stripped/not-stripped using a single nob. 1201638Srgrimes 1211638SrgrimesMANDIR Base path for manual installation. 1221638Srgrimes 1231638SrgrimesMANGRP Manual group. 1241638Srgrimes 1251638SrgrimesMANOWN Manual owner. 1261638Srgrimes 1271638SrgrimesMANMODE Manual mode. 1281638Srgrimes 1291638SrgrimesThis file is generally useful when building your own Makefiles so that 1301638Srgrimesthey use the same default owners etc. as the rest of the tree. 1311638Srgrimes 1321638Srgrimes=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 1331638Srgrimes 1341638SrgrimesThe include file <bsd.prog.mk> handles building programs from one or 1351638Srgrimesmore source files, along with their manual pages. It has a limited number 1361638Srgrimesof suffixes, consistent with the current needs of the BSD tree. 1371638Srgrimes 1381638SrgrimesIt has seven targets: 1391638Srgrimes 1401638Srgrimes all: 1411638Srgrimes build the program and its manual page 1421638Srgrimes clean: 1431638Srgrimes remove the program, any object files and the files a.out, 1441638Srgrimes Errs, errs, mklog, and ${PROG}.core. 1451638Srgrimes cleandir: 1461638Srgrimes remove all of the files removed by the target clean, as 1471638Srgrimes well as .depend, tags, and any manual pages. 1481638Srgrimes depend: 1491638Srgrimes make the dependencies for the source files, and store 1501638Srgrimes them in the file .depend. 1511638Srgrimes install: 1521638Srgrimes install the program and its manual pages; if the Makefile 1531638Srgrimes does not itself define the target install, the targets 1541638Srgrimes beforeinstall and afterinstall may also be used to cause 1551638Srgrimes actions immediately before and after the install target 1561638Srgrimes is executed. 1571638Srgrimes lint: 1581638Srgrimes run lint on the source files 1591638Srgrimes tags: 1601638Srgrimes create a tags file for the source files. 1611638Srgrimes 1621638SrgrimesIt sets/uses the following variables: 1631638Srgrimes 1641638SrgrimesBINGRP Binary group. 1651638Srgrimes 1661638SrgrimesBINOWN Binary owner. 1671638Srgrimes 1681638SrgrimesBINMODE Binary mode. 1691638Srgrimes 1701638SrgrimesCLEANFILES Additional files to remove for the clean and cleandir targets. 1711638Srgrimes 1721638SrgrimesCOPTS Additional flags to the compiler when creating C objects. 1731638Srgrimes 1741638SrgrimesHIDEGAME If HIDEGAME is defined, the binary is installed in 1751638Srgrimes /usr/games/hide, and a symbolic link is created to 1761638Srgrimes /usr/games/dm. 1771638Srgrimes 1781638SrgrimesLDADD Additional loader objects. Usually used for libraries. 1791638Srgrimes For example, to load with the compatibility and utility 1801638Srgrimes libraries, use: 1811638Srgrimes 1821638Srgrimes LDFILES=-lutil -lcompat 1831638Srgrimes 1841638SrgrimesLDFLAGS Additional loader flags. 1851638Srgrimes 1861638SrgrimesLINKS The list of binary links; should be full pathnames, the 1871638Srgrimes linked-to file coming first, followed by the linked 1881638Srgrimes file. The files are hard-linked. For example, to link 1891638Srgrimes /bin/test and /bin/[, use: 1901638Srgrimes 1911638Srgrimes LINKS= ${DESTDIR}/bin/test ${DESTDIR}/bin/[ 1921638Srgrimes 1931638SrgrimesMAN1...MAN8 Manual pages (should end in .0). If no MAN variable is 1941638Srgrimes defined, "MAN1=${PROG}.0" is assumed. 1951638Srgrimes 1961638SrgrimesPROG The name of the program to build. If not supplied, nothing 1971638Srgrimes is built. 1981638Srgrimes 1991638SrgrimesSRCS List of source files to build the program. If PROG is not 2001638Srgrimes defined, it's assumed to be ${PROG}.c. 2011638Srgrimes 2021638SrgrimesDPADD Additional dependencies for the program. Usually used for 2031638Srgrimes libraries. For example, to depend on the compatibility and 2041638Srgrimes utility libraries use: 2051638Srgrimes 2061638Srgrimes SRCLIB=${LIBCOMPAT} ${LIBUTIL} 2071638Srgrimes 20814701Sbde There is a predefined identifier for each (non-profiled, 20914701Sbde non-shared) library and object. Library file names are 21014701Sbde transformed to identifiers by removing the extension and 21114701Sbde converting to upper case. 2121638Srgrimes 21314701Sbde There are no special identifiers for profiled or shared 21414701Sbde libraries or objects. The identifiers for the standard 21514701Sbde libraries are used in DPADD. This works correctly iff all 21614701Sbde the libraries are built at the same time. Unfortunately, 21714701Sbde it causes unnecessary relinks to shared libraries when 21814701Sbde only the static libraries have changed. Dependencies on 21914701Sbde shared libraries should be only on the library version 22014701Sbde numbers. 2211638Srgrimes 2221638SrgrimesSTRIP The flag passed to the install program to cause the binary 2231638Srgrimes to be stripped. 2241638Srgrimes 2251638SrgrimesSUBDIR A list of subdirectories that should be built as well. 2261638Srgrimes Each of the targets will execute the same target in the 2271638Srgrimes subdirectories. 2281638Srgrimes 2293470SrgrimesThe include file <bsd.prog.mk> includes the include files <bsd.inc.mk> 2303470Srgrimesand <bsd.man.mk>. 2311638Srgrimes 2321638SrgrimesSome simple examples: 2331638Srgrimes 2341638SrgrimesTo build foo from foo.c with a manual page foo.1, use: 2351638Srgrimes 2361638Srgrimes PROG= foo 2371638Srgrimes 2381638Srgrimes .include <bsd.prog.mk> 2391638Srgrimes 2401638SrgrimesTo build foo from foo.c with a manual page foo.2, add the line: 2411638Srgrimes 2421638Srgrimes MAN2= foo.0 2431638Srgrimes 2441638SrgrimesIf foo does not have a manual page at all, add the line: 2451638Srgrimes 2461638Srgrimes NOMAN= noman 2471638Srgrimes 2481638SrgrimesIf foo has multiple source files, add the line: 2491638Srgrimes 2501638Srgrimes SRCS= a.c b.c c.c d.c 2511638Srgrimes 2521638Srgrimes=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 2531638Srgrimes 2541638SrgrimesThe include file <bsd.subdir.mk> contains the default targets for building 2551638Srgrimessubdirectories. It has the same seven targets as <bsd.prog.mk>: all, clean, 2561638Srgrimescleandir, depend, install, lint, and tags. For all of the directories 2571638Srgrimeslisted in the variable SUBDIRS, the specified directory will be visited 2581638Srgrimesand the target made. There is also a default target which allows the 2591638Srgrimescommand "make subdir" where subdir is any directory listed in the variable 2601638SrgrimesSUBDIRS. 2611638Srgrimes 2621638Srgrimes=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 2631638Srgrimes 2641638SrgrimesThe include file <bsd.lib.mk> has support for building libraries. It has 2651638Srgrimesthe same seven targets as <bsd.prog.mk>: all, clean, cleandir, depend, 2661638Srgrimesinstall, lint, and tags. It has a limited number of suffixes, consistent 2671638Srgrimeswith the current needs of the BSD tree. 2681638Srgrimes 2691638SrgrimesIt sets/uses the following variables: 2701638Srgrimes 2711638SrgrimesLIBDIR Target directory for libraries. 2721638Srgrimes 2731638SrgrimesLINTLIBDIR Target directory for lint libraries. 2741638Srgrimes 2751638SrgrimesLIBGRP Library group. 2761638Srgrimes 2771638SrgrimesLIBOWN Library owner. 2781638Srgrimes 2791638SrgrimesLIBMODE Library mode. 2801638Srgrimes 2811638SrgrimesLDADD Additional loader objects. 2821638Srgrimes 2831638SrgrimesMAN1 ... MAN8 The manual pages to be installed (use a .0 suffix). 2841638Srgrimes 2851638SrgrimesSRCS List of source files to build the library. Suffix types 2861638Srgrimes .s, .c, and .f are supported. Note, .s files are preferred 2871638Srgrimes to .c files of the same name. (This is not the default for 2881638Srgrimes versions of make.) 2891638Srgrimes 2903470SrgrimesThe include file <bsd.lib.mk> includes the include files <bsd.inc.mk> 2913470Srgrimesand <bsd.man.mk>. 2921638Srgrimes 2931638SrgrimesIt has rules for building profiled objects; profiled libraries are 2941638Srgrimesbuilt by default. 2951638Srgrimes 2961638SrgrimesLibraries are ranlib'd before installation. 297