build - Remove openssl from base (is now permanently replaced by ressl)
[dragonfly.git] / contrib / bmake / mk / mk-files.txt
blobb0a7e94dcb79155e241cdf2967c5f3058f7ec437
1 mk-files
2 ********
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_.
9 Introduction
10 ============
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.
30 Basics
31 ------
33 The BSD build model is very simple.  A directory produces one
34 component, which is generally either a library or a program.
35 Library makefiles include ``lib.mk`` and programs include ``prog.mk``
36 and they *do the right thing*.
38 A simple library makefile might look like::
40         LIB = sig
42         SRCS = \
43                 sigaction.c \
44                 sigcompat.c \
45                 sighdl.c
47         .include <lib.mk>
49 a simple program makefile::
51         PROG = cat
53         SRCS = cat.c
55         .include <prog.mk>
57 in such cases even the ``SRCS`` line is unnecessary as ``prog.mk``
58 will default it to ``${PROG}.c``.
60 It is the sensible use of defaults and the plethora of macro modifiers
61 provided by bmake_ that allow simple makefiles such as the above
62 *just work* on many different systems.
65 mk-files
66 ========
68 This section provides a brief description of some of the ``*.mk``
69 files. 
71 sys.mk
72 ------
74 When bmake starts, it looks for ``sys.mk`` and reads it before doing
75 anything else.  Thus, this is the place to setup the environment for
76 everyone else.
78 In this distribution, sys.mk avoids doing anything platform dependent.
79 It is quite short, and includes a number of other files (which may or
80 may not exists)
82 sys.env.mk
83         If it exists, is expected to do things like conditioning the
84         environment.  Since it will only be included by the initial
85         instance of bmake, it should ``.export`` anything that
86         sub-makes might need.
88 examples/sys.clean-env.mk
89         An example of how to clean the environment.
90         See the file for all the details::
92                 .if ${MAKE_VERSION} >= 20100606 && ${.MAKE.LEVEL} == 0
93                 # we save any env var that starts with these
94                 MAKE_SAVE_ENV_PREFIX += SB MK MAKE MACHINE NEED_ CCACHE DISTCC USE_ SSH
95                 MAKE_SAVE_ENV_VARS += \
96                         PATH HOME USER LOGNAME \
97                         SRCTOP OBJTOP OBJROOT \
98                         ${_env_vars}
99                 
100                 _env_vars != env | egrep '^(${MAKE_SAVE_ENV_PREFIX:ts|})' | sed 's,=.*,,'; echo
101                 _export_list =
102                 .for v in ${MAKE_SAVE_ENV_VARS:O:u}
103                 .if !empty($v)
104                 _export_list += $v
105                 $v := ${$v}
106                 .endif
107                 .endfor
108                 # now clobber the environment
109                 .unexport-env
111                 # list of vars that we handle specially below
112                 _tricky_env_vars = MAKEOBJDIR
113                 # export our selection - sans tricky ones
114                 .export ${_export_list:${_tricky_env_vars:${M_ListToSkip}}}
116                 # this next bit may need tweaking
117                 .if defined(MAKEOBJDIR)
118                 srctop := ${SRCTOP:U${SB_SRC:U${SB}/src}}
119                 objroot := ${OBJROOT:U${SB_OBJROOT:U${SB}/${SB_OBJPREFIX}}}
120                 # we'll take care of MACHINE below
121                 objtop := ${OBJTOP:U${objroot}${MACHINE}}
122                 .if !empty(objtop)
123                 # we would normally want something like (/bin/sh):
124                 # MAKEOBJDIR="\${.CURDIR:S,${SRCTOP},${OBJROOT}\${MACHINE},}"
125                 # the $$ below is how we achieve the same result here.
126                 # since everything saved from the environment above
127                 # has run through := we need to compensate for ${MACHINE}
128                 MAKEOBJDIR = $${.CURDIR:S,${srctop},${objtop:S,${MACHINE},\${MACHINE},},}
130                 # export these as-is, and do not track...
131                 .export-env ${_tricky_env_vars}
132                 # now evaluate for ourselves
133                 .for v in ${_tricky_env_vars}
134                 $v := ${$v}
135                 .endfor
137                 .endif
138                 .endif
139                 .endif
142 host-target.mk
143         Is used to set macros like ``HOST_TARGET``, ``HOST_OS`` and
144         ``host_os`` which are used to find the next step.
146 sys/\*.mk
147         Platform specific additions, such as ``Darwin.mk`` or ``SunOS.mk``
148         set things like ``HOST_LIBEXT = .dylib`` for Darwin or
149         ``SHLIB_FULLVERSION = ${SHLIB_MAJOR}`` for SunOS 5.
150         If there is no OS specific file, ``sys/Generic.mk`` is used.
152 local.sys.mk
153         Any ``local.*.mk`` file is not part of the distribution.
154         This provides a hook for sites to do extra setup without
155         having to edit the distributed files.
158 The above arrangement makes it easy for the mk files to be part of a
159 src tree on an NFS volume and to allow building on multiple platforms.
161 lib.mk
162 ------
164 This file is used to build a number of different libraries from the
165 same SRCS.
167 lib${LIB}.a
168         An archive lib of ``.o`` files, this is the default
170 lib${LIB}_p.a
171         A profiled lib of ``.po`` files.  
172         Still an archive lib, but all the objects are built with
173         profiling in mind - hence the different extension.
174         It is skipped if ``MKPROFILE`` is "no".
176 lib${LIB}_pic.a
177         An archive of ``.so`` objects compiled for relocation.
178         On NetBSD this is the input to ``lib${LIB}.${LD_so}``, it is
179         skipped if ``MKPICLIB`` is "no".
181 lib${LIB}.${LD_so}
182         A shared library.  The value of ``LD_so`` is very platform
183         specific.  For example::
185                 # SunOS 5 and most other ELF systems
186                 libsslfd.so.1
188                 # Darwin
189                 libsslfd.1.dylib
191         This library will only be built if ``SHLIB_MAJOR`` has
192         a value, and ``MKPIC`` is not set to "no".
194 There is a lot of platform specific tweaking in ``lib.mk``, largely the
195 result of the original distributions trying to avoid interfering with
196 the system's ``sys.mk``. 
198 libnames.mk
199 -----------
201 This is included by both ``prog.mk`` and ``lib.mk`` and tries to
202 include ``*.libnames.mk`` of which:
204 local.libnames.mk
205         does not exist unless you create it.  It is a handy way for you
206         to customize without touching the distributed files. 
207         For example, on a test machine I needed to build openssl but
208         not install it, so put the following in ``local.libnames.mk``:: 
210                 .if ${host_os} == "sunos"
211                 LIBCRYPTO = ${OBJTOP}/openssl/lib/crypto/libcrypto${DLIBEXT}
212                 LIBSSL = ${OBJTOP}/openssl/lib/ssl/libssl${DLIBEXT}
213                 INCLUDES_libcrypto = -I${OBJ_libcrypto}
214                 .endif
215                 
216         The makefile created an openssl dir in ``${OBJ_libcrypto}`` to
217         gather all the headers. dpadd.mk_ did the rest.
219 sjg.libnames.mk
220         not part of the mk-files distribution.
222 host.libnames.mk
223         contains logic to find any libs named in ``HOST_LIBS`` in
224         ``HOST_LIBDIRS``.
226 Each file above gets an opportunity to define things like::
228         LIBSSLFD        ?= ${OBJTOP}/ssl/lib/sslfd/libsslfd${DLIBEXT}
229         INCLUDES_libsslfd = -I${SRC_libsslfd}/h -I${OBJ_libslfd}
231 these are used by dpadd.mk_ and will be explained below.
233 dpadd.mk
234 --------
236 This file looks like line noise, and is best considered read-only.
237 However it provides some very useful functionality, which simplifies the build.
239 Makefiles can use the LIB* macros defined via libnames.mk_ or anywhere
240 else in various ways::
242         # indicate that we need to include headers from LIBCRYPTO
243         # this would result in ${INCLUDES_libcrypto} being added to CFLAGS.
244         SRC_LIBS += ${LIBCRYPTO}
246         # indicate that libsslfd must be built already.
247         # it also has the same effect as SRC_LIBS
248         DPADD += ${LIBSSLFD}
250         # indicate that not only must libsslfd be built, 
251         # but that we need to link with it.
252         # this is almost exactly equivalent to
253         # DPADD += ${LIBSSLFD}
254         # LDADD += -L${LIBSSLFD:H} -lsslfd
255         # and mostly serves to ensure that DPADD and LDADD are in sync.
256         DPLIBS += ${LIBSSLFD}
258 Any library (referenced by its full path) in any of the above, is
259 added to ``DPMAGIC_LIBS`` with the following results, for each lib *foo*.
261 SRC_libfoo
262         Is set to indicate where the src for libfoo is.
263         By default it is derived from ``LIBFOO`` by replacing
264         ``${OBJTOP}`` with ``${SRCTOP}``.
266 OBJ_libfoo
267         Not very exciting, is just the dir where libfoo lives.
269 INCLUDES_libfoo
270         What to add to ``CFLAGS`` to find the public headers.
271         The default varies.  If ``${SRC_libfoo}/h`` exists, it is assumed
272         to be the home of all public headers and thus the default is
273         ``-I${SRC_libfoo}/h``
275         Otherwise we make no assumptions and the default is
276         ``-I${SRC_libfoo} -I${OBJ_libfoo}``
278 LDADD_libfoo
279         This only applies to libs reference via ``DPLIBS``.
280         The default is ``-lfoo``, ``LDADD_*`` provides a hook to
281         instantiate other linker flags at the appropriate point
282         without losing the benfits of ``DPLIBS``.
284 prog.mk
285 -------
287 Compiles the specified SRCS and links them and the nominated libraries
288 into a program.  Prog makefiles usually need to list the libraries
289 that need to be linked.   We prefer use of ``DPLIBS`` but the more
290 traditional ``DPADD`` and ``LDADD`` work just as well.
291 That is::
293         DPLIBS += ${LIBRECRYPTO}
295 is equivalent to::
297         DPADD += ${LIBRECRYPTO}
298         LDADD += -lprivate_crypto
300 obj.mk
301 ------
303 One of the cool aspects of BSD make, is its support for separating
304 object files from the src tree.  This is also the source of much
305 confusion to some.
307 Traditionally one had to do a separate ``make obj`` pass through the
308 tree.  If ``MKOBJDIRS`` is "auto", we include auto.obj.mk_.
310 auto.obj.mk
311 -----------
313 This leverages the ``.OBJDIR`` target introduced some years ago to
314 NetBSD make, to automatically create the desired object dir.
316 subdir.mk
317 ---------
319 This is the traditional means of walking the tree.  A makefile sets
320 ``SUBDIR`` to the list of sub-dirs to visit.
322 If ``SUBDIR_MUST_EXIST`` is set, missing directories cause an error,
323 otherwise a warning is issued.  If you don't even want the warning,
324 set ``MISSING_DIR=continue``.
326 Traditionally, ``subdir.mk`` prints clue as it visits each subdir::
328         ===> ssl
329         ===> ssl/lib
330         ===> ssl/lib/sslfd
332 you can suppress that - or enhance it by setting ``ECHO_DIR``::
334         # suppress subdir noise
335         ECHO_DIR=:
336         # print time stamps
337         ECHO_DIR=echo @ `date "+%s [%Y-%m-%d %T] "`
339 links.mk
340 --------
342 Provides rules for processing lists of ``LINKS`` and ``SYMLINKS``.
343 Each is expected to be a list of ``link`` and ``target`` pairs
344 (``link`` -> ``target``). 
346 The logic is generally in a ``_*_SCRIPT`` which is referenced in a
347 ``_*_USE`` (``.USE``) target.
349 The ``_BUILD_*`` forms are identical, but do not use ``${DESTDIR}``
350 and so are useful for creating symlinks during the build phase.
351 For example::
353         SYMLINKS += ${.CURDIR}/${MACHINE_ARCH}/include machine
354         header_links: _BUILD_SYMLINKS_USE
355         
356         md.o: header_links
358 would create a symlink called ``machine`` in ``${.OBJDIR}`` pointing to
359 ``${.CURDIR}/${MACHINE_ARCH}/include`` before compiling ``md.o``
362 autoconf.mk
363 -----------
365 Deals with running (or generating) GNU autoconf ``configure`` scripts.
367 dep.mk
368 ------
370 Deals with collecting dependencies.  Another useful feature of BSD
371 make is the separation of this sort of information into a ``.depend``
372 file.  ``MKDEP`` needs to point to a suitable tool (like mkdeps.sh_)
374 If ``USE_AUTODEP_MK`` is "yes" includes autodep.mk_
376 autodep.mk
377 ----------
379 Leverages the ``-MD`` feature of recent GCC to collect dependency
380 information as a side effect of compilation.  With this GCC puts
381 dependency info into a ``.d`` file.
383 Unfortunately GCC bases the name of the ``.d`` file on the name of the
384 input rather than the output file, which causes problems when the same
385 source is compiled different ways.  The latest GCC supports ``-MF`` to
386 name the ``.d`` file and ``-MT`` to control the name to put as the
387 dependent.
389 Recent bmake allows dependencies for the ``.END`` target (run at the
390 end if everything was successful), and ``autodep.mk`` uses this to
391 post process the ``.d`` files into ``.depend``.
393 auto.dep.mk
394 -----------
396 A much simpler implementation than autodep.mk_ it uses 
397 ``-MF ${.TARGET:T}.d``
398 to avoid possible conflicts during parallel builds.  
399 This precludes the use of suffix rules to drive ``make depend``, so 
400 dep.mk_ handles that if specifically requested.
402 own.mk
403 ------
405 Normally included by ``init.mk`` (included by ``lib.mk`` and
406 ``prog.mk`` etc), sets macros for default ownership  etc.
408 It includes ``${MAKECONF}`` if it is defined and exists.
410 man.mk
411 ------
413 Deals with man pages.
415 warnings.mk
416 -----------
418 This provides a means of fine grained control over warnings on a per
419 ``${MACHINE}`` or even file basis.
421 A makefile sets ``WARNINGS_SET`` to name a list of warnings
422 and individual ``W_*`` macros can be used to tweak them.
423 For example::
425         WARNINGS_SET = HIGH
426         W_unused_sparc = -Wno-unused
428 would add all the warnings in ``${HIGH_WARNINGS}`` to CFLAGS, but
429 on sparc, ``-Wno-unused`` would replace ``-Wunused``.
431 You should never need to edit ``warnings.mk``, it will include
432 ``warnings-sets.mk`` if it exists and you use that to make any local
433 customizations. 
435 rst2htm.mk
436 ----------
438 Logic to simplify generating HTML (and PDF) documents from ReStructuredText.
440 cython.mk
441 ---------
443 Logic to build Python C interface modules using Cython_
445 .. _Cython: http://www.cython.org/
447 Meta mode
448 =========
450 The 20110505 and later versions of ``mk-files`` include a number of
451 makefiles contributed by Juniper Networks, Inc.  
452 These allow the latest version of bmake_ to run in `meta mode`_
453 see `dirdeps.mk`_
455 .. _`dirdeps.mk`: /help/sjg/dirdeps.htm
456 .. _`meta mode`: bmake-meta-mode.htm
458 Install
459 =======
461 You can use the content of mk.tar.gz_ without installing at all.
463 The script ``install-mk`` takes care of copying ``*.mk`` into a
464 destination directory, and unless told not to, create ``bsd.*.mk`` links
465 for ``lib.mk`` etc.
467 If you just want to create the ``bsd.*.mk`` links in the directory
468 where you unpacked the tar file, you can::
470         ./mk/install-mk ./mk
472 ------
474 .. _bmake: bmake.htm
475 .. _NetBSD: http://www.netbsd.org/
476 .. _mkdeps.sh: http://www.crufty.net/ftp/pub/sjg/mkdeps.sh
477 .. _mk.tar.gz: http://www.crufty.net/ftp/pub/sjg/mk.tar.gz
479 :Author: sjg@crufty.net
480 :Revision: $Id: mk-files.txt,v 1.16 2014/09/05 04:41:16 sjg Exp $
481 :Copyright: Crufty.NET