4 The term ``mk-files`` refers to a collection of ``*.mk`` files.
6 You need bmake_ or a *recent* NetBSD_ make.
7 If in doubt use bmake_.
12 Many years ago, when building large software projects, I used GNU make
13 (or my own patched version of it), and had developed a set of macros
14 to simplify developing complex build trees.
16 Since the early 90's my main development machines, run BSD
17 (NetBSD_ to be precise), and the BSD source tree is good example of a
18 large software project. It quickly became clear that
19 ``/usr/share/mk/*.mk`` were a great model, but were quite tightly
20 linked to building the BSD tree.
22 Much as I liked using NetBSD, my customers were more likely to be
23 using SunOS, HP-UX etc, so I started on bmake_ and a portable collection
24 of mk-files (mk.tar.gz_). NetBSD provided much of the original structure.
26 Since then I've added a lot of features to NetBSD's make and hence to
27 bmake which is kept closely in sync. The mk-files however have
28 diverged quite a bit, though ideas are still picked up from NetBSD
34 The BSD build model is very simple. A directory produces one
35 component, which is generally either a library or a program.
36 Library makefiles include ``lib.mk`` and programs include ``prog.mk``
37 and they *do the right thing*.
39 A simple library makefile might look like::
50 a simple program makefile::
58 in such cases even the ``SRCS`` line is unnecessary as ``prog.mk``
59 will default it to ``${PROG}.c``.
61 It is the sensible use of defaults and the plethora of macro modifiers
62 provided by bmake_ that allow simple makefiles such as the above
63 *just work* on many different systems.
69 This section provides a brief description of some of the ``*.mk``
75 When bmake starts, it looks for ``sys.mk`` and reads it before doing
76 anything else. Thus, this is the place to setup the environment for
79 In this distribution, sys.mk avoids doing anything platform dependent.
80 It is quite short, and includes a number of other files (which may or
84 If it exists, is expected to do things like conditioning the
85 environment. Since it will only be included by the initial
86 instance of bmake, it should ``.export`` anything that
89 examples/sys.clean-env.mk
90 An example of how to clean the environment.
91 See the file for all the details::
93 .if ${MAKE_VERSION} >= 20100606 && ${.MAKE.LEVEL} == 0
94 # we save any env var that starts with these
95 MAKE_SAVE_ENV_PREFIX += SB MK MAKE MACHINE NEED_ CCACHE DISTCC USE_ SSH
96 MAKE_SAVE_ENV_VARS += \
97 PATH HOME USER LOGNAME \
98 SRCTOP OBJTOP OBJROOT \
101 _env_vars != env | egrep '^(${MAKE_SAVE_ENV_PREFIX:ts|})' | sed 's,=.*,,'; echo
103 .for v in ${MAKE_SAVE_ENV_VARS:O:u}
109 # now clobber the environment
112 # list of vars that we handle specially below
113 _tricky_env_vars = MAKEOBJDIR
114 # export our selection - sans tricky ones
115 .export ${_export_list:${_tricky_env_vars:${M_ListToSkip}}}
117 # this next bit may need tweaking
118 .if defined(MAKEOBJDIR)
119 srctop := ${SRCTOP:U${SB_SRC:U${SB}/src}}
120 objroot := ${OBJROOT:U${SB_OBJROOT:U${SB}/${SB_OBJPREFIX}}}
121 # we'll take care of MACHINE below
122 objtop := ${OBJTOP:U${objroot}${MACHINE}}
124 # we would normally want something like (/bin/sh):
125 # MAKEOBJDIR="\${.CURDIR:S,${SRCTOP},${OBJROOT}\${MACHINE},}"
126 # the $$ below is how we achieve the same result here.
127 # since everything saved from the environment above
128 # has run through := we need to compensate for ${MACHINE}
129 MAKEOBJDIR = $${.CURDIR:S,${srctop},${objtop:S,${MACHINE},\${MACHINE},},}
131 # export these as-is, and do not track...
132 .export-env ${_tricky_env_vars}
133 # now evaluate for ourselves
134 .for v in ${_tricky_env_vars}
144 Is used to set macros like ``HOST_TARGET``, ``HOST_OS`` and
145 ``host_os`` which are used to find the next step.
148 Platform specific additions, such as ``Darwin.mk`` or ``SunOS.mk``
149 set things like ``HOST_LIBEXT = .dylib`` for Darwin or
150 ``SHLIB_FULLVERSION = ${SHLIB_MAJOR}`` for SunOS 5.
151 If there is no OS specific file, ``sys/Generic.mk`` is used.
154 Any ``local.*.mk`` file is not part of the distribution.
155 This provides a hook for sites to do extra setup without
156 having to edit the distributed files.
159 The above arrangement makes it easy for the mk files to be part of a
160 src tree on an NFS volume and to allow building on multiple platforms.
165 This file is used to build a number of different libraries from the
169 An archive lib of ``.o`` files, this is the default
172 A profiled lib of ``.po`` files.
173 Still an archive lib, but all the objects are built with
174 profiling in mind - hence the different extension.
175 It is skipped if ``MKPROFILE`` is "no".
178 An archive of ``.so`` objects compiled for relocation.
179 On NetBSD this is the input to ``lib${LIB}.${LD_so}``, it is
180 skipped if ``MKPICLIB`` is "no".
183 A shared library. The value of ``LD_so`` is very platform
184 specific. For example::
186 # SunOS 5 and most other ELF systems
192 This library will only be built if ``SHLIB_MAJOR`` has
193 a value, and ``MKPIC`` is not set to "no".
195 There is a lot of platform specific tweaking in ``lib.mk``, largely the
196 result of the original distributions trying to avoid interfering with
197 the system's ``sys.mk``.
202 This is included by both ``prog.mk`` and ``lib.mk`` and tries to
203 include ``*.libnames.mk`` of which:
206 does not exist unless you create it. It is a handy way for you
207 to customize without touching the distributed files.
208 For example, on a test machine I needed to build openssl but
209 not install it, so put the following in ``local.libnames.mk``::
211 .if ${host_os} == "sunos"
212 LIBCRYPTO = ${OBJTOP}/openssl/lib/crypto/libcrypto${DLIBEXT}
213 LIBSSL = ${OBJTOP}/openssl/lib/ssl/libssl${DLIBEXT}
214 INCLUDES_libcrypto = -I${OBJ_libcrypto}
217 The makefile created an openssl dir in ``${OBJ_libcrypto}`` to
218 gather all the headers. dpadd.mk_ did the rest.
221 not part of the mk-files distribution.
224 contains logic to find any libs named in ``HOST_LIBS`` in
227 Each file above gets an opportunity to define things like::
229 LIBSSLFD ?= ${OBJTOP}/ssl/lib/sslfd/libsslfd${DLIBEXT}
230 INCLUDES_libsslfd = -I${SRC_libsslfd}/h -I${OBJ_libslfd}
232 these are used by dpadd.mk_ and will be explained below.
237 This file looks like line noise, and is best considered read-only.
238 However it provides some very useful functionality, which simplifies the build.
240 Makefiles can use the LIB* macros defined via libnames.mk_ or anywhere
241 else in various ways::
243 # indicate that we need to include headers from LIBCRYPTO
244 # this would result in ${INCLUDES_libcrypto} being added to CFLAGS.
245 SRC_LIBS += ${LIBCRYPTO}
247 # indicate that libsslfd must be built already.
248 # it also has the same effect as SRC_LIBS
251 # indicate that not only must libsslfd be built,
252 # but that we need to link with it.
253 # this is almost exactly equivalent to
254 # DPADD += ${LIBSSLFD}
255 # LDADD += -L${LIBSSLFD:H} -lsslfd
256 # and mostly serves to ensure that DPADD and LDADD are in sync.
257 DPLIBS += ${LIBSSLFD}
259 Any library (referenced by its full path) in any of the above, is
260 added to ``DPMAGIC_LIBS`` with the following results, for each lib *foo*.
263 Is set to indicate where the src for libfoo is.
264 By default it is derived from ``LIBFOO`` by replacing
265 ``${OBJTOP}`` with ``${SRCTOP}``.
268 Not very exciting, is just the dir where libfoo lives.
271 What to add to ``CFLAGS`` to find the public headers.
272 The default varies. If ``${SRC_libfoo}/h`` exists, it is assumed
273 to be the home of all public headers and thus the default is
274 ``-I${SRC_libfoo}/h``
276 Otherwise we make no assumptions and the default is
277 ``-I${SRC_libfoo} -I${OBJ_libfoo}``
280 This only applies to libs reference via ``DPLIBS``.
281 The default is ``-lfoo``, ``LDADD_*`` provides a hook to
282 instantiate other linker flags at the appropriate point
283 without losing the benfits of ``DPLIBS``.
288 Compiles the specified SRCS and links them and the nominated libraries
289 into a program. Prog makefiles usually need to list the libraries
290 that need to be linked. We prefer use of ``DPLIBS`` but the more
291 traditional ``DPADD`` and ``LDADD`` work just as well.
294 DPLIBS += ${LIBCRYPTO}
298 DPADD += ${LIBCRYPTO}
304 One of the cool aspects of BSD make, is its support for separating
305 object files from the src tree. This is also the source of much
308 Traditionally one had to do a separate ``make obj`` pass through the
309 tree. If ``MKOBJDIRS`` is "auto", we include auto.obj.mk_.
314 This leverages the ``.OBJDIR`` target introduced some years ago to
315 NetBSD make, to automatically create the desired object dir.
320 This is the traditional means of walking the tree. A makefile sets
321 ``SUBDIR`` to the list of sub-dirs to visit.
323 If ``SUBDIR_MUST_EXIST`` is set, missing directories cause an error,
324 otherwise a warning is issued. If you don't even want the warning,
325 set ``MISSING_DIR=continue``.
327 Traditionally, ``subdir.mk`` prints clue as it visits each subdir::
333 you can suppress that - or enhance it by setting ``ECHO_DIR``::
335 # suppress subdir noise
338 ECHO_DIR=echo @ `date "+%s [%Y-%m-%d %T] "`
343 Provides rules for processing lists of ``LINKS`` and ``SYMLINKS``.
344 Each is expected to be a list of ``link`` and ``target`` pairs
345 (``link`` -> ``target``).
347 The logic is generally in a ``_*_SCRIPT`` which is referenced in a
348 ``_*_USE`` (``.USE``) target.
350 The ``_BUILD_*`` forms are identical, but do not use ``${DESTDIR}``
351 and so are useful for creating symlinks during the build phase.
354 SYMLINKS += ${.CURDIR}/${MACHINE_ARCH}/include machine
355 header_links: _BUILD_SYMLINKS_USE
359 would create a symlink called ``machine`` in ``${.OBJDIR}`` pointing to
360 ``${.CURDIR}/${MACHINE_ARCH}/include`` before compiling ``md.o``
366 Deals with running (or generating) GNU autoconf ``configure`` scripts.
371 Deals with collecting dependencies. Another useful feature of BSD
372 make is the separation of this sort of information into a ``.depend``
373 file. ``MKDEP`` needs to point to a suitable tool (like mkdeps.sh_)
375 If ``USE_AUTODEP_MK`` is "yes" includes autodep.mk_
380 Leverages the ``-MD`` feature of recent GCC to collect dependency
381 information as a side effect of compilation. With this GCC puts
382 dependency info into a ``.d`` file.
384 Unfortunately GCC bases the name of the ``.d`` file on the name of the
385 input rather than the output file, which causes problems when the same
386 source is compiled different ways. The latest GCC supports ``-MF`` to
387 name the ``.d`` file and ``-MT`` to control the name to put as the
390 Recent bmake allows dependencies for the ``.END`` target (run at the
391 end if everything was successful), and ``autodep.mk`` uses this to
392 post process the ``.d`` files into ``.depend``.
397 A much simpler implementation than autodep.mk_ it uses
398 ``-MF ${.TARGET:T}.d``
399 to avoid possible conflicts during parallel builds.
400 This precludes the use of suffix rules to drive ``make depend``, so
401 dep.mk_ handles that if specifically requested.
406 Inspired by FreeBSD's ``bsd.own.mk`` more flexible.
407 FreeBSD now have similar functionality in ``bsd.mkopt.mk``.
409 It allows users to express their intent with respect to options
410 ``MK_*`` by setting ``WITH_*`` or ``WITHOUT_*``.
412 Note: ``WITHOUT_*`` wins if both are set, and makefiles can set
413 ``NO_*`` to say they cannot handle that option, or even ``MK_*`` if
420 Normally included by ``init.mk`` (included by ``lib.mk`` and
421 ``prog.mk`` etc), sets macros for default ownership etc.
423 It includes ``${MAKECONF}`` if it is defined and exists.
428 Leverages ``bmake`` to compute optimal link order for libraries.
429 This works nicely and makes refactoring a breeze - so long as you
430 have not (or few) cicular dependencies between libraries.
435 Deals with man pages.
440 This provides a means of fine grained control over warnings on a per
441 ``${MACHINE}`` or even file basis.
443 A makefile sets ``WARNINGS_SET`` to name a list of warnings
444 and individual ``W_*`` macros can be used to tweak them.
448 W_unused_sparc = -Wno-unused
450 would add all the warnings in ``${HIGH_WARNINGS}`` to CFLAGS, but
451 on sparc, ``-Wno-unused`` would replace ``-Wunused``.
453 You should never need to edit ``warnings.mk``, it will include
454 ``warnings-sets.mk`` if it exists and you use that to make any local
460 Logic to simplify generating HTML (and PDF) documents from ReStructuredText.
465 Logic to build Python C interface modules using Cython_
467 .. _Cython: http://www.cython.org/
472 The 20110505 and later versions of ``mk-files`` include a number of
473 makefiles contributed by Juniper Networks, Inc.
474 These allow the latest version of bmake_ to run in `meta mode`_
477 .. _`dirdeps.mk`: /help/sjg/dirdeps.htm
478 .. _`meta mode`: bmake-meta-mode.htm
483 You can use the content of mk.tar.gz_ without installing at all.
485 The script ``install-mk`` takes care of copying ``*.mk`` into a
486 destination directory, and unless told not to, create ``bsd.*.mk`` links
489 If you just want to create the ``bsd.*.mk`` links in the directory
490 where you unpacked the tar file, you can::
497 .. _NetBSD: http://www.netbsd.org/
498 .. _mkdeps.sh: http://www.crufty.net/ftp/pub/sjg/mkdeps.sh
499 .. _mk.tar.gz: http://www.crufty.net/ftp/pub/sjg/mk.tar.gz
501 :Author: sjg@crufty.net
502 :Revision: $Id: mk-files.txt,v 1.18 2018/12/08 07:27:15 sjg Exp $
503 :Copyright: Crufty.NET