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
117 object, and ".pico" denotes a position-independent relocatable object.
119 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
121 The following variables are common:
124 Flags dependent on source file name.
126 Flags dependent on source file name.
128 Flags dependent on source file name.
129 CFLAGS.${COMPILER_TYPE}
130 Flags dependent on compiler added to CFLAGS.
131 CFLAGS.${MACHINE_ARCH}
132 Architectural flags added to CFLAGS.
133 CFLAGS_NO_SIMD Add this to CFLAGS for programs that don't want any SIMD
134 instructions generated. It is setup in bsd.cpu.mk to an
135 appropriate value for the compiler and target.
136 CXXFLAGS.${COMPILER_TYPE}
137 Flags dependent on compiler added to CXXFLAGS.
138 CXXFLAGS.${MACHINE_ARCH}
139 Architectural flags added to CXXFLAGS.
141 Flags dependent on source file name.
143 A list of features that the compiler supports. Zero or
145 c++11 Supports full C++ 11 standard.
147 COMPILER_TYPE Type of compiler, either clang or gcc, though other
148 values are possible. Don't assume != clang == gcc.
151 A numeric constant equal to:
152 major * 10000 + minor * 100 + tiny
153 for the compiler's self-reported version.
155 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
157 The include file <sys.mk> has the default rules for all makes, in the BSD
158 environment or otherwise. You probably don't want to touch this file.
160 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
162 The include file <bsd.arch.inc.mk> includes other Makefiles for specific
163 architectures, if they exist. It will include the first of the following
164 files that it finds: Makefile.${MACHINE}, Makefile.${MACHINE_ARCH},
165 Makefile.${MACHINE_CPUARCH}
167 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
169 The include file <bsd.man.mk> handles installing manual pages and their
172 It has three targets:
177 install the manual pages and their links.
179 verify the validity of manual pages.
181 It sets/uses the following variables:
183 MAN The manual pages to be installed (use a .1 - .9 suffix).
185 MANDIR Base path for manual installation.
193 MANSUBDIR Subdirectory under the manual page section, i.e. "/vax"
194 or "/tahoe" for machine specific manual pages.
196 MLINKS List of manual page links (using a .1 - .9 suffix). The
197 linked-to file must come first, the linked file second,
198 and there may be multiple pairs. The files are hard-linked.
200 The include file <bsd.man.mk> includes a file named "../Makefile.inc" if
203 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
205 The include file <bsd.own.mk> contains the owners, groups, etc. for both
206 manual pages and binaries.
210 It sets/uses the following variables:
218 MANDIR Base path for manual installation.
226 This file is generally useful when building your own Makefiles so that
227 they use the same default owners etc. as the rest of the tree.
229 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
231 The include file <bsd.prog.mk> handles building programs from one or
232 more source files, along with their manual pages. It has a limited number
233 of suffixes, consistent with the current needs of the BSD tree.
235 It has seven targets:
238 build the program and its manual page
240 remove the program and any object files.
242 remove all of the files removed by the target clean, as
243 well as .depend, tags, and any manual pages.
245 make the dependencies for the source files, and store
246 them in the file .depend.
248 install the program and its manual pages; if the Makefile
249 does not itself define the target install, the targets
250 beforeinstall and afterinstall may also be used to cause
251 actions immediately before and after the install target
254 create a tags file for the source files.
256 It sets/uses the following variables:
258 ACFLAGS Flags to the compiler when preprocessing and
261 AFLAGS Flags to the assembler when assembling .s files.
269 CFLAGS Flags to the compiler when creating C objects.
271 CLEANDIRS Additional files (CLEANFILES) and directories (CLEANDIRS) to
272 CLEANFILES remove during clean and cleandir targets. "rm -rf" and
273 "rm -f" are used, respectively.
275 DPADD Additional dependencies for the program. Usually used for
276 libraries. For example, to depend on the compatibility and
277 utility libraries use:
279 DPADD=${LIBCOMPAT} ${LIBUTIL}
281 There is a predefined identifier for each (non-profiled,
282 non-shared) library and object. Library file names are
283 transformed to identifiers by removing the extension and
284 converting to upper case.
286 There are no special identifiers for profiled or shared
287 libraries or objects. The identifiers for the standard
288 libraries are used in DPADD. This works correctly iff all
289 the libraries are built at the same time. Unfortunately,
290 it causes unnecessary relinks to shared libraries when
291 only the static libraries have changed. Dependencies on
292 shared libraries should be only on the library version
295 FILES A list of non-executable files.
296 The installation is controlled by the FILESNAME, FILESOWN,
297 FILESGRP, FILESMODE, FILESDIR variables that can be
298 further specialized by FILES<VAR>_<file>.
300 LDADD Additional loader objects. Usually used for libraries.
301 For example, to load with the compatibility and utility
304 LDADD=-lutil -lcompat
306 LDFLAGS Additional loader flags. Passed to the loader via CC,
307 since that's used to link programs as well, so loader
308 specific flags need to be prefixed with -Wl, to work.
310 LIBADD Additional libraries. This is for base system libraries
311 and is only valid inside of the /usr/src tree.
312 Use LIBADD=name instead of LDADD=-lname.
314 LINKS The list of binary links; should be full pathnames, the
315 linked-to file coming first, followed by the linked
316 file. The files are hard-linked. For example, to link
317 /bin/test and /bin/[, use:
319 LINKS= /bin/test /bin/[
321 MAN Manual pages. If no MAN variable is defined,
322 "MAN=${PROG}.1" is assumed. See bsd.man.mk for more details.
324 PROG The name of the program to build. If not supplied, nothing
327 PROGNAME The name that the above program will be installed as, if
328 different from ${PROG}.
330 PROG_CXX If defined, the name of the program to build. Also
331 causes <bsd.prog.mk> to link the program with the
332 standard C++ library. PROG_CXX overrides the value
333 of PROG if PROG is also set.
335 PROGS When used with <bsd.progs.mk>, allow building multiple
336 PROGS_CXX PROG and PROG_CXX in one Makefile. To define
337 individual variables for each program the VAR.prog
338 syntax should be used. For example:
345 The supported variables are:
355 - INTERNALPROG (no installation)
368 SCRIPTS A list of interpreter scripts [file.{sh,csh,pl,awk,...}].
369 The installation is controlled by the SCRIPTSNAME, SCRIPTSOWN,
370 SCRIPTSGRP, SCRIPTSMODE, SCRIPTSDIR variables that can be
371 further specialized by SCRIPTS<VAR>_<script>.
373 SRCS List of source files to build the program. If SRCS is not
374 defined, it's assumed to be ${PROG}.c or, if PROG_CXX is
375 defined, ${PROG_CXX}.cc.
377 STRIP The flag passed to the install program to cause the binary
378 to be stripped. This is to be used when building your
379 own install script so that the entire system can be made
380 stripped/not-stripped using a single nob.
382 SUBDIR A list of subdirectories that should be built as well.
383 Each of the targets will execute the same target in the
386 The include file <bsd.prog.mk> includes the file named "../Makefile.inc"
387 if it exists, as well as the include file <bsd.man.mk>.
389 Some simple examples:
391 To build foo from foo.c with a manual page foo.1, use:
395 .include <bsd.prog.mk>
397 To build foo from foo.c with a manual page foo.2, add the line:
401 If foo does not have a manual page at all, add the line:
405 If foo has multiple source files, add the line:
407 SRCS= a.c b.c c.c d.c
409 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
411 The include file, <bsd.snmpmod.mk>, handles building MIB modules for bsnmpd
412 from one or more source files, along with their manual pages. It has a
413 limited number of suffixes, consistent with the current needs of the BSD
416 bsd.snmpmod.mk leverages bsd.lib.mk for building MIB modules and
417 bsd.files.mk for installing MIB description and definition files.
419 It implements the following additional targets:
422 execute smilint on the MIBs defined by BMIBS.
424 The net-mgmt/libsmi package must be installed before
425 executing this target. The net-mgmt/net-snmp package
426 should be installed as well to reduce false positives
429 It sets/uses the following variables:
431 BMIBS The MIB definitions to install.
433 BMIBSDIR The directory where the MIB definitions are installed.
434 This defaults to `${SHAREDIR}/snmp/mibs`.
436 DEFS The MIB description files to install.
438 DEFSDIR The directory where MIB description files are installed.
439 This defaults to `${SHAREDIR}/snmp/defs`.
441 EXTRAMIBDEFS Extra MIB description files to use as input when
442 generating ${MOD}_oid.h and ${MOD}_tree.[ch].
444 EXTRAMIBSYMS Extra MIB definition files used only for extracting
447 EXTRAMIBSYMS are useful when resolving inter-module
448 dependencies and are useful with files containing only
451 See ${MOD}_oid.h for more details.
453 LOCALBASE The package root where smilint and the net-snmp
454 definitions can be found
456 MOD The bsnmpd module name.
458 SMILINT smilint binary to use with the smilint make target.
460 SMILINT_FLAGS flags to pass to smilint.
462 SMIPATH A colon-separated directory path where MIBs definitions
463 can be found. See "SMIPATH" in smi_config for more
466 XSYM MIB names to extract symbols for. See ${MOD}_oid.h for
469 It generates the following files:
471 ${MOD}_tree.c A source file and header which programmatically describes
472 ${MOD}_tree.h the MIB (type, OID name, ACCESS attributes, etc).
474 The files are generated via "gensnmptree -p".
476 See gensnmptree(1) for more details.
478 ${MOD}_oid.h A header which programmatically describes the MIB root and
481 The files are generated via "gensnmptree -e".
483 See gensnmptree(1) for more details.
485 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
487 The include file <bsd.subdir.mk> contains the default targets for building
488 subdirectories. It has the same seven targets as <bsd.prog.mk>: all, clean,
489 cleandir, depend, install, and tags. For all of the directories listed in the
490 variable SUBDIRS, the specified directory will be visited and the target made.
491 There is also a default target which allows the command "make subdir" where
492 subdir is any directory listed in the variable SUBDIRS.
494 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
496 The include file <bsd.lib.mk> has support for building libraries. It has the
497 same seven targets as <bsd.prog.mk>: all, clean, cleandir, depend, install, and
498 tags. It has a limited number of suffixes, consistent with the current needs of
501 It sets/uses the following variables:
503 LDADD Additional loader objects.
505 LIB The name of the library to build. Both a shared and static
506 library will be built. NO_PIC can be set to only build a
509 LIBADD Additional libraries. This is for base system libraries
510 and is only valid inside of the /usr/src tree.
511 Use LIBADD=name instead of LDADD=-lname.
513 LIBDIR Target directory for libraries.
515 LIBGRP Library group.
517 LIBMODE Library mode.
519 LIBOWN Library owner.
521 LIBRARIES_ONLY Do not build or install files other than the library.
523 LIB_CXX The name of the library to build. It also causes
524 <bsd.lib.mk> to link the library with the
525 standard C++ library. LIB_CXX overrides the value
526 of LIB if LIB is also set. Both a shared and static library
527 will be built. NO_PIC can be set to only build a static
530 MAN The manual pages to be installed. See bsd.man.mk for more
533 SHLIB Like LIB but only builds a shared library.
535 SHLIB_CXX Like LIB_CXX but only builds a shared library.
537 SHLIB_LDSCRIPT Template file to generate shared library linker script.
538 If not defined, a simple symlink is created to the real
541 SRCS List of source files to build the library. Suffix types
542 .s, .c, and .f are supported. Note, .s files are preferred
543 to .c files of the same name. (This is not the default for
546 The include file <bsd.lib.mk> includes the file named "../Makefile.inc"
547 if it exists, as well as the include file <bsd.man.mk>.
549 It has rules for building profiled objects; profiled libraries are
552 Libraries are ranlib'd before installation.
554 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
556 The include file <bsd.test.mk> handles building one or more test programs
557 intended to be used in the FreeBSD Test Suite under /usr/tests/.
559 It has seven targets:
562 build the test programs.
564 runs the test programs with kyua test.
566 The beforecheck and aftercheck targets will be invoked, if
567 defined, to execute commands before and after the realcheck
568 target has been executed, respectively.
570 The devel/kyua package must be installed before invoking this
573 remove the test programs and any object files.
575 remove all of the files removed by the target clean, as
576 well as .depend and tags.
578 make the dependencies for the source files, and store
579 them in the file .depend.
581 install the test programs and their data files; if the
582 Makefile does not itself define the target install, the
583 targets beforeinstall and afterinstall may also be used
584 to cause actions immediately before and after the
585 install target is executed.
587 create a tags file for the source files.
589 It sets/uses the following variables, among many others:
591 ATF_TESTS_C The names of the ATF C test programs to build.
593 ATF_TESTS_CXX The names of the ATF C++ test programs to build.
595 ATF_TESTS_SH The names of the ATF sh test programs to build.
597 KYUAFILE If 'auto' (the default), generate a Kyuafile out of the
598 test programs defined in the Makefile. If 'yes', then a
599 manually-crafted Kyuafile must be supplied with the
600 sources. If 'no', no Kyuafile is installed (useful for
601 subdirectories providing helper programs or data files
604 LOCALBASE The --prefix for the kyua package.
606 The value of LOCALBASE defaults to /usr/local .
609 If defined, none of the built test programs get
610 installed under /usr/tests/ and no Kyuafile is
611 automatically generated. Should not be used within the
612 FreeBSD source tree but is provided for the benefit of
615 PLAIN_TESTS_C The names of the plain (legacy) programs to build.
617 PLAIN_TESTS_CXX The names of the plain (legacy) test programs to build.
619 PLAIN_TESTS_SH The names of the plain (legacy) test programs to build.
622 Path to the Perl interpreter to be used for
623 TAP-compliant test programs that are written in Perl.
624 Refer to TAP_TESTS_PERL for details.
626 TAP_TESTS_C The names of the TAP-compliant C test programs to build.
628 TAP_TESTS_CXX The names of the TAP-compliant C++ test programs to
631 TAP_TESTS_PERL The names of the TAP-compliant Perl test programs to
632 build. The corresponding source files should end with
633 the .pl extension; the test program is marked as
634 requiring Perl; and TAP_PERL_INTERPRETER is used in the
635 built scripts as the interpreter of choice.
637 TAP_TESTS_SH The names of the TAP-compliant sh test programs to
640 TESTSBASE Installation prefix for tests. Defaults to /usr/tests
642 TESTSDIR Path to the installed tests. Must be a subdirectory of
643 TESTSBASE and the subpath should match the relative
644 location of the tests within the src tree.
646 The value of TESTSDIR defaults to
647 ${TESTSBASE}/${RELDIR:H} , e.g. /usr/tests/bin/ls when
648 included from bin/ls/tests .
650 TESTS_SUBDIRS List of subdirectories containing tests into which to
651 recurse. Differs from SUBDIR in that these directories
652 get registered into the automatically-generated
655 The actual building of the test programs is performed by <bsd.prog.mk>.
656 Please see the documentation above for this other file for additional
657 details on the behavior of <bsd.test.mk>.