1 # @(#)bsd.README 8.2 (Berkeley) 4/2/94
4 This is the README file for the "include" files for the FreeBSD
5 source tree. The files are installed in /usr/share/mk, and are by
6 convention, named with the suffix ".mk". These files store several
7 build options and should be handled with caution.
9 Note, this file is not intended to replace reading through the .mk
10 files for anything tricky.
12 There are two main types of make include files. One type is the generally
13 usable make include files, such as bsd.prog.mk and bsd.lib.mk. The other is
14 the internal make include files, such as bsd.files.mk and bsd.man.mk, which
15 can not/should not be used directly but are used by the other make include
16 files. In most cases it is only interesting to include bsd.prog.mk or
19 bsd.arch.inc.mk - includes arch-specific Makefile.$arch
20 bsd.compiler.mk - defined based on current compiler
21 bsd.cpu.mk - sets CPU/arch-related variables (included from sys.mk)
22 bsd.dep.mk - handle Makefile dependencies
23 bsd.doc.mk - building troff system documents
24 bsd.endian.mk - TARGET_ENDIAN=1234(little) or 4321 (big) for target
25 bsd.files.mk - install of general purpose files
26 bsd.incs.mk - install of include files
27 bsd.info.mk - building GNU Info hypertext system (deprecated)
28 bsd.init.mk - initialization for the make include files
29 bsd.kmod.mk - building loadable kernel modules
30 bsd.lib.mk - support for building libraries
31 bsd.libnames.mk - define library names
32 bsd.links.mk - install of links (sym/hard)
33 bsd.man.mk - install of manual pages and their links
34 bsd.nls.mk - build and install of NLS catalogs
35 bsd.obj.mk - creating 'obj' directories and cleaning up
36 bsd.own.mk - define common variables
37 bsd.port.mk - building ports
38 bsd.port.post.mk - building ports
39 bsd.port.pre.mk - building ports
40 bsd.port.subdir.mk - targets for building subdirectories for ports
41 bsd.prog.mk - building programs from source files
42 bsd.progs.mk - build multiple programs from sources (deprecated)
43 bsd.snmpmod.mk - building modules for the SNMP daemon bsnmpd
44 bsd.subdir.mk - targets for building subdirectories
45 bsd.sys.mk - common settings used for building FreeBSD sources
46 bsd.test.mk - building test programs from source files
47 sys.mk - default rules for all makes
49 This file does not document bsd.port*.mk. They are documented in ports(7).
51 See also make(1), mkdep(1), style.Makefile(5) and `PMake - A
52 Tutorial', located in /usr/share/doc/psd/12.make.
54 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
56 Random things worth knowing about this document:
58 If appropriate when documenting the variables the default value is
59 indicated using square brackets e.g. [gzip].
60 In some cases the default value depend on other values (e.g. system
61 architecture). In these cases the most common value is indicated.
63 This document contains some simple examples of the usage of the BSD make
64 include files. For more examples look at the makefiles in the FreeBSD
67 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
69 RANDOM THINGS WORTH KNOWING:
71 The files are like C-style #include files, and pretty much behave like
72 you'd expect. The syntax is slightly different in that a single '.' is
73 used instead of the hash mark, i.e. ".include <bsd.prog.mk>".
75 One difference that will save you lots of debugging time is that inclusion
76 of the file is normally done at the *end* of the Makefile. The reason for
77 this is because .mk files often modify variables and behavior based on the
78 values of variables set in the Makefile. To make this work, remember that
79 the FIRST target found is the target that is used, i.e. if the Makefile has:
86 the command "make a" will echo "a". To make things confusing, the SECOND
87 variable assignment is the overriding one, i.e. if the Makefile has:
95 the command "make b" will echo "bar". This is for compatibility with the
96 way the V7 make behaved.
98 It's fairly difficult to make the BSD .mk files work when you're building
99 multiple programs in a single directory. It's a lot easier to split up
100 the programs than to deal with the problem. Most of the agony comes from
101 making the "obj" directory stuff work right, not because we switch to a new
102 version of make. So, don't get mad at us, figure out a better way to handle
103 multiple architectures so we can quit using the symbolic link stuff.
104 (Imake doesn't count.)
106 The file .depend in the source directory is expected to contain dependencies
107 for the source files. This file is read automatically by make after reading
110 The variable DESTDIR works as before. It's not set anywhere but will change
111 the tree where the file gets installed.
113 The profiled libraries are no longer built in a different directory than
114 the regular libraries. A new suffix, ".po", is used to denote a profiled
117 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
119 The following variables are common:
121 CFLAGS.${COMPILER_TYPE}
122 Flags dependent on compiler added to CXXFLAGS.
123 CFLAGS.${MACHINE_ARCH}
124 Architectural flags added to CFLAGS.
125 CFLAGS_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.
128 CXXFLAGS.${COMPILER_TYPE}
129 Flags dependent on compiler added to CXXFLAGS.
130 CXXFLAGS.${MACHINE_ARCH}
131 Architectural flags added to CXXFLAGS.
133 A list of features that the compiler supports. Zero or
135 c++11 Supports full C++ 11 standard.
137 COMPILER_TYPE Type of compiler, either clang or gcc, though other
138 values are possible. Don't assume != clang == gcc.
141 A numeric constant equal to:
142 major * 10000 + minor * 100 + tiny
143 for the compiler's self-reported version.
145 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
147 The include file <sys.mk> has the default rules for all makes, in the BSD
148 environment or otherwise. You probably don't want to touch this file.
150 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
152 The include file <bsd.arch.inc.mk> includes other Makefiles for specific
153 architectures, if they exist. It will include the first of the following
154 files that it finds: Makefile.${MACHINE}, Makefile.${MACHINE_ARCH},
155 Makefile.${MACHINE_CPUARCH}
157 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
159 The include file <bsd.man.mk> handles installing manual pages and their
162 It has three targets:
167 install the manual pages and their links.
169 verify the validity of manual pages.
171 It sets/uses the following variables:
173 MANDIR Base path for manual installation.
181 MANSUBDIR Subdirectory under the manual page section, i.e. "/vax"
182 or "/tahoe" for machine specific manual pages.
184 MAN The manual pages to be installed (use a .1 - .9 suffix).
186 MLINKS 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.
190 The include file <bsd.man.mk> includes a file named "../Makefile.inc" if
193 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
195 The include file <bsd.own.mk> contains the owners, groups, etc. for both
196 manual pages and binaries.
200 It sets/uses the following variables:
208 MANDIR Base path for manual installation.
216 This file is generally useful when building your own Makefiles so that
217 they use the same default owners etc. as the rest of the tree.
219 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
221 The include file <bsd.prog.mk> handles building programs from one or
222 more source files, along with their manual pages. It has a limited number
223 of suffixes, consistent with the current needs of the BSD tree.
225 It has seven targets:
228 build the program and its manual page
230 remove the program and any object files.
232 remove all of the files removed by the target clean, as
233 well as .depend, tags, and any manual pages.
235 make the dependencies for the source files, and store
236 them in the file .depend.
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
244 run lint on the source files
246 create a tags file for the source files.
248 It sets/uses the following variables:
256 CLEANFILES Additional files to remove and
257 CLEANDIRS additional directories to remove during clean and cleandir
258 targets. "rm -f" and "rm -rf" used respectively.
260 CFLAGS Flags to the compiler when creating C objects.
262 FILES 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>.
267 LDADD Additional loader objects. Usually used for libraries.
268 For example, to load with the compatibility and utility
271 LDADD=-lutil -lcompat
273 LDFLAGS 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.
277 LINKS 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:
282 LINKS= ${DESTDIR}/bin/test ${DESTDIR}/bin/[
284 MAN Manual pages (should end in .1 - .9). If no MAN variable
285 is defined, "MAN=${PROG}.1" is assumed.
287 PROG The name of the program to build. If not supplied, nothing
290 PROG_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.
295 PROGS When used with <bsd.progs.mk>, allow building multiple
296 PROGS_CXX PROG and PROGS_CXX in one Makefile. To define
297 individual variables for each program the VAR.prog
298 syntax should be used. For example:
305 The supported variables are BINDIR BINGRP BINMODE BINOWN
306 CFLAGS CPPFLAGS CXXFLAGS DPADD DPLIBS DPSRCS LDADD
307 LDFLAGS LIBADD MAN MLINKS PROGNAME SRCS.
309 PROGNAME The name that the above program will be installed as, if
310 different from ${PROG}.
312 SRCS List of source files to build the program. If SRCS is not
313 defined, it's assumed to be ${PROG}.c or, if PROG_CXX is
314 defined, ${PROG_CXX}.cc.
316 DPADD Additional dependencies for the program. Usually used for
317 libraries. For example, to depend on the compatibility and
318 utility libraries use:
320 DPADD=${LIBCOMPAT} ${LIBUTIL}
322 There is a predefined identifier for each (non-profiled,
323 non-shared) library and object. Library file names are
324 transformed to identifiers by removing the extension and
325 converting to upper case.
327 There are no special identifiers for profiled or shared
328 libraries or objects. The identifiers for the standard
329 libraries are used in DPADD. This works correctly iff all
330 the libraries are built at the same time. Unfortunately,
331 it causes unnecessary relinks to shared libraries when
332 only the static libraries have changed. Dependencies on
333 shared libraries should be only on the library version
336 STRIP The flag passed to the install program to cause the binary
337 to be stripped. This is to be used when building your
338 own install script so that the entire system can be made
339 stripped/not-stripped using a single nob.
341 SUBDIR A list of subdirectories that should be built as well.
342 Each of the targets will execute the same target in the
345 SCRIPTS A list of interpreter scripts [file.{sh,csh,pl,awk,...}].
346 The installation is controlled by the SCRIPTSNAME, SCRIPTSOWN,
347 SCRIPTSGRP, SCRIPTSMODE, SCRIPTSDIR variables that can be
348 further specialized by SCRIPTS<VAR>_<script>.
350 The include file <bsd.prog.mk> includes the file named "../Makefile.inc"
351 if it exists, as well as the include file <bsd.man.mk>.
353 Some simple examples:
355 To build foo from foo.c with a manual page foo.1, use:
359 .include <bsd.prog.mk>
361 To build foo from foo.c with a manual page foo.2, add the line:
365 If foo does not have a manual page at all, add the line:
369 If foo has multiple source files, add the line:
371 SRCS= a.c b.c c.c d.c
373 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
375 The include file <bsd.subdir.mk> contains the default targets for building
376 subdirectories. It has the same seven targets as <bsd.prog.mk>: all, clean,
377 cleandir, depend, install, lint, and tags. For all of the directories
378 listed in the variable SUBDIRS, the specified directory will be visited
379 and the target made. There is also a default target which allows the
380 command "make subdir" where subdir is any directory listed in the variable
383 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
385 The include file <bsd.lib.mk> has support for building libraries. It has
386 the same seven targets as <bsd.prog.mk>: all, clean, cleandir, depend,
387 install, lint, and tags. It has a limited number of suffixes, consistent
388 with the current needs of the BSD tree.
390 It sets/uses the following variables:
392 LIB The name of the library to build.
394 LIB_CXX The name of the library to build. It also causes
395 <bsd.lib.mk> to link the library with the
396 standard C++ library. LIB_CXX overrides the value
397 of LIB if LIB is also set.
399 LIBDIR Target directory for libraries.
401 LINTLIBDIR Target directory for lint libraries.
403 LIBGRP Library group.
405 LIBOWN Library owner.
407 LIBMODE Library mode.
409 LDADD Additional loader objects.
411 MAN The manual pages to be installed (use a .1 - .9 suffix).
413 SRCS List of source files to build the library. Suffix types
414 .s, .c, and .f are supported. Note, .s files are preferred
415 to .c files of the same name. (This is not the default for
418 SHLIB_LDSCRIPT Template file to generate shared library linker script.
419 Unless used, a simple symlink is created to the real
422 LIBRARIES_ONLY Do not build or install files other than the library.
424 The include file <bsd.lib.mk> includes the file named "../Makefile.inc"
425 if it exists, as well as the include file <bsd.man.mk>.
427 It has rules for building profiled objects; profiled libraries are
430 Libraries are ranlib'd before installation.
432 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
434 The include file <bsd.test.mk> handles building one or more test programs
435 intended to be used in the FreeBSD Test Suite under /usr/tests/.
437 It has seven targets:
440 build the test programs.
442 remove the test programs and any object files.
444 remove all of the files removed by the target clean, as
445 well as .depend and tags.
447 make the dependencies for the source files, and store
448 them in the file .depend.
450 install the test programs and their data files; if the
451 Makefile does not itself define the target install, the
452 targets beforeinstall and afterinstall may also be used
453 to cause actions immediately before and after the
454 install target is executed.
456 run lint on the source files.
458 create a tags file for the source files.
460 runs the test programs from the object directory; if the
461 Makefile does not itself define the target test, the
462 targets beforetest and aftertest may also be used to
463 cause actions immediately before and after the test
466 It sets/uses the following variables, among many others:
468 TESTDIR Path to the installed tests. Must be a subdirectory of
469 TESTSBASE and the subpath should match the relative
470 location of the tests within the src tree.
472 KYUAFILE If 'auto' (the default), generate a Kyuafile out of the
473 test programs defined in the Makefile. If 'yes', then a
474 manually-crafted Kyuafile must be supplied with the
475 sources. If 'no', no Kyuafile is installed (useful for
476 subdirectories providing helper programs or data files
479 ATF_TESTS_C The names of the ATF C test programs to build.
481 ATF_TESTS_CXX The names of the ATF C++ test programs to build.
483 ATF_TESTS_SH The names of the ATF sh test programs to build.
485 PLAIN_TESTS_C The names of the plain (legacy) programs to build.
487 PLAIN_TESTS_CXX The names of the plain (legacy) test programs to build.
489 PLAIN_TESTS_SH The names of the plain (legacy) test programs to build.
492 Path to the Perl interpreter to be used for
493 TAP-compliant test programs that are written in Perl.
494 Refer to TAP_TESTS_PERL for details.
496 TAP_TESTS_C The names of the TAP-compliant C test programs to build.
498 TAP_TESTS_CXX The names of the TAP-compliant C++ test programs to
501 TAP_TESTS_PERL The names of the TAP-compliant Perl test programs to
502 build. The corresponding source files should end with
503 the .pl extension; the test program is marked as
504 requiring Perl; and TAP_PERL_INTERPRETER is used in the
505 built scripts as the interpreter of choice.
507 TAP_TESTS_SH The names of the TAP-compliant sh test programs to
510 TESTS_SUBDIRS List of subdirectories containing tests into which to
511 recurse. Differs from SUBDIR in that these directories
512 get registered into the automatically-generated
516 If defined, none of the built test programs get
517 installed under /usr/tests/ and no Kyuafile is
518 automatically generated. Should not be used within the
519 FreeBSD source tree but is provided for the benefit of
522 The actual building of the test programs is performed by <bsd.prog.mk>.
523 Please see the documentation above for this other file for additional
524 details on the behavior of <bsd.test.mk>.