1# $OpenBSD: bsd.README,v 1.86 2023/07/25 20:19:14 asou Exp $
2# $NetBSD: bsd.README,v 1.17 1996/04/13 02:08:08 thorpej Exp $
3# @(#)bsd.README 5.1 (Berkeley) 5/11/90
4
5This is the README file for the make "include" files for the BSD
6source tree. The files are installed in /usr/share/mk, and are, by
7convention, named with the suffix ".mk".
8
9bsd.dep.mk - handle Makefile dependencies
10bsd.lib.mk - support for building libraries
11bsd.man.mk - installing manual pages and their links
12bsd.obj.mk - creating 'obj' directories and cleaning up
13bsd.own.mk - define common variables
14bsd.port.mk - building ports (see bsd.port.mk(5))
15bsd.port.arch.mk - glue for building ports with MD stuff
16bsd.port.subdir.mk - targets for building subdirectories for ports
17bsd.prog.mk - building programs from source files
18bsd.regress.mk - regression tests (see bsd.regress.mk(5))
19bsd.subdir.mk - targets for building subdirectories
20bsd.sys.mk - overrides for <sys.mk> for building OpenBSD
21sys.mk - global default rules, mostly POSIX
22
23Note, this file is not intended to replace reading through the .mk
24files for anything tricky.
25
26=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
27
28RANDOM THINGS WORTH KNOWING:
29
30The files are simply C-style #include files, and pretty much behave like
31you'd expect. The syntax is slightly different in that a single '.' is
32used instead of the hash mark, i.e. ".include <bsd.prog.mk>".
33
34One difference that will save you lots of debugging time is that inclusion
35of the file is normally done at the *end* of the Makefile. The reason for
36this is because .mk files often modify variables and behavior based on the
37values of variables set in the Makefile. To make this work, remember that
38the FIRST target found is the target that is used, i.e. if the Makefile has:
39
40 a:
41 echo a
42 a:
43 echo a number two
44
45the command "make a" will echo "a". To make things confusing, the SECOND
46variable assignment is the overriding one, i.e. if the Makefile has:
47
48 a= foo
49 a= bar
50
51 b:
52 echo ${a}
53
54the command "make b" will echo "bar". This is for compatibility with the
55way the V7 make behaved.
56
57To make things even more confusing, make uses lazy evaluation. All
58variables are expanded only when needed. Which means that, in
59
60 a= foo
61
62 b: $(a)
63 echo $(.ALLSRC)
64 echo $(a)
65
66 foo:
67 touch foo
68
69 a= bar
70
71the command "make b" will echo "foo"; echo "bar". The first $(a) means
72"foo", because it's needed to generate the dependency rule when it's read,
73but the second $(a) is only expanded when needed, at which point a contains
74bar.
75
76It's fairly difficult to make the BSD .mk files work when you're building
77multiple programs in a single directory. It's a lot easier to split up the
78programs than to deal with the problem. Most of the agony comes from making
79the "obj" directory stuff work right, not because we switched to a new version
80of make. So, don't get mad at us, figure out a better way to handle multiple
81architectures so we can quit using the symbolic link stuff. (Imake doesn't
82count.)
83
84Dependencies are handled using the compiler's -M* options, resulting in
85lots of .d files. These are manually included through <bsd.dep.mk>.
86
87<bsd.dep.mk> also provides an empty depend target to <bsd.prog.mk> and
88<bsd.lib.mk>, for backward compatibility.
89
90The variable DESTDIR works as before. It's not set anywhere but will change
91the tree where the file gets installed.
92
93The profiled libraries are no longer built in a different directory than
94the regular libraries. A new suffix, ".po", is used to denote a profiled
95object.
96
97=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
98
99The include file <sys.mk> has the default rules for all makes, in the BSD
100environment or otherwise. You probably don't want to touch this file.
101
102=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
103
104The include file <bsd.sys.mk> is used by <bsd.prog.mk> and
105<bsd.lib.mk>. It overrides parts of <sys.mk> for building the
106OpenBSD source tree. For example, it contains a better yacc(1)
107rule assigning the proper names to all output files.
108
109=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
110
111The include file <bsd.man.mk> handles installing manual pages and their
112links.
113
114It has a single target:
115
116 maninstall:
117 Install the manual pages and their links.
118
119It sets/uses the following variables:
120
121MANDIR Base path for manual installation.
122
123MANGRP Manual group.
124
125MANOWN Manual owner.
126
127MANMODE Manual mode.
128
129MANSUBDIR Subdirectory under the manual page section, i.e. "amd64"
130 or "sparc64" for machine specific manual pages.
131
132MAN The manual pages to be installed (use a .1 - .9 suffix).
133
134MLINKS List of manual page links (using a .1 - .9 suffix). The
135 linked-to file must come first, the linked file second,
136 and there may be multiple pairs. The files are soft-linked.
137
138BEFOREMAN List of extra targets that must be already built before the
139 man target can be run. Those targets must be real files (and
140 not .PHONY targets).
141
142The include file <bsd.man.mk> includes a file named "../Makefile.inc" if
143it exists.
144
145=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
146
147The include file <bsd.own.mk> contains source tree configuration parameters,
148such as the owners, groups, etc. for both manual pages and binaries, and
149a few global "feature configuration" parameters.
150
151It has no targets.
152
153To get system-specific configuration parameters, bsd.own.mk will try to
154include the file specified by the "MAKECONF" variable. If MAKECONF is not
155set, or no such file exists, the system make configuration file, /etc/mk.conf
156is included. These files may define any of the variables described below.
157
158bsd.own.mk sets the following variables, if they are not already defined
159(defaults are in brackets):
160
161BSDSRCDIR The real path to the system sources, so that 'make obj'
162 will work correctly. [/usr/src]
163
164BSDOBJDIR The real path to the system 'obj' tree, so that 'make obj'
165 will work correctly. [/usr/obj]
166
167BINGRP Binary group. [bin]
168
169BINOWN Binary owner. [root]
170
171BINMODE Binary mode. [555]
172
173NONBINMODE Mode for non-executable files. [444]
174
175DIRMODE Mode for new directories. [755]
176
177MANDIR Base path for manual installation. [/usr/share/man/man]
178
179MANGRP Manual group. [bin]
180
181MANOWN Manual owner. [root]
182
183MANMODE Manual mode. [${NONBINMODE}]
184
185LIBDIR Base path for library installation. [/usr/lib]
186
187LIBGRP Library group. [${BINGRP}]
188
189LIBOWN Library owner. [${BINOWN}]
190
191LIBMODE Library mode. [${NONBINMODE}]
192
193DOCDIR Base path for system documentation
194 installation. [/usr/share/doc]
195
196DOCGRP Documentation group. [bin]
197
198DOCOWN Documentation owner. [root]
199
200DOCMODE Documentation mode. [${NONBINMODE}]
201
202INSTALL_STRIP The flag passed to the install program to cause the binary
203 to be stripped. This is to be used when building your
204 own install script so that the entire system can be made
205 stripped/not-stripped using a single knob. Note that
206 INSTALL_STRIP is not set if ${DEBUG} is defined. [-s]
207
208INSTALL_COPY The old usage of this flag is obsolescent since install(1)
209 now copies by default. However, it can also be used to
210 specify that a file not be copied unless it is different
211 (via the -p option). See install(1) for details. This
212 is to be used when building our own install script so
213 that the entire system can either be installed with copies,
214 or copy-if-different using a single knob. [-c]
215
216Additionally, the following variables may be set by bsd.own.mk or in a
217make configuration file to modify the behaviour of the system build
218process (default values are in brackets along with comments, if set by
219bsd.own.mk):
220
221SKEY Compile in support for S/key authentication. [yes, set
222 unconditionally]
223
224SYS_INCLUDE Copy or symlink kernel include files into /usr/include.
225 Possible values are "symlinks" or "copies" (which is
226 the same as the variable being unset).
227
228NOPROFILE Do not build profiled versions of system libraries.
229
230NOPIC Do not build PIC versions of system libraries, and
231 do not build shared libraries.
232
233NOPIE Do not build PIE objects or executables.
234
235DEBUG Add -g to assembly, C compiler and linking passes. Also
236 doesn't set STRIP to -s per default if defined.
237
238WARNINGS Adds appropriate warning flags (defined in CDIAGFLAGS,
239 e.g., -Wall...) to compiles. [no]
240
241SUDO Command to run when doing "make install" portion of
242 "make build". If set to /usr/bin/doas, this allows one
243 to run "make build" as a user other than root (assuming
244 doas is setup for that user).
245
246PIPE If set to "-pipe" gcc will be given the -pipe option
247 which can speed up compiles on machines with memory
248 to spare. Instead of using temp files, gcc uses pipes
249 for the temporary data.
250
251GLOBAL_AUTOCONF_CACHE
252 Set to the name of a file that all cached GNU autoconf
253 test results will be saved in. Reduces redundant tests.
254 Be careful! Redundant tests may not be redundant if you
255 are installing substantially updated gnu programs.
256
257bsd.own.mk is generally useful when building your own Makefiles so that
258they use the same default owners etc. as the rest of the tree.
259
260=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
261
262The include file <bsd.prog.mk> handles building programs from one or
263more source files, along with their manual pages. It has a limited number
264of suffixes, consistent with the current needs of the BSD tree.
265
266It has six targets:
267
268 all:
269 build the program and its manual page
270 clean:
271 remove the program, any object files, and some other
272 files that are automatically generated.
273 cleandir:
274 remove all of the files removed by the target clean, as
275 well as the tags file.
276 includes:
277 install any header files.
278 install:
279 install the program and its manual pages; if the Makefile
280 does not itself define the target install, the targets
281 beforeinstall and afterinstall may also be used to cause
282 actions immediately before and after the install target
283 is executed.
284 tags:
285 create a tags file for the source files.
286
287It uses the following variables:
288
289BINGRP Binary group.
290
291BINOWN Binary owner.
292
293BINMODE Binary mode.
294
295BUILDFIRST Stuff that needs to be built before anything else, in
296 terms of dependencies.
297
298BUILDAFTER Stuff that comes later (usually don't touch, defined correctly
299 by <bsd.prog.mk> and <bsd.lib.mk>)
300
301CLEANFILES Additional files to remove for the clean and cleandir targets.
302
303COPTS Additional flags to the compiler when creating C objects.
304
305CXXOPTS Additional flags to the compiler when creating C++ objects.
306
307LDADD Additional linker objects. Usually used for libraries.
308 For example, to link with the crypto and utility
309 libraries, use:
310
311 LDADD+=-lutil -lcrypto
312
313LDFLAGS Additional linker flags.
314
315LINKS The list of binary links; should be full pathnames, the
316 linked-to file coming first, followed by the linked
317 file. The files are hard-linked. For example, to link
318 /bin/test and /bin/[, use:
319
320 LINKS= ${DESTDIR}/bin/test ${DESTDIR}/bin/[
321
322MAN Manual pages (should end in .1 - .9). If no MAN variable is
323 defined, "MAN=${PROG}.1" is assumed.
324
325PROG The name of the program to build. If not supplied, nothing
326 is built.
327
328SRCS List of source files to build the program. If it's not
329 defined, it's assumed to be ${PROG}.c.
330
331DPADD Additional dependencies for the program. Usually used for
332 libraries. For example, to depend on the crypto and
333 utility libraries use:
334
335 DPADD+=${LIBCRYPTO} ${LIBUTIL}
336
337 The following libraries are predefined for DPADD:
338
339 LIBC /usr/lib/libc.a
340 LIBCBOR /usr/lib/libcbor.a
341 LIBCRYPTO /usr/lib/libcrypto.a
342 LIBCURSES /usr/lib/libcurses.a
343 LIBEDIT /usr/lib/libedit.a
344 LIBELF /usr/lib/libelf.a
345 LIBEVENT /usr/lib/libevent.a
346 LIBEXPAT /usr/lib/libexpat.a
347 LIBFIDO2 /usr/lib/libfido2.a
348 LIBFORM /usr/lib/libform.a
349 LIBFORMW /usr/lib/libformw.a
350 LIBKEYNOTE /usr/lib/libkeynote.a
351 LIBKVM /usr/lib/libkvm.a
352 LIBL /usr/lib/libl.a
353 LIBM /usr/lib/libm.a
354 LIBMENU /usr/lib/libmenu.a
355 LIBMENUW /usr/lib/libmenuw.a
356 LIBRADIUS /usr/lib/libradius.a
357 LIBOSSAUDIO /usr/lib/libossaudio.a
358 LIBPANEL /usr/lib/libpanel.a
359 LIBPANELW /usr/lib/libpanelw.a
360 LIBPCAP /usr/lib/libpcap.a
361 LIBPERL /usr/lib/libperl.a
362 LIBPTHREAD /usr/lib/libpthread.a
363 LIBRPCSVC /usr/lib/librpcsvc.a
364 LIBSKEY /usr/lib/libskey.a
365 LIBSNDIO /usr/lib/libsndio.a
366 LIBSSL /usr/lib/libssl.a
367 LIBAGENTX /usr/lib/libagentx.a
368 LIBTERMCAP /usr/lib/libtermcap.a
369 LIBTERMLIB /usr/lib/libtermlib.a
370 LIBTLS /usr/lib/libtls.a
371 LIBUSBHID /usr/lib/libusbhid.a
372 LIBUTIL /usr/lib/libutil.a
373 LIBY /usr/lib/liby.a
374 LIBZ /usr/lib/libz.a
375 LIBARCH arch-dependent stuff
376
377STRIP The flag passed to the install program to cause the binary
378 to be stripped.
379
380SUBDIR A list of subdirectories that should be built as well.
381 Each of the targets will execute the same target in the
382 subdirectories.
383
384The include file <bsd.prog.mk> includes the file named "../Makefile.inc"
385if it exists, as well as the include file <bsd.man.mk>.
386
387Some simple examples:
388
389To build foo from foo.c with a manual page foo.1, use:
390
391 PROG= foo
392
393 .include <bsd.prog.mk>
394
395To build foo from foo.c with a manual page foo.2, add the line:
396
397 MAN= foo.2
398
399If foo does not have a manual page at all, add the line:
400
401 NOMAN= noman
402
403If foo has multiple source files, add the line:
404
405 SRCS= a.c b.c c.c d.c
406
407SRCS may contain lex and yacc files, in which case the framework will
408convert these files to C and header files first, before building anything
409else.
410
411SRCS may contain C++ files, in which case the C++ compiler will be used
412for linking.
413
414If YFLAGS contains -d, the header file will be named like the C file,
415and a proper rule tying both together will be generated. For instance, if
416SRCS contains grammar.y, then effectively you will have
417
418grammar.c grammar.h: grammar.y
419 ${YACC.Y} -o grammar.c grammar.y
420
421
422<bsd.prog.mk> provides a limited capability to build several
423programs in a single directory by defining the list of programs
424as PROGS instead of using PROG, for instance: PROGS = foo bar
425
426This only works if all programs in the directory use the same
427compiler and linker flags. Also, the programs cannot use source
428files with the same file name but different content.
429
430Each program of the list, for instance foo, will use SRCS_foo instead
431of SRCS to find its sources. SRCS_foo still defaults to foo.c, and
432MAN still defaults to section 1 manpages: MAN = foo.1 bar.1.
433
434Each program can have its separate LDADD_foo and DPADD_foo definitions.
435If not defined, these default to LDADD/DPADD.
436
437Some simple examples:
438To build foo from foo.c and bar from bar.c with manual pages foo.1 and bar.1:
439
440 PROGS = foo bar
441
442 .include <bsd.prog.mk>
443
444If bar has manual page bar.8 instead, add the line:
445 MAN = foo.1 bar.8
446
447If bar has multiple source files, add the line:
448 SRCS_bar = a.c b.c c.c d.c
449
450Note that foo and bar may share some source files, like so:
451 SRCS_foo = foo.c common.c
452 SRCS_bar = bar.c common.c
453
454=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
455
456The include file <bsd.subdir.mk> contains the default targets for building
457subdirectories. It has the same six targets as <bsd.prog.mk>: all,
458clean, cleandir, includes, install, and tags. For all of
459the directories listed in the variable SUBDIR, the specified directory
460will be visited and the target made. There is also a default target which
461allows the command "make subdir" where subdir is any directory listed in
462the variable SUBDIR.
463
464
465=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
466
467The include file <bsd.lib.mk> has support for building libraries. It has
468the same six targets as <bsd.prog.mk>: all, clean, cleandir,
469includes, install, and tags. It has a limited number of suffixes,
470consistent with the current needs of the BSD tree.
471
472It uses the following variables:
473
474BUILDFIRST/BUILDAFTER
475 See <bsd.prog.mk>.
476
477LIB The name of the library to build.
478
479LIBDIR Target directory for libraries.
480
481LIBGRP Library group.
482
483LIBOWN Library owner.
484
485LIBMODE Library mode.
486
487LDADD Additional linker objects.
488
489MAN The manual pages to be installed (use a .1 - .9 suffix).
490
491SRCS List of source files to build the library. Suffix types
492 .s, .c, and .f are supported. Note, .s files are preferred
493 to .c files of the same name. (This is not the default for
494 POSIX make without bsd.lib.mk).
495
496 The same support for yacc and lex files as <bsd.prog.mk>
497 is provided.
498
499The include file <bsd.lib.mk> includes the file named "../Makefile.inc"
500if it exists, as well as the include file <bsd.man.mk>.
501
502It has rules for building profiled objects; profiled libraries are
503built by default.
504
505Static libraries are ranlib'd when made.
506
507In addition, a reduced version of a library, including just specific
508objects that are compiled with additional options to reduce their
509size may be built. This is used by the distrib/ tree and crunchgen
510when building ramdisks. This sets/uses the following variables:
511
512DIST_LIB The path of the library to build. [lib${LIB}_d.a]
513
514DIST_OBJS The (sub)set of .o files to include in ${DIST_LIB}. [${OBJS}]
515
516DIST_CFLAGS Additional flags for the C compiler and assembler.
517 [-Oz]
518
519