541 lines
19 KiB
Plaintext
541 lines
19 KiB
Plaintext
# @(#)bsd.README 8.2 (Berkeley) 4/2/94
|
|
# $FreeBSD$
|
|
|
|
This is the README file for the "include" files for the FreeBSD
|
|
source tree. The files are installed in /usr/share/mk, and are by
|
|
convention, named with the suffix ".mk". These files store several
|
|
build options and should be handled with caution.
|
|
|
|
Note, this file is not intended to replace reading through the .mk
|
|
files for anything tricky.
|
|
|
|
There are two main types of make include files. One type is the generally
|
|
usable make include files, such as bsd.prog.mk and bsd.lib.mk. The other is
|
|
the internal make include files, such as bsd.files.mk and bsd.man.mk, which
|
|
can not/should not be used directly but are used by the other make include
|
|
files. In most cases it is only interesting to include bsd.prog.mk or
|
|
bsd.lib.mk.
|
|
|
|
bsd.arch.inc.mk - includes arch-specific Makefile.$arch
|
|
bsd.compiler.mk - defined based on current compiler
|
|
bsd.confs.mk - install of configuration files
|
|
bsd.cpu.mk - sets CPU/arch-related variables (included from sys.mk)
|
|
bsd.crunchgen.mk - building crunched binaries using crunchgen(1)
|
|
bsd.dep.mk - handle Makefile dependencies
|
|
bsd.doc.mk - building troff system documents
|
|
bsd.endian.mk - TARGET_ENDIAN=1234(little) or 4321 (big) for target
|
|
bsd.files.mk - install of general purpose files
|
|
bsd.incs.mk - install of include files
|
|
bsd.info.mk - building GNU Info hypertext system (deprecated)
|
|
bsd.init.mk - initialization for the make include files
|
|
bsd.kmod.mk - building loadable kernel modules
|
|
bsd.lib.mk - support for building libraries
|
|
bsd.libnames.mk - define library names
|
|
bsd.links.mk - install of links (sym/hard)
|
|
bsd.man.mk - install of manual pages and their links
|
|
bsd.nls.mk - build and install of NLS catalogs
|
|
bsd.obj.mk - creating 'obj' directories and cleaning up
|
|
bsd.own.mk - define common variables
|
|
bsd.port.mk - building ports
|
|
bsd.port.post.mk - building ports
|
|
bsd.port.pre.mk - building ports
|
|
bsd.port.subdir.mk - targets for building subdirectories for ports
|
|
bsd.prog.mk - building programs from source files
|
|
bsd.progs.mk - build multiple programs from sources
|
|
bsd.snmpmod.mk - building modules for the SNMP daemon bsnmpd
|
|
bsd.subdir.mk - targets for building subdirectories
|
|
bsd.sys.mk - common settings used for building FreeBSD sources
|
|
bsd.test.mk - building test programs from source files
|
|
sys.mk - default rules for all makes
|
|
|
|
This file does not document bsd.port*.mk. They are documented in ports(7).
|
|
|
|
See also make(1), mkdep(1), style.Makefile(5) and `PMake - A
|
|
Tutorial', located in /usr/share/doc/psd/12.make.
|
|
|
|
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
|
|
|
|
Random things worth knowing about this document:
|
|
|
|
If appropriate when documenting the variables the default value is
|
|
indicated using square brackets e.g. [gzip].
|
|
In some cases the default value depend on other values (e.g. system
|
|
architecture). In these cases the most common value is indicated.
|
|
|
|
This document contains some simple examples of the usage of the BSD make
|
|
include files. For more examples look at the makefiles in the FreeBSD
|
|
source tree.
|
|
|
|
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
|
|
|
|
RANDOM THINGS WORTH KNOWING:
|
|
|
|
The files are like C-style #include files, and pretty much behave like
|
|
you'd expect. The syntax is slightly different in that a single '.' is
|
|
used instead of the hash mark, i.e. ".include <bsd.prog.mk>".
|
|
|
|
One difference that will save you lots of debugging time is that inclusion
|
|
of the file is normally done at the *end* of the Makefile. The reason for
|
|
this is because .mk files often modify variables and behavior based on the
|
|
values of variables set in the Makefile. To make this work, remember that
|
|
the FIRST target found is the target that is used, i.e. if the Makefile has:
|
|
|
|
a:
|
|
echo a
|
|
a:
|
|
echo a number two
|
|
|
|
the command "make a" will echo "a". To make things confusing, the SECOND
|
|
variable assignment is the overriding one, i.e. if the Makefile has:
|
|
|
|
a= foo
|
|
a= bar
|
|
|
|
b:
|
|
echo ${a}
|
|
|
|
the command "make b" will echo "bar". This is for compatibility with the
|
|
way the V7 make behaved.
|
|
|
|
It's fairly difficult to make the BSD .mk files work when you're building
|
|
multiple programs in a single directory. It's a lot easier to split up
|
|
the programs than to deal with the problem. Most of the agony comes from
|
|
making the "obj" directory stuff work right, not because we switch to a new
|
|
version of make. So, don't get mad at us, figure out a better way to handle
|
|
multiple architectures so we can quit using the symbolic link stuff.
|
|
(Imake doesn't count.)
|
|
|
|
The file .depend in the source directory is expected to contain dependencies
|
|
for the source files. This file is read automatically by make after reading
|
|
the Makefile.
|
|
|
|
The variable DESTDIR works as before. It's not set anywhere but will change
|
|
the tree where the file gets installed.
|
|
|
|
The profiled libraries are no longer built in a different directory than
|
|
the regular libraries. A new suffix, ".po", is used to denote a profiled
|
|
object.
|
|
|
|
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
|
|
|
|
The following variables are common:
|
|
|
|
CFLAGS.${COMPILER_TYPE}
|
|
Flags dependent on compiler added to CXXFLAGS.
|
|
CFLAGS.${MACHINE_ARCH}
|
|
Architectural flags added to CFLAGS.
|
|
CFLAGS_NO_SIMD Add this to CFLAGS for programs that don't want any SIMD
|
|
instructions generated. It is setup in bsd.cpu.mk to an
|
|
appropriate value for the compiler and target.
|
|
CXXFLAGS.${COMPILER_TYPE}
|
|
Flags dependent on compiler added to CXXFLAGS.
|
|
CXXFLAGS.${MACHINE_ARCH}
|
|
Architectural flags added to CXXFLAGS.
|
|
COMPILER_FEATURES
|
|
A list of features that the compiler supports. Zero or
|
|
more of:
|
|
c++11 Supports full C++ 11 standard.
|
|
|
|
COMPILER_TYPE Type of compiler, either clang or gcc, though other
|
|
values are possible. Don't assume != clang == gcc.
|
|
|
|
COMPILER_VERSION
|
|
A numeric constant equal to:
|
|
major * 10000 + minor * 100 + tiny
|
|
for the compiler's self-reported version.
|
|
|
|
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
|
|
|
|
The include file <sys.mk> has the default rules for all makes, in the BSD
|
|
environment or otherwise. You probably don't want to touch this file.
|
|
|
|
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
|
|
|
|
The include file <bsd.arch.inc.mk> includes other Makefiles for specific
|
|
architectures, if they exist. It will include the first of the following
|
|
files that it finds: Makefile.${MACHINE}, Makefile.${MACHINE_ARCH},
|
|
Makefile.${MACHINE_CPUARCH}
|
|
|
|
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
|
|
|
|
The include file <bsd.man.mk> handles installing manual pages and their
|
|
links.
|
|
|
|
It has three targets:
|
|
|
|
all-man:
|
|
build manual pages.
|
|
maninstall:
|
|
install the manual pages and their links.
|
|
manlint:
|
|
verify the validity of manual pages.
|
|
|
|
It sets/uses the following variables:
|
|
|
|
MANDIR Base path for manual installation.
|
|
|
|
MANGRP Manual group.
|
|
|
|
MANOWN Manual owner.
|
|
|
|
MANMODE Manual mode.
|
|
|
|
MANSUBDIR Subdirectory under the manual page section, i.e. "/vax"
|
|
or "/tahoe" for machine specific manual pages.
|
|
|
|
MAN The manual pages to be installed (use a .1 - .9 suffix).
|
|
|
|
MLINKS List of manual page links (using a .1 - .9 suffix). The
|
|
linked-to file must come first, the linked file second,
|
|
and there may be multiple pairs. The files are hard-linked.
|
|
|
|
The include file <bsd.man.mk> includes a file named "../Makefile.inc" if
|
|
it exists.
|
|
|
|
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
|
|
|
|
The include file <bsd.own.mk> contains the owners, groups, etc. for both
|
|
manual pages and binaries.
|
|
|
|
It has no targets.
|
|
|
|
It sets/uses the following variables:
|
|
|
|
BINGRP Binary group.
|
|
|
|
BINOWN Binary owner.
|
|
|
|
BINMODE Binary mode.
|
|
|
|
MANDIR Base path for manual installation.
|
|
|
|
MANGRP Manual group.
|
|
|
|
MANOWN Manual owner.
|
|
|
|
MANMODE Manual mode.
|
|
|
|
This file is generally useful when building your own Makefiles so that
|
|
they use the same default owners etc. as the rest of the tree.
|
|
|
|
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
|
|
|
|
The include file <bsd.prog.mk> handles building programs from one or
|
|
more source files, along with their manual pages. It has a limited number
|
|
of suffixes, consistent with the current needs of the BSD tree.
|
|
|
|
It has seven targets:
|
|
|
|
all:
|
|
build the program and its manual page
|
|
clean:
|
|
remove the program and any object files.
|
|
cleandir:
|
|
remove all of the files removed by the target clean, as
|
|
well as .depend, tags, and any manual pages.
|
|
depend:
|
|
make the dependencies for the source files, and store
|
|
them in the file .depend.
|
|
install:
|
|
install the program and its manual pages; if the Makefile
|
|
does not itself define the target install, the targets
|
|
beforeinstall and afterinstall may also be used to cause
|
|
actions immediately before and after the install target
|
|
is executed.
|
|
lint:
|
|
run lint on the source files
|
|
tags:
|
|
create a tags file for the source files.
|
|
|
|
It sets/uses the following variables:
|
|
|
|
BINGRP Binary group.
|
|
|
|
BINOWN Binary owner.
|
|
|
|
BINMODE Binary mode.
|
|
|
|
CLEANFILES Additional files to remove and
|
|
CLEANDIRS additional directories to remove during clean and cleandir
|
|
targets. "rm -f" and "rm -rf" used respectively.
|
|
|
|
CFLAGS Flags to the compiler when creating C objects.
|
|
|
|
FILES A list of non-executable files.
|
|
The installation is controlled by the FILESNAME, FILESOWN,
|
|
FILESGRP, FILESMODE, FILESDIR variables that can be
|
|
further specialized by FILES<VAR>_<file>.
|
|
|
|
LDADD Additional loader objects. Usually used for libraries.
|
|
For example, to load with the compatibility and utility
|
|
libraries, use:
|
|
|
|
LDADD=-lutil -lcompat
|
|
|
|
LIBADD Additional libraries. This is for base system libraries
|
|
and is only valid inside of the /usr/src tree.
|
|
Rather than use LDADD=-lname use LIBADD=name.
|
|
|
|
LDFLAGS Additional loader flags. Passed to the loader via CC,
|
|
since that's used to link programs as well, so loader
|
|
specific flags need to be prefixed with -Wl, to work.
|
|
|
|
LINKS The list of binary links; should be full pathnames, the
|
|
linked-to file coming first, followed by the linked
|
|
file. The files are hard-linked. For example, to link
|
|
/bin/test and /bin/[, use:
|
|
|
|
LINKS= ${DESTDIR}/bin/test ${DESTDIR}/bin/[
|
|
|
|
MAN Manual pages (should end in .1 - .9). If no MAN variable
|
|
is defined, "MAN=${PROG}.1" is assumed.
|
|
|
|
PROG The name of the program to build. If not supplied, nothing
|
|
is built.
|
|
|
|
PROG_CXX If defined, the name of the program to build. Also
|
|
causes <bsd.prog.mk> to link the program with the
|
|
standard C++ library. PROG_CXX overrides the value
|
|
of PROG if PROG is also set.
|
|
|
|
PROGS When used with <bsd.progs.mk>, allow building multiple
|
|
PROGS_CXX PROG and PROGS_CXX in one Makefile. To define
|
|
individual variables for each program the VAR.prog
|
|
syntax should be used. For example:
|
|
|
|
PROGS= foo bar
|
|
SRCS.foo= foo_src.c
|
|
LDADD.foo= -lutil
|
|
SRCS.bar= bar_src.c
|
|
|
|
The supported variables are BINDIR BINGRP BINMODE BINOWN
|
|
CFLAGS CPPFLAGS CXXFLAGS DPADD DPLIBS DPSRCS LDADD
|
|
LDFLAGS LIBADD MAN MLINKS PROGNAME SRCS.
|
|
|
|
PROGNAME The name that the above program will be installed as, if
|
|
different from ${PROG}.
|
|
|
|
SRCS List of source files to build the program. If SRCS is not
|
|
defined, it's assumed to be ${PROG}.c or, if PROG_CXX is
|
|
defined, ${PROG_CXX}.cc.
|
|
|
|
DPADD Additional dependencies for the program. Usually used for
|
|
libraries. For example, to depend on the compatibility and
|
|
utility libraries use:
|
|
|
|
DPADD=${LIBCOMPAT} ${LIBUTIL}
|
|
|
|
There is a predefined identifier for each (non-profiled,
|
|
non-shared) library and object. Library file names are
|
|
transformed to identifiers by removing the extension and
|
|
converting to upper case.
|
|
|
|
There are no special identifiers for profiled or shared
|
|
libraries or objects. The identifiers for the standard
|
|
libraries are used in DPADD. This works correctly iff all
|
|
the libraries are built at the same time. Unfortunately,
|
|
it causes unnecessary relinks to shared libraries when
|
|
only the static libraries have changed. Dependencies on
|
|
shared libraries should be only on the library version
|
|
numbers.
|
|
|
|
STRIP The flag passed to the install program to cause the binary
|
|
to be stripped. This is to be used when building your
|
|
own install script so that the entire system can be made
|
|
stripped/not-stripped using a single nob.
|
|
|
|
SUBDIR A list of subdirectories that should be built as well.
|
|
Each of the targets will execute the same target in the
|
|
subdirectories.
|
|
|
|
SCRIPTS A list of interpreter scripts [file.{sh,csh,pl,awk,...}].
|
|
The installation is controlled by the SCRIPTSNAME, SCRIPTSOWN,
|
|
SCRIPTSGRP, SCRIPTSMODE, SCRIPTSDIR variables that can be
|
|
further specialized by SCRIPTS<VAR>_<script>.
|
|
|
|
The include file <bsd.prog.mk> includes the file named "../Makefile.inc"
|
|
if it exists, as well as the include file <bsd.man.mk>.
|
|
|
|
Some simple examples:
|
|
|
|
To build foo from foo.c with a manual page foo.1, use:
|
|
|
|
PROG= foo
|
|
|
|
.include <bsd.prog.mk>
|
|
|
|
To build foo from foo.c with a manual page foo.2, add the line:
|
|
|
|
MAN= foo.2
|
|
|
|
If foo does not have a manual page at all, add the line:
|
|
|
|
MAN=
|
|
|
|
If foo has multiple source files, add the line:
|
|
|
|
SRCS= a.c b.c c.c d.c
|
|
|
|
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
|
|
|
|
The include file <bsd.subdir.mk> contains the default targets for building
|
|
subdirectories. It has the same seven targets as <bsd.prog.mk>: all, clean,
|
|
cleandir, depend, install, lint, and tags. For all of the directories
|
|
listed in the variable SUBDIRS, the specified directory will be visited
|
|
and the target made. There is also a default target which allows the
|
|
command "make subdir" where subdir is any directory listed in the variable
|
|
SUBDIRS.
|
|
|
|
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
|
|
|
|
The include file <bsd.lib.mk> has support for building libraries. It has
|
|
the same seven targets as <bsd.prog.mk>: all, clean, cleandir, depend,
|
|
install, lint, and tags. It has a limited number of suffixes, consistent
|
|
with the current needs of the BSD tree.
|
|
|
|
It sets/uses the following variables:
|
|
|
|
LIB The name of the library to build.
|
|
|
|
LIB_CXX The name of the library to build. It also causes
|
|
<bsd.lib.mk> to link the library with the
|
|
standard C++ library. LIB_CXX overrides the value
|
|
of LIB if LIB is also set.
|
|
|
|
LIBDIR Target directory for libraries.
|
|
|
|
LINTLIBDIR Target directory for lint libraries.
|
|
|
|
LIBGRP Library group.
|
|
|
|
LIBOWN Library owner.
|
|
|
|
LIBMODE Library mode.
|
|
|
|
LDADD Additional loader objects.
|
|
|
|
LIBADD Additional libraries. This is for base system libraries
|
|
and is only valid inside of the /usr/src tree.
|
|
Rather than use LDADD=-lname use LIBADD=name.
|
|
|
|
MAN The manual pages to be installed (use a .1 - .9 suffix).
|
|
|
|
SRCS List of source files to build the library. Suffix types
|
|
.s, .c, and .f are supported. Note, .s files are preferred
|
|
to .c files of the same name. (This is not the default for
|
|
versions of make.)
|
|
|
|
SHLIB_LDSCRIPT Template file to generate shared library linker script.
|
|
Unless used, a simple symlink is created to the real
|
|
shared object.
|
|
|
|
LIBRARIES_ONLY Do not build or install files other than the library.
|
|
|
|
The include file <bsd.lib.mk> includes the file named "../Makefile.inc"
|
|
if it exists, as well as the include file <bsd.man.mk>.
|
|
|
|
It has rules for building profiled objects; profiled libraries are
|
|
built by default.
|
|
|
|
Libraries are ranlib'd before installation.
|
|
|
|
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
|
|
|
|
The include file <bsd.test.mk> handles building one or more test programs
|
|
intended to be used in the FreeBSD Test Suite under /usr/tests/.
|
|
|
|
It has seven targets:
|
|
|
|
all:
|
|
build the test programs.
|
|
clean:
|
|
remove the test programs and any object files.
|
|
cleandir:
|
|
remove all of the files removed by the target clean, as
|
|
well as .depend and tags.
|
|
depend:
|
|
make the dependencies for the source files, and store
|
|
them in the file .depend.
|
|
install:
|
|
install the test programs and their data files; if the
|
|
Makefile does not itself define the target install, the
|
|
targets beforeinstall and afterinstall may also be used
|
|
to cause actions immediately before and after the
|
|
install target is executed.
|
|
lint:
|
|
run lint on the source files.
|
|
tags:
|
|
create a tags file for the source files.
|
|
test:
|
|
runs the test programs from the object directory; if the
|
|
Makefile does not itself define the target test, the
|
|
targets beforetest and aftertest may also be used to
|
|
cause actions immediately before and after the test
|
|
target is executed.
|
|
|
|
It sets/uses the following variables, among many others:
|
|
|
|
TESTSBASE Installation prefix for tests. Defaults to /usr/tests
|
|
|
|
TESTSDIR Path to the installed tests. Must be a subdirectory of
|
|
TESTSBASE and the subpath should match the relative
|
|
location of the tests within the src tree.
|
|
|
|
The value of TESTSDIR defaults to
|
|
${TESTSBASE}/${RELDIR:H} , e.g. /usr/tests/bin/ls when
|
|
included from bin/ls/tests .
|
|
|
|
KYUAFILE If 'auto' (the default), generate a Kyuafile out of the
|
|
test programs defined in the Makefile. If 'yes', then a
|
|
manually-crafted Kyuafile must be supplied with the
|
|
sources. If 'no', no Kyuafile is installed (useful for
|
|
subdirectories providing helper programs or data files
|
|
only).
|
|
|
|
ATF_TESTS_C The names of the ATF C test programs to build.
|
|
|
|
ATF_TESTS_CXX The names of the ATF C++ test programs to build.
|
|
|
|
ATF_TESTS_SH The names of the ATF sh test programs to build.
|
|
|
|
PLAIN_TESTS_C The names of the plain (legacy) programs to build.
|
|
|
|
PLAIN_TESTS_CXX The names of the plain (legacy) test programs to build.
|
|
|
|
PLAIN_TESTS_SH The names of the plain (legacy) test programs to build.
|
|
|
|
TAP_PERL_INTERPRETER
|
|
Path to the Perl interpreter to be used for
|
|
TAP-compliant test programs that are written in Perl.
|
|
Refer to TAP_TESTS_PERL for details.
|
|
|
|
TAP_TESTS_C The names of the TAP-compliant C test programs to build.
|
|
|
|
TAP_TESTS_CXX The names of the TAP-compliant C++ test programs to
|
|
build.
|
|
|
|
TAP_TESTS_PERL The names of the TAP-compliant Perl test programs to
|
|
build. The corresponding source files should end with
|
|
the .pl extension; the test program is marked as
|
|
requiring Perl; and TAP_PERL_INTERPRETER is used in the
|
|
built scripts as the interpreter of choice.
|
|
|
|
TAP_TESTS_SH The names of the TAP-compliant sh test programs to
|
|
build.
|
|
|
|
TESTS_SUBDIRS List of subdirectories containing tests into which to
|
|
recurse. Differs from SUBDIR in that these directories
|
|
get registered into the automatically-generated
|
|
Kyuafile (if any).
|
|
|
|
NOT_FOR_TEST_SUITE
|
|
If defined, none of the built test programs get
|
|
installed under /usr/tests/ and no Kyuafile is
|
|
automatically generated. Should not be used within the
|
|
FreeBSD source tree but is provided for the benefit of
|
|
third-parties.
|
|
|
|
The actual building of the test programs is performed by <bsd.prog.mk>.
|
|
Please see the documentation above for this other file for additional
|
|
details on the behavior of <bsd.test.mk>.
|