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.confs.mk - install of configuration files
22 bsd.cpu.mk - sets CPU/arch-related variables (included from sys.mk)
23 bsd.crunchgen.mk - building crunched binaries using crunchgen(1)
24 bsd.dep.mk - handle Makefile dependencies
25 bsd.doc.mk - building troff system documents
26 bsd.endian.mk - TARGET_ENDIAN=1234(little) or 4321 (big) for target
27 bsd.files.mk - install of general purpose files
28 bsd.incs.mk - install of include files
29 bsd.info.mk - building GNU Info hypertext system (deprecated)
30 bsd.init.mk - initialization for the make include files
31 bsd.kmod.mk - building loadable kernel modules
32 bsd.lib.mk - support for building libraries
33 bsd.libnames.mk - define library names
34 bsd.links.mk - install of links (sym/hard)
35 bsd.man.mk - install of manual pages and their links
36 bsd.nls.mk - build and install of NLS catalogs
37 bsd.obj.mk - creating 'obj' directories and cleaning up
38 bsd.own.mk - define common variables
39 bsd.port.mk - building ports
40 bsd.port.post.mk - building ports
41 bsd.port.pre.mk - building ports
42 bsd.port.subdir.mk - targets for building subdirectories for ports
43 bsd.prog.mk - building programs from source files
44 bsd.progs.mk - build multiple programs from sources
45 bsd.snmpmod.mk - building modules for the SNMP daemon bsnmpd
46 bsd.subdir.mk - targets for building subdirectories
47 bsd.sys.mk - common settings used for building FreeBSD sources
48 bsd.test.mk - building test programs from source files
49 sys.mk - default rules for all makes
51 This file does not document bsd.port*.mk. They are documented in ports(7).
53 See also make(1), mkdep(1), style.Makefile(5) and `PMake - A
54 Tutorial', located in /usr/share/doc/psd/12.make.
56 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
58 Random things worth knowing about this document:
60 If appropriate when documenting the variables the default value is
61 indicated using square brackets e.g. [gzip].
62 In some cases the default value depend on other values (e.g. system
63 architecture). In these cases the most common value is indicated.
65 This document contains some simple examples of the usage of the BSD make
66 include files. For more examples look at the makefiles in the FreeBSD
69 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
71 RANDOM THINGS WORTH KNOWING:
73 The files are like C-style #include files, and pretty much behave like
74 you'd expect. The syntax is slightly different in that a single '.' is
75 used instead of the hash mark, i.e. ".include <bsd.prog.mk>".
77 One difference that will save you lots of debugging time is that inclusion
78 of the file is normally done at the *end* of the Makefile. The reason for
79 this is because .mk files often modify variables and behavior based on the
80 values of variables set in the Makefile. To make this work, remember that
81 the FIRST target found is the target that is used, i.e. if the Makefile has:
88 the command "make a" will echo "a". To make things confusing, the SECOND
89 variable assignment is the overriding one, i.e. if the Makefile has:
97 the command "make b" will echo "bar". This is for compatibility with the
98 way the V7 make behaved.
100 It's fairly difficult to make the BSD .mk files work when you're building
101 multiple programs in a single directory. It's a lot easier to split up
102 the programs than to deal with the problem. Most of the agony comes from
103 making the "obj" directory stuff work right, not because we switch to a new
104 version of make. So, don't get mad at us, figure out a better way to handle
105 multiple architectures so we can quit using the symbolic link stuff.
106 (Imake doesn't count.)
108 The file .depend in the source directory is expected to contain dependencies
109 for the source files. This file is read automatically by make after reading
112 The variable DESTDIR works as before. It's not set anywhere but will change
113 the tree where the file gets installed.
115 The profiled libraries are no longer built in a different directory than
116 the regular libraries. A new suffix, ".po", is used to denote a profiled
119 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
121 The following variables are common:
124 Flags dependent on source file name.
126 Flags dependent on source file name.
127 CFLAGS.${COMPILER_TYPE}
128 Flags dependent on compiler added to CXXFLAGS.
129 CFLAGS.${MACHINE_ARCH}
130 Architectural flags added to CFLAGS.
131 CFLAGS_NO_SIMD Add this to CFLAGS for programs that don't want any SIMD
132 instructions generated. It is setup in bsd.cpu.mk to an
133 appropriate value for the compiler and target.
134 CXXFLAGS.${COMPILER_TYPE}
135 Flags dependent on compiler added to CXXFLAGS.
136 CXXFLAGS.${MACHINE_ARCH}
137 Architectural flags added to CXXFLAGS.
139 Flags dependent on source file name.
141 A list of features that the compiler supports. Zero or
143 c++11 Supports full C++ 11 standard.
145 COMPILER_TYPE Type of compiler, either clang or gcc, though other
146 values are possible. Don't assume != clang == gcc.
149 A numeric constant equal to:
150 major * 10000 + minor * 100 + tiny
151 for the compiler's self-reported version.
153 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
155 The include file <sys.mk> has the default rules for all makes, in the BSD
156 environment or otherwise. You probably don't want to touch this file.
158 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
160 The include file <bsd.arch.inc.mk> includes other Makefiles for specific
161 architectures, if they exist. It will include the first of the following
162 files that it finds: Makefile.${MACHINE}, Makefile.${MACHINE_ARCH},
163 Makefile.${MACHINE_CPUARCH}
165 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
167 The include file <bsd.man.mk> handles installing manual pages and their
170 It has three targets:
175 install the manual pages and their links.
177 verify the validity of manual pages.
179 It sets/uses the following variables:
181 MANDIR Base path for manual installation.
189 MANSUBDIR Subdirectory under the manual page section, i.e. "/vax"
190 or "/tahoe" for machine specific manual pages.
192 MAN The manual pages to be installed (use a .1 - .9 suffix).
194 MLINKS List of manual page links (using a .1 - .9 suffix). The
195 linked-to file must come first, the linked file second,
196 and there may be multiple pairs. The files are hard-linked.
198 The include file <bsd.man.mk> includes a file named "../Makefile.inc" if
201 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
203 The include file <bsd.own.mk> contains the owners, groups, etc. for both
204 manual pages and binaries.
208 It sets/uses the following variables:
216 MANDIR Base path for manual installation.
224 This file is generally useful when building your own Makefiles so that
225 they use the same default owners etc. as the rest of the tree.
227 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
229 The include file <bsd.prog.mk> handles building programs from one or
230 more source files, along with their manual pages. It has a limited number
231 of suffixes, consistent with the current needs of the BSD tree.
233 It has seven targets:
236 build the program and its manual page
238 remove the program and any object files.
240 remove all of the files removed by the target clean, as
241 well as .depend, tags, and any manual pages.
243 make the dependencies for the source files, and store
244 them in the file .depend.
246 install the program and its manual pages; if the Makefile
247 does not itself define the target install, the targets
248 beforeinstall and afterinstall may also be used to cause
249 actions immediately before and after the install target
252 run lint on the source files
254 create a tags file for the source files.
256 It sets/uses the following variables:
264 CLEANFILES Additional files to remove and
265 CLEANDIRS additional directories to remove during clean and cleandir
266 targets. "rm -f" and "rm -rf" used respectively.
268 CFLAGS Flags to the compiler when creating C objects.
270 FILES A list of non-executable files.
271 The installation is controlled by the FILESNAME, FILESOWN,
272 FILESGRP, FILESMODE, FILESDIR variables that can be
273 further specialized by FILES<VAR>_<file>.
275 LDADD Additional loader objects. Usually used for libraries.
276 For example, to load with the compatibility and utility
279 LDADD=-lutil -lcompat
281 LIBADD Additional libraries. This is for base system libraries
282 and is only valid inside of the /usr/src tree.
283 Rather than use LDADD=-lname use LIBADD=name.
285 LDFLAGS Additional loader flags. Passed to the loader via CC,
286 since that's used to link programs as well, so loader
287 specific flags need to be prefixed with -Wl, to work.
289 LINKS The list of binary links; should be full pathnames, the
290 linked-to file coming first, followed by the linked
291 file. The files are hard-linked. For example, to link
292 /bin/test and /bin/[, use:
294 LINKS= ${DESTDIR}/bin/test ${DESTDIR}/bin/[
296 MAN Manual pages (should end in .1 - .9). If no MAN variable
297 is defined, "MAN=${PROG}.1" is assumed.
299 PROG The name of the program to build. If not supplied, nothing
302 PROG_CXX If defined, the name of the program to build. Also
303 causes <bsd.prog.mk> to link the program with the
304 standard C++ library. PROG_CXX overrides the value
305 of PROG if PROG is also set.
307 PROGS When used with <bsd.progs.mk>, allow building multiple
308 PROGS_CXX PROG and PROGS_CXX in one Makefile. To define
309 individual variables for each program the VAR.prog
310 syntax should be used. For example:
317 The supported variables are:
339 PROGNAME The name that the above program will be installed as, if
340 different from ${PROG}.
342 SRCS List of source files to build the program. If SRCS is not
343 defined, it's assumed to be ${PROG}.c or, if PROG_CXX is
344 defined, ${PROG_CXX}.cc.
346 DPADD Additional dependencies for the program. Usually used for
347 libraries. For example, to depend on the compatibility and
348 utility libraries use:
350 DPADD=${LIBCOMPAT} ${LIBUTIL}
352 There is a predefined identifier for each (non-profiled,
353 non-shared) library and object. Library file names are
354 transformed to identifiers by removing the extension and
355 converting to upper case.
357 There are no special identifiers for profiled or shared
358 libraries or objects. The identifiers for the standard
359 libraries are used in DPADD. This works correctly iff all
360 the libraries are built at the same time. Unfortunately,
361 it causes unnecessary relinks to shared libraries when
362 only the static libraries have changed. Dependencies on
363 shared libraries should be only on the library version
366 STRIP The flag passed to the install program to cause the binary
367 to be stripped. This is to be used when building your
368 own install script so that the entire system can be made
369 stripped/not-stripped using a single nob.
371 SUBDIR A list of subdirectories that should be built as well.
372 Each of the targets will execute the same target in the
375 SCRIPTS A list of interpreter scripts [file.{sh,csh,pl,awk,...}].
376 The installation is controlled by the SCRIPTSNAME, SCRIPTSOWN,
377 SCRIPTSGRP, SCRIPTSMODE, SCRIPTSDIR variables that can be
378 further specialized by SCRIPTS<VAR>_<script>.
380 The include file <bsd.prog.mk> includes the file named "../Makefile.inc"
381 if it exists, as well as the include file <bsd.man.mk>.
383 Some simple examples:
385 To build foo from foo.c with a manual page foo.1, use:
389 .include <bsd.prog.mk>
391 To build foo from foo.c with a manual page foo.2, add the line:
395 If foo does not have a manual page at all, add the line:
399 If foo has multiple source files, add the line:
401 SRCS= a.c b.c c.c d.c
403 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
405 The include file <bsd.subdir.mk> contains the default targets for building
406 subdirectories. It has the same seven targets as <bsd.prog.mk>: all, clean,
407 cleandir, depend, install, lint, and tags. For all of the directories
408 listed in the variable SUBDIRS, the specified directory will be visited
409 and the target made. There is also a default target which allows the
410 command "make subdir" where subdir is any directory listed in the variable
413 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
415 The include file <bsd.lib.mk> has support for building libraries. It has
416 the same seven targets as <bsd.prog.mk>: all, clean, cleandir, depend,
417 install, lint, and tags. It has a limited number of suffixes, consistent
418 with the current needs of the BSD tree.
420 It sets/uses the following variables:
422 LIB The name of the library to build. Both a shared and static
423 library will be built. NO_PIC can be set to only build a
426 LIB_CXX The name of the library to build. It also causes
427 <bsd.lib.mk> to link the library with the
428 standard C++ library. LIB_CXX overrides the value
429 of LIB if LIB is also set. Both a shared and static library
430 will be built. NO_PIC can be set to only build a static
433 LIBDIR Target directory for libraries.
435 LINTLIBDIR Target directory for lint libraries.
437 LIBGRP Library group.
439 LIBOWN Library owner.
441 LIBMODE Library mode.
443 LDADD Additional loader objects.
445 LIBADD Additional libraries. This is for base system libraries
446 and is only valid inside of the /usr/src tree.
447 Rather than use LDADD=-lname use LIBADD=name.
449 MAN The manual pages to be installed (use a .1 - .9 suffix).
451 SRCS List of source files to build the library. Suffix types
452 .s, .c, and .f are supported. Note, .s files are preferred
453 to .c files of the same name. (This is not the default for
456 SHLIB Like LIB but only builds a shared library.
458 SHLIB_CXX Like LIB_CXX but only builds a shared library.
460 SHLIB_LDSCRIPT Template file to generate shared library linker script.
461 Unless used, a simple symlink is created to the real
464 LIBRARIES_ONLY Do not build or install files other than the library.
466 The include file <bsd.lib.mk> includes the file named "../Makefile.inc"
467 if it exists, as well as the include file <bsd.man.mk>.
469 It has rules for building profiled objects; profiled libraries are
472 Libraries are ranlib'd before installation.
474 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
476 The include file <bsd.test.mk> handles building one or more test programs
477 intended to be used in the FreeBSD Test Suite under /usr/tests/.
479 It has seven targets:
482 build the test programs.
484 runs the test programs from CHECKDIR with kyua test.
486 The beforecheck and aftercheck targets will be invoked, if
487 defined, to execute commands before and after the realcheck
488 target has been executed, respectively.
490 The devel/kyua package must be installed before invoking this
493 See CHECKDIR for more details.
495 remove the test programs and any object files.
497 remove all of the files removed by the target clean, as
498 well as .depend and tags.
500 make the dependencies for the source files, and store
501 them in the file .depend.
503 install the test programs and their data files; if the
504 Makefile does not itself define the target install, the
505 targets beforeinstall and afterinstall may also be used
506 to cause actions immediately before and after the
507 install target is executed.
509 run lint on the source files.
511 create a tags file for the source files.
513 It sets/uses the following variables, among many others:
515 TESTSBASE Installation prefix for tests. Defaults to /usr/tests
517 TESTSDIR Path to the installed tests. Must be a subdirectory of
518 TESTSBASE and the subpath should match the relative
519 location of the tests within the src tree.
521 The value of TESTSDIR defaults to
522 ${TESTSBASE}/${RELDIR:H} , e.g. /usr/tests/bin/ls when
523 included from bin/ls/tests .
525 CHECKDIR The directory that 'make check' executes tests from.
527 The value of CHECKDIR defaults to .OBJDIR.
529 KYUAFILE If 'auto' (the default), generate a Kyuafile out of the
530 test programs defined in the Makefile. If 'yes', then a
531 manually-crafted Kyuafile must be supplied with the
532 sources. If 'no', no Kyuafile is installed (useful for
533 subdirectories providing helper programs or data files
536 LOCALBASE The --prefix for the kyua package.
538 The value of LOCALBASE defaults to /usr/local .
540 ATF_TESTS_C The names of the ATF C test programs to build.
542 ATF_TESTS_CXX The names of the ATF C++ test programs to build.
544 ATF_TESTS_SH The names of the ATF sh test programs to build.
546 PLAIN_TESTS_C The names of the plain (legacy) programs to build.
548 PLAIN_TESTS_CXX The names of the plain (legacy) test programs to build.
550 PLAIN_TESTS_SH The names of the plain (legacy) test programs to build.
553 Path to the Perl interpreter to be used for
554 TAP-compliant test programs that are written in Perl.
555 Refer to TAP_TESTS_PERL for details.
557 TAP_TESTS_C The names of the TAP-compliant C test programs to build.
559 TAP_TESTS_CXX The names of the TAP-compliant C++ test programs to
562 TAP_TESTS_PERL The names of the TAP-compliant Perl test programs to
563 build. The corresponding source files should end with
564 the .pl extension; the test program is marked as
565 requiring Perl; and TAP_PERL_INTERPRETER is used in the
566 built scripts as the interpreter of choice.
568 TAP_TESTS_SH The names of the TAP-compliant sh test programs to
571 TESTS_SUBDIRS List of subdirectories containing tests into which to
572 recurse. Differs from SUBDIR in that these directories
573 get registered into the automatically-generated
577 If defined, none of the built test programs get
578 installed under /usr/tests/ and no Kyuafile is
579 automatically generated. Should not be used within the
580 FreeBSD source tree but is provided for the benefit of
583 The actual building of the test programs is performed by <bsd.prog.mk>.
584 Please see the documentation above for this other file for additional
585 details on the behavior of <bsd.test.mk>.