1 # @(#)bsd.README 8.2 (Berkeley) 4/2/94
2 # $FreeBSD: src/share/mk/bsd.README,v 1.15.2.6 2002/07/19 08:34:07 ru Exp $
3 # $DragonFly: src/share/mk/bsd.README,v 1.3 2004/07/31 19:29:24 asmodai Exp $
5 XXX This document is seriously out of date, it is currenly being revised.
7 This is the README file for the new make "include" files for the BSD
8 source tree. The files are installed in /usr/share/mk, and are, by
9 convention, named with the suffix ".mk".
15 bsd.dep.mk - handle Makefile dependencies
18 bsd.doc.mk - building troff system documents
22 bsd.info.mk - building GNU Info hypertext system
24 bsd.kmod.mk - building loadable kernel modules
25 bsd.lib.mk - support for building libraries
26 bsd.libnames.mk - define library names
28 bsd.man.mk - installing manual pages and their links
29 bsd.obj.mk - creating 'obj' directories and cleaning up
30 bsd.own.mk - define common variables
31 bsd.port.mk - building ports
34 bsd.port.subdir.mk - targets for building subdirectories for ports
35 bsd.prog.mk - building programs from source files
36 bsd.subdir.mk - targets for building subdirectories
41 Note, this file is not intended to replace reading through the .mk
42 files for anything tricky.
44 See also make(1), mkdep(1) and `PMake - A Tutorial',
45 located in /usr/share/doc/psd/12.make.
47 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
49 RANDOM THINGS WORTH KNOWING:
51 The files are simply C-style #include files, and pretty much behave like
52 you'd expect. The syntax is slightly different in that a single '.' is
53 used instead of the hash mark, i.e. ".include <bsd.prog.mk>".
55 One difference that will save you lots of debugging time is that inclusion
56 of the file is normally done at the *end* of the Makefile. The reason for
57 this is because .mk files often modify variables and behavior based on the
58 values of variables set in the Makefile. To make this work, remember that
59 the FIRST target found is the target that is used, i.e. if the Makefile has:
66 the command "make a" will echo "a". To make things confusing, the SECOND
67 variable assignment is the overriding one, i.e. if the Makefile has:
75 the command "make b" will echo "bar". This is for compatibility with the
76 way the V7 make behaved.
78 It's fairly difficult to make the BSD .mk files work when you're building
79 multiple programs in a single directory. It's a lot easier split up the
80 programs than to deal with the problem. Most of the agony comes from making
81 the "obj" directory stuff work right, not because we switch to a new version
82 of make. So, don't get mad at us, figure out a better way to handle multiple
83 architectures so we can quit using the symbolic link stuff. (Imake doesn't
86 The file .depend in the source directory is expected to contain dependencies
87 for the source files. This file is read automatically by make after reading
90 The variable DESTDIR works as before. It's not set anywhere but will change
91 the tree where the file gets installed.
93 The profiled libraries are no longer built in a different directory than
94 the regular libraries. A new suffix, ".po", is used to denote a profiled
97 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
99 The include file <sys.mk> has the default rules for all makes, in the BSD
100 environment or otherwise. You probably don't want to touch this file.
102 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
104 The include file <bsd.man.mk> handles installing manual pages and their
107 It has three targets:
112 install the manual pages and their links.
114 verify the validity of manual pages.
116 It sets/uses the following variables:
118 MANDIR Base path for manual installation.
126 MANSUBDIR Subdirectory under the manual page section, i.e. "/vax"
127 or "/tahoe" for machine specific manual pages.
129 MAN The manual pages to be installed (use a .1 - .9 suffix).
131 MLINKS List of manual page links (using a .1 - .9 suffix). The
132 linked-to file must come first, the linked file second,
133 and there may be multiple pairs. The files are soft-linked.
135 The include file <bsd.man.mk> includes a file named "../Makefile.inc" if
138 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
140 The include file <bsd.own.mk> contains the owners, groups, etc. for both
141 manual pages and binaries.
145 It sets/uses the following variables:
153 STRIP The flag passed to the install program to cause the binary
154 to be stripped. This is to be used when building your
155 own install script so that the entire system can be made
156 stripped/not-stripped using a single nob.
158 MANDIR Base path for manual installation.
166 This file is generally useful when building your own Makefiles so that
167 they use the same default owners etc. as the rest of the tree.
169 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
171 The include file <bsd.prog.mk> handles building programs from one or
172 more source files, along with their manual pages. It has a limited number
173 of suffixes, consistent with the current needs of the BSD tree.
175 It has seven targets:
178 build the program and its manual page
180 remove the program, any object files and the files a.out,
181 Errs, errs, mklog, and ${PROG}.core.
183 remove all of the files removed by the target clean, as
184 well as .depend, tags, and any manual pages.
186 make the dependencies for the source files, and store
187 them in the file .depend.
189 install the program and its manual pages; if the Makefile
190 does not itself define the target install, the targets
191 beforeinstall and afterinstall may also be used to cause
192 actions immediately before and after the install target
195 run lint on the source files
197 create a tags file for the source files.
199 It sets/uses the following variables:
207 CLEANFILES Additional files to remove and
208 CLEANDIRS additional directories to remove during clean and cleandir
209 targets. "rm -f" and "rm -rf" used respectively.
211 COPTS Additional flags to the compiler when creating C objects.
213 FILES A list of non-executable files.
214 The installation is controlled by the FILESNAME, FILESOWN,
215 FILESGRP, FILESMODE, FILESDIR variables that can be
216 further specialized by FILES<VAR>_<file>.
218 HIDEGAME If HIDEGAME is defined, the binary is installed in
219 /usr/games/hide, and a symbolic link is created to
222 LDADD Additional loader objects. Usually used for libraries.
223 For example, to load with the compatibility and utility
226 LDFILES=-lutil -lcompat
228 LDFLAGS Additional loader flags.
230 LINKS The list of binary links; should be full pathnames, the
231 linked-to file coming first, followed by the linked
232 file. The files are hard-linked. For example, to link
233 /bin/test and /bin/[, use:
235 LINKS= ${DESTDIR}/bin/test ${DESTDIR}/bin/[
237 MAN Manual pages (should end in .1 - .9). If no MAN variable
238 is defined, "MAN=${PROG}.1" is assumed.
240 PROG The name of the program to build. If not supplied, nothing
243 PROG_CXX If defined, the name of the program to build. Also
244 causes <bsd.prog.mk> to link the program with the
245 standard C++ library. PROG_CXX overrides the value
246 of PROG if PROG is also set.
248 PROGNAME The name that the above program will be installed as, if
249 different from ${PROG}.
251 SRCS List of source files to build the program. If SRCS is not
252 defined, it's assumed to be ${PROG}.c or, if PROG_CXX is
253 defined, ${PROG_CXX}.cc.
255 DPADD Additional dependencies for the program. Usually used for
256 libraries. For example, to depend on the compatibility and
257 utility libraries use:
259 SRCLIB=${LIBCOMPAT} ${LIBUTIL}
261 There is a predefined identifier for each (non-profiled,
262 non-shared) library and object. Library file names are
263 transformed to identifiers by removing the extension and
264 converting to upper case.
266 There are no special identifiers for profiled or shared
267 libraries or objects. The identifiers for the standard
268 libraries are used in DPADD. This works correctly iff all
269 the libraries are built at the same time. Unfortunately,
270 it causes unnecessary relinks to shared libraries when
271 only the static libraries have changed. Dependencies on
272 shared libraries should be only on the library version
275 STRIP The flag passed to the install program to cause the binary
278 SUBDIR A list of subdirectories that should be built as well.
279 Each of the targets will execute the same target in the
282 SCRIPTS A list of interpreter scripts [file.{sh,csh,pl,awk,...}].
283 The installation is controlled by the SCRIPTSNAME, SCRIPTSOWN,
284 SCRIPTSGRP, SCRIPTSMODE, SCRIPTSDIR variables that can be
285 further specialized by SCRIPTS<VAR>_<script>.
287 The include file <bsd.prog.mk> includes the file named "../Makefile.inc"
288 if it exists, as well as the include file <bsd.man.mk>.
290 Some simple examples:
292 To build foo from foo.c with a manual page foo.1, use:
296 .include <bsd.prog.mk>
298 To build foo from foo.c with a manual page foo.2, add the line:
302 If foo does not have a manual page at all, add the line:
306 If foo has multiple source files, add the line:
308 SRCS= a.c b.c c.c d.c
310 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
312 The include file <bsd.subdir.mk> contains the default targets for building
313 subdirectories. It has the same seven targets as <bsd.prog.mk>: all, clean,
314 cleandir, depend, install, lint, and tags. For all of the directories
315 listed in the variable SUBDIRS, the specified directory will be visited
316 and the target made. There is also a default target which allows the
317 command "make subdir" where subdir is any directory listed in the variable
320 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
322 The include file <bsd.lib.mk> has support for building libraries. It has
323 the same seven targets as <bsd.prog.mk>: all, clean, cleandir, depend,
324 install, lint, and tags. It has a limited number of suffixes, consistent
325 with the current needs of the BSD tree.
327 It sets/uses the following variables:
329 LIBDIR Target directory for libraries.
331 LINTLIBDIR Target directory for lint libraries.
333 LIBGRP Library group.
335 LIBOWN Library owner.
337 LIBMODE Library mode.
339 LDADD Additional loader objects.
341 MAN The manual pages to be installed (use a .1 - .9 suffix).
343 SRCS List of source files to build the library. Suffix types
344 .s, .c, and .f are supported. Note, .s files are preferred
345 to .c files of the same name. (This is not the default for
348 The include file <bsd.lib.mk> includes the file named "../Makefile.inc"
349 if it exists, as well as the include file <bsd.man.mk>.
351 It has rules for building profiled objects; profiled libraries are
354 Libraries are ranlib'd before installation.