xref: /freebsd/share/mk/bsd.README (revision c9dbb1cc52b063bbd9ab078a7afc89a8696da659)
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 (deprecated)
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
273LDFLAGS		Additional loader flags. Passed to the loader via CC,
274		since that's used to link programs as well, so loader
275		specific flags need to be prefixed with -Wl, to work.
276
277LINKS		The list of binary links; should be full pathnames, the
278		linked-to file coming first, followed by the linked
279		file.  The files are hard-linked.  For example, to link
280		/bin/test and /bin/[, use:
281
282			LINKS=	${DESTDIR}/bin/test ${DESTDIR}/bin/[
283
284MAN		Manual pages (should end in .1 - .9).  If no MAN variable
285		is defined, "MAN=${PROG}.1" is assumed.
286
287PROG		The name of the program to build.  If not supplied, nothing
288		is built.
289
290PROG_CXX	If defined, the name of the program to build.  Also
291		causes <bsd.prog.mk> to link the program with the
292		standard C++ library.  PROG_CXX overrides the value
293		of PROG if PROG is also set.
294
295PROGNAME	The name that the above program will be installed as, if
296		different from ${PROG}.
297
298SRCS		List of source files to build the program.  If SRCS is not
299		defined, it's assumed to be ${PROG}.c or, if PROG_CXX is
300		defined, ${PROG_CXX}.cc.
301
302DPADD		Additional dependencies for the program.  Usually used for
303		libraries.  For example, to depend on the compatibility and
304		utility libraries use:
305
306			DPADD=${LIBCOMPAT} ${LIBUTIL}
307
308		There is a predefined identifier for each (non-profiled,
309		non-shared) library and object.  Library file names are
310		transformed to identifiers by removing the extension and
311		converting to upper case.
312
313		There are no special identifiers for profiled or shared
314		libraries or objects.  The identifiers for the standard
315		libraries are used in DPADD.  This works correctly iff all
316		the libraries are built at the same time.  Unfortunately,
317		it causes unnecessary relinks to shared libraries when
318		only the static libraries have changed.  Dependencies on
319		shared libraries should be only on the library version
320		numbers.
321
322STRIP		The flag passed to the install program to cause the binary
323		to be stripped.  This is to be used when building your
324		own install script so that the entire system can be made
325		stripped/not-stripped using a single nob.
326
327SUBDIR		A list of subdirectories that should be built as well.
328		Each of the targets will execute the same target in the
329		subdirectories.
330
331SCRIPTS		A list of interpreter scripts [file.{sh,csh,pl,awk,...}].
332		The installation is controlled by the SCRIPTSNAME, SCRIPTSOWN,
333		SCRIPTSGRP, SCRIPTSMODE, SCRIPTSDIR variables that can be
334		further specialized by SCRIPTS<VAR>_<script>.
335
336The include file <bsd.prog.mk> includes the file named "../Makefile.inc"
337if it exists, as well as the include file <bsd.man.mk>.
338
339Some simple examples:
340
341To build foo from foo.c with a manual page foo.1, use:
342
343	PROG=	foo
344
345	.include <bsd.prog.mk>
346
347To build foo from foo.c with a manual page foo.2, add the line:
348
349	MAN=	foo.2
350
351If foo does not have a manual page at all, add the line:
352
353	MAN=
354
355If foo has multiple source files, add the line:
356
357	SRCS=	a.c b.c c.c d.c
358
359=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
360
361The include file <bsd.subdir.mk> contains the default targets for building
362subdirectories.  It has the same seven targets as <bsd.prog.mk>: all, clean,
363cleandir, depend, install, lint, and tags.  For all of the directories
364listed in the variable SUBDIRS, the specified directory will be visited
365and the target made.  There is also a default target which allows the
366command "make subdir" where subdir is any directory listed in the variable
367SUBDIRS.
368
369=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
370
371The include file <bsd.lib.mk> has support for building libraries.  It has
372the same seven targets as <bsd.prog.mk>: all, clean, cleandir, depend,
373install, lint, and tags.  It has a limited number of suffixes, consistent
374with the current needs of the BSD tree.
375
376It sets/uses the following variables:
377
378LIB		The name of the library to build.
379
380LIB_CXX		The name of the library to build. It also causes
381		<bsd.lib.mk> to link the library with the
382		standard C++ library.  LIB_CXX overrides the value
383		of LIB if LIB is also set.
384
385LIBDIR		Target directory for libraries.
386
387LINTLIBDIR	Target directory for lint libraries.
388
389LIBGRP		Library group.
390
391LIBOWN		Library owner.
392
393LIBMODE		Library mode.
394
395LDADD		Additional loader objects.
396
397MAN		The manual pages to be installed (use a .1 - .9 suffix).
398
399SRCS		List of source files to build the library.  Suffix types
400		.s, .c, and .f are supported.  Note, .s files are preferred
401		to .c files of the same name.  (This is not the default for
402		versions of make.)
403
404SHLIB_LDSCRIPT	Template file to generate shared library linker script.
405		Unless used, a simple symlink is created to the real
406		shared object.
407
408LIBRARIES_ONLY	Do not build or install files other than the library.
409
410The include file <bsd.lib.mk> includes the file named "../Makefile.inc"
411if it exists, as well as the include file <bsd.man.mk>.
412
413It has rules for building profiled objects; profiled libraries are
414built by default.
415
416Libraries are ranlib'd before installation.
417
418=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
419
420The include file <bsd.test.mk> handles building one or more test programs
421intended to be used in the FreeBSD Test Suite under /usr/tests/.
422
423It has seven targets:
424
425	all:
426		build the test programs.
427	clean:
428		remove the test programs and any object files.
429	cleandir:
430		remove all of the files removed by the target clean, as
431		well as .depend and tags.
432	depend:
433		make the dependencies for the source files, and store
434		them in the file .depend.
435	install:
436                install the test programs and their data files; if the
437                Makefile does not itself define the target install, the
438                targets beforeinstall and afterinstall may also be used
439                to cause actions immediately before and after the
440                install target is executed.
441	lint:
442		run lint on the source files.
443	tags:
444		create a tags file for the source files.
445	test:
446		runs the test programs from the object directory; if the
447		Makefile does not itself define the target test, the
448		targets beforetest and aftertest may also be used to
449		cause actions immediately before and after the test
450		target is executed.
451
452It sets/uses the following variables, among many others:
453
454TESTDIR		Path to the installed tests.  Must be a subdirectory of
455		TESTSBASE and the subpath should match the relative
456		location of the tests within the src tree.
457
458KYUAFILE	If 'auto' (the default), generate a Kyuafile out of the
459		test programs defined in the Makefile.  If 'yes', then a
460		manually-crafted Kyuafile must be supplied with the
461		sources.  If 'no', no Kyuafile is installed (useful for
462		subdirectories providing helper programs or data files
463		only).
464
465ATF_TESTS_C	The names of the ATF C test programs to build.
466
467ATF_TESTS_CXX	The names of the ATF C++ test programs to build.
468
469ATF_TESTS_SH	The names of the ATF sh test programs to build.
470
471PLAIN_TESTS_C	The names of the plain (legacy) programs to build.
472
473PLAIN_TESTS_CXX	The names of the plain (legacy) test programs to build.
474
475PLAIN_TESTS_SH	The names of the plain (legacy) test programs to build.
476
477TAP_PERL_INTERPRETER
478		Path to the Perl interpreter to be used for
479		TAP-compliant test programs that are written in Perl.
480		Refer to TAP_TESTS_PERL for details.
481
482TAP_TESTS_C	The names of the TAP-compliant C test programs to build.
483
484TAP_TESTS_CXX	The names of the TAP-compliant C++ test programs to
485		build.
486
487TAP_TESTS_PERL	The names of the TAP-compliant Perl test programs to
488		build.  The corresponding source files should end with
489		the .pl extension; the test program is marked as
490		requiring Perl; and TAP_PERL_INTERPRETER is used in the
491		built scripts as the interpreter of choice.
492
493TAP_TESTS_SH	The names of the TAP-compliant sh test programs to
494		build.
495
496TESTS_SUBDIRS	List of subdirectories containing tests into which to
497		recurse.  Differs from SUBDIR in that these directories
498		get registered into the automatically-generated
499		Kyuafile (if any).
500
501NOT_FOR_TEST_SUITE
502		If defined, none of the built test programs get
503		installed under /usr/tests/ and no Kyuafile is
504		automatically generated.  Should not be used within the
505		FreeBSD source tree but is provided for the benefit of
506		third-parties.
507
508The actual building of the test programs is performed by <bsd.prog.mk>.
509Please see the documentation above for this other file for additional
510details on the behavior of <bsd.test.mk>.
511