xref: /freebsd/share/mk/bsd.README (revision 47dd1d1b619cc035b82b49a91a25544309ff95ae)
1#	@(#)bsd.README	8.2 (Berkeley) 4/2/94
2# $FreeBSD$
3
4This is the README file for the "include" files for the FreeBSD
5source tree.  The files are installed in /usr/share/mk, and are by
6convention, named with the suffix ".mk".  These files store several
7build options and should be handled with caution.
8
9Note, this file is not intended to replace reading through the .mk
10files for anything tricky.
11
12There are two main types of make include files.  One type is the generally
13usable make include files, such as bsd.prog.mk and bsd.lib.mk.  The other is
14the internal make include files, such as bsd.files.mk and bsd.man.mk, which
15can not/should not be used directly but are used by the other make include
16files.  In most cases it is only interesting to include bsd.prog.mk or
17bsd.lib.mk.
18
19bsd.arch.inc.mk		- includes arch-specific Makefile.$arch
20bsd.compiler.mk		- defined based on current compiler
21bsd.confs.mk		- install of configuration files
22bsd.cpu.mk		- sets CPU/arch-related variables (included from sys.mk)
23bsd.crunchgen.mk	- building crunched binaries using crunchgen(1)
24bsd.dep.mk		- handle Makefile dependencies
25bsd.doc.mk		- building troff system documents
26bsd.endian.mk		- TARGET_ENDIAN=1234(little) or 4321 (big) for target
27bsd.files.mk		- install of general purpose files
28bsd.incs.mk		- install of include files
29bsd.info.mk		- building GNU Info hypertext system (deprecated)
30bsd.init.mk		- initialization for the make include files
31bsd.kmod.mk		- building loadable kernel modules
32bsd.lib.mk		- support for building libraries
33bsd.libnames.mk		- define library names
34bsd.links.mk		- install of links (sym/hard)
35bsd.man.mk		- install of manual pages and their links
36bsd.nls.mk		- build and install of NLS catalogs
37bsd.obj.mk		- creating 'obj' directories and cleaning up
38bsd.own.mk		- define common variables
39bsd.port.mk		- building ports
40bsd.port.post.mk	- building ports
41bsd.port.pre.mk		- building ports
42bsd.port.subdir.mk	- targets for building subdirectories for ports
43bsd.prog.mk		- building programs from source files
44bsd.progs.mk		- build multiple programs from sources
45bsd.snmpmod.mk		- building modules for the SNMP daemon bsnmpd
46bsd.subdir.mk		- targets for building subdirectories
47bsd.sys.mk		- common settings used for building FreeBSD sources
48bsd.test.mk		- building test programs from source files
49sys.mk			- default rules for all makes
50
51This file does not document bsd.port*.mk.  They are documented in ports(7).
52
53See also make(1), mkdep(1), style.Makefile(5) and `PMake - A
54Tutorial', located in /usr/share/doc/psd/12.make.
55
56=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
57
58Random things worth knowing about this document:
59
60If appropriate when documenting the variables the default value is
61indicated using square brackets e.g. [gzip].
62In some cases the default value depend on other values (e.g. system
63architecture).  In these cases the most common value is indicated.
64
65This document contains some simple examples of the usage of the BSD make
66include files.  For more examples look at the makefiles in the FreeBSD
67source tree.
68
69=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
70
71RANDOM THINGS WORTH KNOWING:
72
73The files are like C-style #include files, and pretty much behave like
74you'd expect.  The syntax is slightly different in that a single '.' is
75used instead of the hash mark, i.e. ".include <bsd.prog.mk>".
76
77One difference that will save you lots of debugging time is that inclusion
78of the file is normally done at the *end* of the Makefile.  The reason for
79this is because .mk files often modify variables and behavior based on the
80values of variables set in the Makefile.  To make this work, remember that
81the FIRST target found is the target that is used, i.e. if the Makefile has:
82
83	a:
84		echo a
85	a:
86		echo a number two
87
88the command "make a" will echo "a".  To make things confusing, the SECOND
89variable assignment is the overriding one, i.e. if the Makefile has:
90
91	a=	foo
92	a=	bar
93
94	b:
95		echo ${a}
96
97the command "make b" will echo "bar".  This is for compatibility with the
98way the V7 make behaved.
99
100It's fairly difficult to make the BSD .mk files work when you're building
101multiple programs in a single directory.  It's a lot easier to split up
102the programs than to deal with the problem.  Most of the agony comes from
103making the "obj" directory stuff work right, not because we switch to a new
104version of make.  So, don't get mad at us, figure out a better way to handle
105multiple architectures so we can quit using the symbolic link stuff.
106(Imake doesn't count.)
107
108The file .depend in the source directory is expected to contain dependencies
109for the source files.  This file is read automatically by make after reading
110the Makefile.
111
112The variable DESTDIR works as before.  It's not set anywhere but will change
113the tree where the file gets installed.
114
115The profiled libraries are no longer built in a different directory than
116the regular libraries.  A new suffix, ".po", is used to denote a profiled
117object, and ".pico" denotes a position-independent relocatable object.
118".nossppico" denotes a position-independent relocatable object without
119stack smashing protection.
120
121=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
122
123The following variables are common:
124
125AFLAGS.${SRC}
126		Flags dependent on source file name.
127ACFLAGS.${SRC}
128		Flags dependent on source file name.
129CFLAGS.${SRC}
130		Flags dependent on source file name.
131CFLAGS.${COMPILER_TYPE}
132		Flags dependent on compiler added to CFLAGS.
133CFLAGS.${MACHINE_ARCH}
134		Architectural flags added to CFLAGS.
135CFLAGS_NO_SIMD	Add this to CFLAGS for programs that don't want any SIMD
136		instructions generated. It is setup in bsd.cpu.mk to an
137		appropriate value for the compiler and target.
138CXXFLAGS.${COMPILER_TYPE}
139		Flags dependent on compiler added to CXXFLAGS.
140CXXFLAGS.${MACHINE_ARCH}
141		Architectural flags added to CXXFLAGS.
142CXXFLAGS.${SRC}
143		Flags dependent on source file name.
144COMPILER_FEATURES
145		A list of features that the compiler supports. Zero or
146		more of:
147			c++11	Supports full C++ 11 standard.
148
149COMPILER_TYPE	Type of compiler, either clang or gcc, though other
150		values are possible. Don't assume != clang == gcc.
151
152COMPILER_VERSION
153		A numeric constant equal to:
154		     major * 10000 + minor * 100 + tiny
155		for the compiler's self-reported version.
156
157=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
158
159The include file <sys.mk> has the default rules for all makes, in the BSD
160environment or otherwise.  You probably don't want to touch this file.
161
162=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
163
164The include file <bsd.arch.inc.mk> includes other Makefiles for specific
165architectures, if they exist. It will include the first of the following
166files that it finds: Makefile.${MACHINE}, Makefile.${MACHINE_ARCH},
167Makefile.${MACHINE_CPUARCH}
168
169=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
170
171The include file <bsd.man.mk> handles installing manual pages and their
172links.
173
174It has three targets:
175
176	all-man:
177		build manual pages.
178	maninstall:
179		install the manual pages and their links.
180	manlint:
181		verify the validity of manual pages.
182
183It sets/uses the following variables:
184
185MAN		The manual pages to be installed (use a .1 - .9 suffix).
186
187MANDIR		Base path for manual installation.
188
189MANGRP		Manual group.
190
191MANMODE		Manual mode.
192
193MANOWN		Manual owner.
194
195MANSUBDIR	Subdirectory under the manual page section, i.e. "/vax"
196		or "/tahoe" for machine specific manual pages.
197
198MLINKS		List of manual page links (using a .1 - .9 suffix).  The
199		linked-to file must come first, the linked file second,
200		and there may be multiple pairs.  The files are hard-linked.
201
202The include file <bsd.man.mk> includes a file named "../Makefile.inc" if
203it exists.
204
205=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
206
207The include file <bsd.own.mk> contains the owners, groups, etc. for both
208manual pages and binaries.
209
210It has no targets.
211
212It sets/uses the following variables:
213
214BINGRP		Binary group.
215
216BINMODE		Binary mode.
217
218BINOWN		Binary owner.
219
220MANDIR		Base path for manual installation.
221
222MANGRP		Manual group.
223
224MANMODE		Manual mode.
225
226MANOWN		Manual owner.
227
228This file is generally useful when building your own Makefiles so that
229they use the same default owners etc. as the rest of the tree.
230
231=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
232
233The include file <bsd.prog.mk> handles building programs from one or
234more source files, along with their manual pages.  It has a limited number
235of suffixes, consistent with the current needs of the BSD tree.
236
237It has seven targets:
238
239	all:
240		build the program and its manual page
241	clean:
242		remove the program and any object files.
243	cleandir:
244		remove all of the files removed by the target clean, as
245		well as .depend, tags, and any manual pages.
246	depend:
247		make the dependencies for the source files, and store
248		them in the file .depend.
249	install:
250		install the program and its manual pages; if the Makefile
251		does not itself define the target install, the targets
252		beforeinstall and afterinstall may also be used to cause
253		actions immediately before and after the install target
254		is executed.
255	tags:
256		create a tags file for the source files.
257
258It sets/uses the following variables:
259
260ACFLAGS		Flags to the compiler when preprocessing and
261		assembling .S files.
262
263AFLAGS		Flags to the assembler when assembling .s files.
264
265BINGRP		Binary group.
266
267BINMODE		Binary mode.
268
269BINOWN		Binary owner.
270
271CFLAGS		Flags to the compiler when creating C objects.
272
273CLEANDIRS	Additional files (CLEANFILES) and directories (CLEANDIRS) to
274CLEANFILES	remove during clean and cleandir targets.  "rm -rf" and
275		"rm -f" are used, respectively.
276
277DPADD		Additional dependencies for the program.  Usually used for
278		libraries.  For example, to depend on the compatibility and
279		utility libraries use:
280
281			DPADD=${LIBCOMPAT} ${LIBUTIL}
282
283		There is a predefined identifier for each (non-profiled,
284		non-shared) library and object.  Library file names are
285		transformed to identifiers by removing the extension and
286		converting to upper case.
287
288		There are no special identifiers for profiled or shared
289		libraries or objects.  The identifiers for the standard
290		libraries are used in DPADD.  This works correctly iff all
291		the libraries are built at the same time.  Unfortunately,
292		it causes unnecessary relinks to shared libraries when
293		only the static libraries have changed.  Dependencies on
294		shared libraries should be only on the library version
295		numbers.
296
297FILES		A list of non-executable files.
298		The installation is controlled by the FILESNAME, FILESOWN,
299		FILESGRP, FILESMODE, FILESDIR variables that can be
300		further specialized by FILES<VAR>_<file>.
301
302LDADD		Additional loader objects.  Usually used for libraries.
303		For example, to load with the compatibility and utility
304		libraries, use:
305
306			LDADD=-lutil -lcompat
307
308LDFLAGS		Additional loader flags. Passed to the loader via CC,
309		since that's used to link programs as well, so loader
310		specific flags need to be prefixed with -Wl, to work.
311
312LIBADD		Additional libraries.  This is for base system libraries
313		and is only valid inside of the /usr/src tree.
314		Use LIBADD=name instead of LDADD=-lname.
315
316LINKS		The list of binary links; should be full pathnames, the
317		linked-to file coming first, followed by the linked
318		file.  The files are hard-linked.  For example, to link
319		/bin/test and /bin/[, use:
320
321			LINKS=	/bin/test /bin/[
322
323MAN		Manual pages.  If no MAN variable is defined,
324		"MAN=${PROG}.1" is assumed. See bsd.man.mk for more details.
325
326PROG		The name of the program to build.  If not supplied, nothing
327		is built.
328
329PROGNAME	The name that the above program will be installed as, if
330		different from ${PROG}.
331
332PROG_CXX	If defined, the name of the program to build.  Also
333		causes <bsd.prog.mk> to link the program with the
334		standard C++ library.  PROG_CXX overrides the value
335		of PROG if PROG is also set.
336
337PROGS		When used with <bsd.progs.mk>, allow building multiple
338PROGS_CXX	PROG and PROG_CXX in one Makefile.  To define
339		individual variables for each program the VAR.prog
340		syntax should be used.  For example:
341
342		PROGS=		foo bar
343		SRCS.foo=	foo_src.c
344		LDADD.foo=	-lutil
345		SRCS.bar=	bar_src.c
346
347		The supported variables are:
348		- BINDIR
349		- BINGRP
350		- BINMODE
351		- BINOWN
352		- CFLAGS
353		- CXXFLAGS
354		- DEBUG_FLAGS
355		- DPADD
356		- DPSRCS
357		- INTERNALPROG (no installation)
358		- LDADD
359		- LDFLAGS
360		- LIBADD
361		- LINKS
362		- MAN
363		- MLINKS
364		- NO_WERROR
365		- PROGNAME
366		- SRCS
367		- STRIP
368		- WARNS
369
370SCRIPTS		A list of interpreter scripts [file.{sh,csh,pl,awk,...}].
371		The installation is controlled by the SCRIPTSNAME, SCRIPTSOWN,
372		SCRIPTSGRP, SCRIPTSMODE, SCRIPTSDIR variables that can be
373		further specialized by SCRIPTS<VAR>_<script>.
374
375SRCS		List of source files to build the program.  If SRCS is not
376		defined, it's assumed to be ${PROG}.c or, if PROG_CXX is
377		defined, ${PROG_CXX}.cc.
378
379STRIP		The flag passed to the install program to cause the binary
380		to be stripped.  This is to be used when building your
381		own install script so that the entire system can be made
382		stripped/not-stripped using a single nob.
383
384SUBDIR		A list of subdirectories that should be built as well.
385		Each of the targets will execute the same target in the
386		subdirectories.
387
388The include file <bsd.prog.mk> includes the file named "../Makefile.inc"
389if it exists, as well as the include file <bsd.man.mk>.
390
391Some simple examples:
392
393To build foo from foo.c with a manual page foo.1, use:
394
395	PROG=	foo
396
397	.include <bsd.prog.mk>
398
399To build foo from foo.c with a manual page foo.2, add the line:
400
401	MAN=	foo.2
402
403If foo does not have a manual page at all, add the line:
404
405	MAN=
406
407If foo has multiple source files, add the line:
408
409	SRCS=	a.c b.c c.c d.c
410
411=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
412
413The include file, <bsd.snmpmod.mk>, handles building MIB modules for bsnmpd
414from one or more source files, along with their manual pages.  It has a
415limited number of suffixes, consistent with the current needs of the BSD
416tree.
417
418bsd.snmpmod.mk leverages bsd.lib.mk for building MIB modules and
419bsd.files.mk for installing MIB description and definition files.
420
421It implements the following additional targets:
422
423	smilint:
424		execute smilint on the MIBs defined by BMIBS.
425
426		The net-mgmt/libsmi package must be installed before
427		executing this target. The net-mgmt/net-snmp package
428		should be installed as well to reduce false positives
429		from smilint.
430
431It sets/uses the following variables:
432
433BMIBS		The MIB definitions to install.
434
435BMIBSDIR	The directory where the MIB definitions are installed.
436		This defaults to `${SHAREDIR}/snmp/mibs`.
437
438DEFS		The MIB description files to install.
439
440DEFSDIR		The directory where MIB description files are installed.
441		This defaults to `${SHAREDIR}/snmp/defs`.
442
443EXTRAMIBDEFS	Extra MIB description files to use as input when
444		generating ${MOD}_oid.h and ${MOD}_tree.[ch].
445
446EXTRAMIBSYMS	Extra MIB definition files used only for extracting
447		symbols.
448
449		EXTRAMIBSYMS are useful when resolving inter-module
450		dependencies and are useful with files containing only
451		enum-definitions.
452
453		See ${MOD}_oid.h for more details.
454
455LOCALBASE	The package root where smilint and the net-snmp
456		definitions can be found
457
458MOD		The bsnmpd module name.
459
460SMILINT		smilint binary to use with the smilint make target.
461
462SMILINT_FLAGS	flags to pass to smilint.
463
464SMIPATH		A colon-separated directory path where MIBs definitions
465		can be found. See "SMIPATH" in smi_config for more
466		details.
467
468XSYM		MIB names to extract symbols for. See ${MOD}_oid.h for
469		more details.
470
471It generates the following files:
472
473${MOD}_tree.c	A source file and header which programmatically describes
474${MOD}_tree.h	the MIB (type, OID name, ACCESS attributes, etc).
475
476		The files are generated via "gensnmptree -p".
477
478		See gensnmptree(1) for more details.
479
480${MOD}_oid.h	A header which programmatically describes the MIB root and
481		MIB tables.
482
483		The files are generated via "gensnmptree -e".
484
485		See gensnmptree(1) for more details.
486
487=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
488
489The include file <bsd.subdir.mk> contains the default targets for building
490subdirectories.  It has the same seven targets as <bsd.prog.mk>: all, clean,
491cleandir, depend, install, and tags.  For all of the directories listed in the
492variable SUBDIRS, the specified directory will be visited and the target made.
493There is also a default target which allows the command "make subdir" where
494subdir is any directory listed in the variable SUBDIRS.
495
496=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
497
498The include file <bsd.lib.mk> has support for building libraries.  It has the
499same seven targets as <bsd.prog.mk>: all, clean, cleandir, depend, install, and
500tags.  It has a limited number of suffixes, consistent with the current needs of
501the BSD tree.
502
503It sets/uses the following variables:
504
505LDADD		Additional loader objects.
506
507LIB		The name of the library to build.  Both a shared and static
508		library will be built.  NO_PIC can be set to only build a
509		static library.
510
511LIBADD		Additional libraries.  This is for base system libraries
512		and is only valid inside of the /usr/src tree.
513		Use LIBADD=name instead of LDADD=-lname.
514
515LIBDIR		Target directory for libraries.
516
517LIBGRP		Library group.
518
519LIBMODE		Library mode.
520
521LIBOWN		Library owner.
522
523LIBRARIES_ONLY	Do not build or install files other than the library.
524
525LIB_CXX		The name of the library to build. It also causes
526		<bsd.lib.mk> to link the library with the
527		standard C++ library.  LIB_CXX overrides the value
528		of LIB if LIB is also set.  Both a shared and static library
529		will be built.  NO_PIC can be set to only build a static
530		library.
531
532MAN		The manual pages to be installed. See bsd.man.mk for more
533		details.
534
535SHLIB		Like LIB but only builds a shared library.
536
537SHLIB_CXX	Like LIB_CXX but only builds a shared library.
538
539SHLIB_LDSCRIPT	Template file to generate shared library linker script.
540		If not defined, a simple symlink is created to the real
541		shared object.
542
543SRCS		List of source files to build the library.  Suffix types
544		.s, .c, and .f are supported.  Note, .s files are preferred
545		to .c files of the same name.  (This is not the default for
546		versions of make.)
547
548The include file <bsd.lib.mk> includes the file named "../Makefile.inc"
549if it exists, as well as the include file <bsd.man.mk>.
550
551It has rules for building profiled objects; profiled libraries are
552built by default.
553
554Libraries are ranlib'd before installation.
555
556=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
557
558The include file <bsd.test.mk> handles building one or more test programs
559intended to be used in the FreeBSD Test Suite under /usr/tests/.
560
561It has seven targets:
562
563	all:
564		build the test programs.
565	check:
566		runs the test programs with kyua test.
567
568		The beforecheck and aftercheck targets will be invoked, if
569		defined, to execute commands before and after the realcheck
570		target has been executed, respectively.
571
572		The devel/kyua package must be installed before invoking this
573		target.
574	clean:
575		remove the test programs and any object files.
576	cleandir:
577		remove all of the files removed by the target clean, as
578		well as .depend and tags.
579	depend:
580		make the dependencies for the source files, and store
581		them in the file .depend.
582	install:
583                install the test programs and their data files; if the
584                Makefile does not itself define the target install, the
585                targets beforeinstall and afterinstall may also be used
586                to cause actions immediately before and after the
587                install target is executed.
588	tags:
589		create a tags file for the source files.
590
591It sets/uses the following variables, among many others:
592
593ATF_TESTS_C	The names of the ATF C test programs to build.
594
595ATF_TESTS_CXX	The names of the ATF C++ test programs to build.
596
597ATF_TESTS_SH	The names of the ATF sh test programs to build.
598
599KYUAFILE	If 'auto' (the default), generate a Kyuafile out of the
600		test programs defined in the Makefile.  If 'yes', then a
601		manually-crafted Kyuafile must be supplied with the
602		sources.  If 'no', no Kyuafile is installed (useful for
603		subdirectories providing helper programs or data files
604		only).
605
606LOCALBASE	The --prefix for the kyua package.
607
608		The value of LOCALBASE defaults to /usr/local .
609
610NOT_FOR_TEST_SUITE
611		If defined, none of the built test programs get
612		installed under /usr/tests/ and no Kyuafile is
613		automatically generated.  Should not be used within the
614		FreeBSD source tree but is provided for the benefit of
615		third-parties.
616
617PLAIN_TESTS_C	The names of the plain (legacy) programs to build.
618
619PLAIN_TESTS_CXX	The names of the plain (legacy) test programs to build.
620
621PLAIN_TESTS_SH	The names of the plain (legacy) test programs to build.
622
623TAP_PERL_INTERPRETER
624		Path to the Perl interpreter to be used for
625		TAP-compliant test programs that are written in Perl.
626		Refer to TAP_TESTS_PERL for details.
627
628TAP_TESTS_C	The names of the TAP-compliant C test programs to build.
629
630TAP_TESTS_CXX	The names of the TAP-compliant C++ test programs to
631		build.
632
633TAP_TESTS_PERL	The names of the TAP-compliant Perl test programs to
634		build.  The corresponding source files should end with
635		the .pl extension; the test program is marked as
636		requiring Perl; and TAP_PERL_INTERPRETER is used in the
637		built scripts as the interpreter of choice.
638
639TAP_TESTS_SH	The names of the TAP-compliant sh test programs to
640		build.
641
642TESTSBASE	Installation prefix for tests. Defaults to /usr/tests
643
644TESTSDIR	Path to the installed tests.  Must be a subdirectory of
645		TESTSBASE and the subpath should match the relative
646		location of the tests within the src tree.
647
648		The value of TESTSDIR defaults to
649		${TESTSBASE}/${RELDIR:H} , e.g. /usr/tests/bin/ls when
650		included from bin/ls/tests .
651
652TESTS_SUBDIRS	List of subdirectories containing tests into which to
653		recurse.  Differs from SUBDIR in that these directories
654		get registered into the automatically-generated
655		Kyuafile (if any).
656
657The actual building of the test programs is performed by <bsd.prog.mk>.
658Please see the documentation above for this other file for additional
659details on the behavior of <bsd.test.mk>.
660