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