contrib/bmake/mk/mk-files.txt

   1 mk-files
   2 ********
   3
   4 The term ``mk-files`` refers to a collection of ``*.mk`` files.
   5
   6 You need bmake_ or a *recent* NetBSD_ make.
   7 If in doubt use bmake_.
   8
   9 Introduction
  10 ============
  11
  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.
  15
  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.
  21
  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.
  25
  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
  29 and FreeBSD.
  30
  31 Basics
  32 ------
  33
  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*.
  38
  39 A simple library makefile might look like::
  40
  41         LIB = sig
  42
  43         SRCS = \
  44                 sigaction.c \
  45                 sigcompat.c \
  46                 sighdl.c
  47
  48         .include <lib.mk>
  49
  50 a simple program makefile::
  51
  52         PROG = cat
  53
  54         SRCS = cat.c
  55
  56         .include <prog.mk>
  57
  58 in such cases even the ``SRCS`` line is unnecessary as ``prog.mk``
  59 will default it to ``${PROG}.c``.
  60
  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.
  64
  65
  66 mk-files
  67 ========
  68
  69 This section provides a brief description of some of the ``*.mk``
  70 files.
  71
  72 sys.mk
  73 ------
  74
  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
  77 everyone else.
  78
  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
  81 may not exists)
  82
  83 sys.env.mk
  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
  87         sub-makes might need.
  88
  89 examples/sys.clean-env.mk
  90         An example of how to clean the environment.
  91         See the file for all the details::
  92
  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 \
  99                         ${_env_vars}
 100
 101                 _env_vars != env | egrep '^(${MAKE_SAVE_ENV_PREFIX:ts|})' | sed 's,=.*,,'; echo
 102                 _export_list =
 103                 .for v in ${MAKE_SAVE_ENV_VARS:O:u}
 104                 .if !empty($v)
 105                 _export_list += $v
 106                 $v := ${$v}
 107                 .endif
 108                 .endfor
 109                 # now clobber the environment
 110                 .unexport-env
 111
 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}}}
 116
 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}}
 123                 .if !empty(objtop)
 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},},}
 130
 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}
 135                 $v := ${$v}
 136                 .endfor
 137
 138                 .endif
 139                 .endif
 140                 .endif
 141
 142
 143 host-target.mk
 144         Is used to set macros like ``HOST_TARGET``, ``HOST_OS`` and
 145         ``host_os`` which are used to find the next step.
 146
 147 sys/\*.mk
 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.
 152
 153 local.sys.mk
 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.
 157
 158
 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.
 161
 162 lib.mk
 163 ------
 164
 165 This file is used to build a number of different libraries from the
 166 same SRCS.
 167
 168 lib${LIB}.a
 169         An archive lib of ``.o`` files, this is the default
 170
 171 lib${LIB}_p.a
 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".
 176
 177 lib${LIB}_pic.a
 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".
 181
 182 lib${LIB}.${LD_so}
 183         A shared library.  The value of ``LD_so`` is very platform
 184         specific.  For example::
 185
 186                 # SunOS 5 and most other ELF systems
 187                 libsslfd.so.1
 188
 189                 # Darwin
 190                 libsslfd.1.dylib
 191
 192         This library will only be built if ``SHLIB_MAJOR`` has
 193         a value, and ``MKPIC`` is not set to "no".
 194
 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``.
 198
 199 libnames.mk
 200 -----------
 201
 202 This is included by both ``prog.mk`` and ``lib.mk`` and tries to
 203 include ``*.libnames.mk`` of which:
 204
 205 local.libnames.mk
 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``::
 210
 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}
 215                 .endif
 216
 217         The makefile created an openssl dir in ``${OBJ_libcrypto}`` to
 218         gather all the headers. dpadd.mk_ did the rest.
 219
 220 sjg.libnames.mk
 221         not part of the mk-files distribution.
 222
 223 host.libnames.mk
 224         contains logic to find any libs named in ``HOST_LIBS`` in
 225         ``HOST_LIBDIRS``.
 226
 227 Each file above gets an opportunity to define things like::
 228
 229         LIBSSLFD        ?= ${OBJTOP}/ssl/lib/sslfd/libsslfd${DLIBEXT}
 230         INCLUDES_libsslfd = -I${SRC_libsslfd}/h -I${OBJ_libslfd}
 231
 232 these are used by dpadd.mk_ and will be explained below.
 233
 234 dpadd.mk
 235 --------
 236
 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.
 239
 240 Makefiles can use the LIB* macros defined via libnames.mk_ or anywhere
 241 else in various ways::
 242
 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}
 246
 247         # indicate that libsslfd must be built already.
 248         # it also has the same effect as SRC_LIBS
 249         DPADD += ${LIBSSLFD}
 250
 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}
 258
 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*.
 261
 262 SRC_libfoo
 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}``.
 266
 267 OBJ_libfoo
 268         Not very exciting, is just the dir where libfoo lives.
 269
 270 INCLUDES_libfoo
 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``
 275
 276         Otherwise we make no assumptions and the default is
 277         ``-I${SRC_libfoo} -I${OBJ_libfoo}``
 278
 279 LDADD_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``.
 284
 285 prog.mk
 286 -------
 287
 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.
 292 That is::
 293
 294         DPLIBS += ${LIBCRYPTO}
 295
 296 is equivalent to::
 297
 298         DPADD += ${LIBCRYPTO}
 299         LDADD += -lcrypto
 300
 301 obj.mk
 302 ------
 303
 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
 306 confusion to some.
 307
 308 Traditionally one had to do a separate ``make obj`` pass through the
 309 tree.  If ``MKOBJDIRS`` is "auto", we include auto.obj.mk_.
 310
 311 auto.obj.mk
 312 -----------
 313
 314 This leverages the ``.OBJDIR`` target introduced some years ago to
 315 NetBSD make, to automatically create the desired object dir.
 316
 317 subdir.mk
 318 ---------
 319
 320 This is the traditional means of walking the tree.  A makefile sets
 321 ``SUBDIR`` to the list of sub-dirs to visit.
 322
 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``.
 326
 327 Traditionally, ``subdir.mk`` prints clue as it visits each subdir::
 328
 329         ===> ssl
 330         ===> ssl/lib
 331         ===> ssl/lib/sslfd
 332
 333 you can suppress that - or enhance it by setting ``ECHO_DIR``::
 334
 335         # suppress subdir noise
 336         ECHO_DIR=:
 337         # print time stamps
 338         ECHO_DIR=echo @ `date "+%s [%Y-%m-%d %T] "`
 339
 340 links.mk
 341 --------
 342
 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``).
 346
 347 The logic is generally in a ``_*_SCRIPT`` which is referenced in a
 348 ``_*_USE`` (``.USE``) target.
 349
 350 The ``_BUILD_*`` forms are identical, but do not use ``${DESTDIR}``
 351 and so are useful for creating symlinks during the build phase.
 352 For example::
 353
 354         SYMLINKS += ${.CURDIR}/${MACHINE_ARCH}/include machine
 355         header_links: _BUILD_SYMLINKS_USE
 356
 357         md.o: header_links
 358
 359 would create a symlink called ``machine`` in ``${.OBJDIR}`` pointing to
 360 ``${.CURDIR}/${MACHINE_ARCH}/include`` before compiling ``md.o``
 361
 362
 363 autoconf.mk
 364 -----------
 365
 366 Deals with running (or generating) GNU autoconf ``configure`` scripts.
 367
 368 dep.mk
 369 ------
 370
 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_)
 374
 375 If ``USE_AUTODEP_MK`` is "yes" includes autodep.mk_
 376
 377 autodep.mk
 378 ----------
 379
 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.
 383
 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
 388 dependent.
 389
 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``.
 393
 394 auto.dep.mk
 395 -----------
 396
 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.
 402
 403 options.mk
 404 ----------
 405
 406 Inspired by FreeBSD's ``bsd.own.mk`` more flexible.
 407 FreeBSD now have similar functionality in ``bsd.mkopt.mk``.
 408
 409 It allows users to express their intent with respect to options
 410 ``MK_*`` by setting ``WITH_*`` or ``WITHOUT_*``.
 411
 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
 414 they really need to.
 415
 416
 417 own.mk
 418 ------
 419
 420 Normally included by ``init.mk`` (included by ``lib.mk`` and
 421 ``prog.mk`` etc), sets macros for default ownership  etc.
 422
 423 It includes ``${MAKECONF}`` if it is defined and exists.
 424
 425 ldorder.mk
 426 ----------
 427
 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.
 431
 432 man.mk
 433 ------
 434
 435 Deals with man pages.
 436
 437 warnings.mk
 438 -----------
 439
 440 This provides a means of fine grained control over warnings on a per
 441 ``${MACHINE}`` or even file basis.
 442
 443 A makefile sets ``WARNINGS_SET`` to name a list of warnings
 444 and individual ``W_*`` macros can be used to tweak them.
 445 For example::
 446
 447         WARNINGS_SET = HIGH
 448         W_unused_sparc = -Wno-unused
 449
 450 would add all the warnings in ``${HIGH_WARNINGS}`` to CFLAGS, but
 451 on sparc, ``-Wno-unused`` would replace ``-Wunused``.
 452
 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
 455 customizations.
 456
 457 rst2htm.mk
 458 ----------
 459
 460 Logic to simplify generating HTML (and PDF) documents from ReStructuredText.
 461
 462 cython.mk
 463 ---------
 464
 465 Logic to build Python C interface modules using Cython_
 466
 467 .. _Cython: http://www.cython.org/
 468
 469 Meta mode
 470 =========
 471
 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`_
 475 see `dirdeps.mk`_
 476
 477 .. _`dirdeps.mk`: /help/sjg/dirdeps.htm
 478 .. _`meta mode`: bmake-meta-mode.htm
 479
 480 Install
 481 =======
 482
 483 You can use the content of mk.tar.gz_ without installing at all.
 484
 485 The script ``install-mk`` takes care of copying ``*.mk`` into a
 486 destination directory, and unless told not to, create ``bsd.*.mk`` links
 487 for ``lib.mk`` etc.
 488
 489 If you just want to create the ``bsd.*.mk`` links in the directory
 490 where you unpacked the tar file, you can::
 491
 492         ./mk/install-mk ./mk
 493
 494 ------
 495
 496 .. _bmake: bmake.htm
 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
 500
 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