bsd.README revision 156743
11638Srgrimes#	@(#)bsd.README	8.2 (Berkeley) 4/2/94
250476Speter# $FreeBSD: head/share/mk/bsd.README 156743 2006-03-15 15:49:38Z 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
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
42115103Strhodessys.mk			- default rules for all makes
4323559Swosch
44115103StrhodesThis file does not document bsd.port*.mk.  They are documented in ports(7).
4523559Swosch
46115103StrhodesSee also make(1), mkdep(1), style.Makefile(5) and `PMake - A
47115103StrhodesTutorial', located in /usr/share/doc/psd/12.make.
481638Srgrimes
49115103Strhodes=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
5023578Swosch
51115103StrhodesRandom things worth knowing about this document:
52115103Strhodes
53115103StrhodesIf appropriate when documenting the variables the default value is
54115103Strhodesindicated using square brackets e.g. [gzip].
55115103StrhodesIn some cases the default value depend on other values (e.g. system
56115103Strhodesarchitecture).  In these cases the most common value is indicated.
57115103Strhodes
58115103StrhodesThis document contains some simple examples of the usage of the BSD make
59115103Strhodesinclude files.  For more examples look at the makefiles in the FreeBSD
60115103Strhodessource tree.
61115103Strhodes
621638Srgrimes=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
631638Srgrimes
641638SrgrimesRANDOM THINGS WORTH KNOWING:
651638Srgrimes
66115103StrhodesThe files are like C-style #include files, and pretty much behave like
671638Srgrimesyou'd expect.  The syntax is slightly different in that a single '.' is
681638Srgrimesused instead of the hash mark, i.e. ".include <bsd.prog.mk>".
691638Srgrimes
701638SrgrimesOne difference that will save you lots of debugging time is that inclusion
711638Srgrimesof the file is normally done at the *end* of the Makefile.  The reason for
721638Srgrimesthis is because .mk files often modify variables and behavior based on the
731638Srgrimesvalues of variables set in the Makefile.  To make this work, remember that
741638Srgrimesthe FIRST target found is the target that is used, i.e. if the Makefile has:
751638Srgrimes
761638Srgrimes	a:
771638Srgrimes		echo a
781638Srgrimes	a:
791638Srgrimes		echo a number two
801638Srgrimes
811638Srgrimesthe command "make a" will echo "a".  To make things confusing, the SECOND
821638Srgrimesvariable assignment is the overriding one, i.e. if the Makefile has:
831638Srgrimes
841638Srgrimes	a=	foo
851638Srgrimes	a=	bar
861638Srgrimes
871638Srgrimes	b:
881638Srgrimes		echo ${a}
891638Srgrimes
901638Srgrimesthe command "make b" will echo "bar".  This is for compatibility with the
911638Srgrimesway the V7 make behaved.
921638Srgrimes
931638SrgrimesIt's fairly difficult to make the BSD .mk files work when you're building
941638Srgrimesmultiple programs in a single directory.  It's a lot easier split up the
951638Srgrimesprograms than to deal with the problem.  Most of the agony comes from making
961638Srgrimesthe "obj" directory stuff work right, not because we switch to a new version
971638Srgrimesof make.  So, don't get mad at us, figure out a better way to handle multiple
981638Srgrimesarchitectures so we can quit using the symbolic link stuff.  (Imake doesn't
991638Srgrimescount.)
1001638Srgrimes
1011638SrgrimesThe file .depend in the source directory is expected to contain dependencies
1021638Srgrimesfor the source files.  This file is read automatically by make after reading
1031638Srgrimesthe Makefile.
1041638Srgrimes
1051638SrgrimesThe variable DESTDIR works as before.  It's not set anywhere but will change
1061638Srgrimesthe tree where the file gets installed.
1071638Srgrimes
1081638SrgrimesThe profiled libraries are no longer built in a different directory than
1091638Srgrimesthe regular libraries.  A new suffix, ".po", is used to denote a profiled
1101638Srgrimesobject.
1111638Srgrimes
1121638Srgrimes=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
1131638Srgrimes
1141638SrgrimesThe include file <sys.mk> has the default rules for all makes, in the BSD
1151638Srgrimesenvironment or otherwise.  You probably don't want to touch this file.
1161638Srgrimes
1171638Srgrimes=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
1181638Srgrimes
1191638SrgrimesThe include file <bsd.man.mk> handles installing manual pages and their
1201638Srgrimeslinks.
1211638Srgrimes
12283075SruIt has three targets:
1231638Srgrimes
12483075Sru	all-man:
12583075Sru		build manual pages.
1261638Srgrimes	maninstall:
12783075Sru		install the manual pages and their links.
12883075Sru	manlint:
12983075Sru		verify the validity of manual pages.
1301638Srgrimes
1311638SrgrimesIt sets/uses the following variables:
1321638Srgrimes
1331638SrgrimesMANDIR		Base path for manual installation.
1341638Srgrimes
1351638SrgrimesMANGRP		Manual group.
1361638Srgrimes
1371638SrgrimesMANOWN		Manual owner.
1381638Srgrimes
1391638SrgrimesMANMODE		Manual mode.
1401638Srgrimes
1411638SrgrimesMANSUBDIR	Subdirectory under the manual page section, i.e. "/vax"
1421638Srgrimes		or "/tahoe" for machine specific manual pages.
1431638Srgrimes
14474942SruMAN		The manual pages to be installed (use a .1 - .9 suffix).
1451638Srgrimes
14658494SruMLINKS		List of manual page links (using a .1 - .9 suffix).  The
1471638Srgrimes		linked-to file must come first, the linked file second,
1481638Srgrimes		and there may be multiple pairs.  The files are soft-linked.
1491638Srgrimes
15074942SruThe include file <bsd.man.mk> includes a file named "../Makefile.inc" if
15174942Sruit exists.
1521638Srgrimes
1531638Srgrimes=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
1541638Srgrimes
1551638SrgrimesThe include file <bsd.own.mk> contains the owners, groups, etc. for both
1561638Srgrimesmanual pages and binaries.
1571638Srgrimes
1581638SrgrimesIt has no targets.
1591638Srgrimes
1601638SrgrimesIt sets/uses the following variables:
1611638Srgrimes
1621638SrgrimesBINGRP		Binary group.
1631638Srgrimes
1641638SrgrimesBINOWN		Binary owner.
1651638Srgrimes
1661638SrgrimesBINMODE		Binary mode.
1671638Srgrimes
1681638SrgrimesMANDIR		Base path for manual installation.
1691638Srgrimes
1701638SrgrimesMANGRP		Manual group.
1711638Srgrimes
1721638SrgrimesMANOWN		Manual owner.
1731638Srgrimes
1741638SrgrimesMANMODE		Manual mode.
1751638Srgrimes
1761638SrgrimesThis file is generally useful when building your own Makefiles so that
1771638Srgrimesthey use the same default owners etc. as the rest of the tree.
1781638Srgrimes
1791638Srgrimes=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
1801638Srgrimes
1811638SrgrimesThe include file <bsd.prog.mk> handles building programs from one or
1821638Srgrimesmore source files, along with their manual pages.  It has a limited number
1831638Srgrimesof suffixes, consistent with the current needs of the BSD tree.
1841638Srgrimes
1851638SrgrimesIt has seven targets:
1861638Srgrimes
1871638Srgrimes	all:
1881638Srgrimes		build the program and its manual page
1891638Srgrimes	clean:
1901638Srgrimes		remove the program, any object files and the files a.out,
1911638Srgrimes		Errs, errs, mklog, and ${PROG}.core.
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
2321638Srgrimes			LDFILES=-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
2651638Srgrimes			SRCLIB=${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
35674942SruThe include file <bsd.lib.mk> includes the file named "../Makefile.inc"
35774942Sruif it exists, as well as the include file <bsd.man.mk>.
3581638Srgrimes
3591638SrgrimesIt has rules for building profiled objects; profiled libraries are
3601638Srgrimesbuilt by default.
3611638Srgrimes
3621638SrgrimesLibraries are ranlib'd before installation.
363