472 lines
16 KiB
Plaintext
472 lines
16 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.cpu.mk - sets CPU/arch-related variables
|
|
bsd.dep.mk - handle Makefile dependencies
|
|
bsd.doc.mk - building troff system documents
|
|
bsd.files.mk - install of general purpose files
|
|
bsd.incs.mk - install of include files
|
|
bsd.info.mk - building GNU Info hypertext system
|
|
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.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 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.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
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
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:
|
|
|
|
TESTDIR 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.
|
|
|
|
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>.
|