diff options
Diffstat (limited to 'contrib/bmake/mk/mk-files.txt')
| -rw-r--r-- | contrib/bmake/mk/mk-files.txt | 183 |
1 files changed, 142 insertions, 41 deletions
diff --git a/contrib/bmake/mk/mk-files.txt b/contrib/bmake/mk/mk-files.txt index 282f9b87a63c..6e8a4ff691f6 100644 --- a/contrib/bmake/mk/mk-files.txt +++ b/contrib/bmake/mk/mk-files.txt @@ -69,6 +69,14 @@ mk-files This section provides a brief description of some of the ``*.mk`` files. +The makefiles ``lib.mk``, ``prog.mk``, ``init.mk``, ``own.mk``, +``dep.mk`` and ``man.mk`` are more or less equivalent to ``bsd.*.mk`` +found in BSD, and when installed on non-BSD platforms get symlinked as +``bsd.*.mk`` as well. + +The other makefiles (apart from ``sys.mk``) can be used in conjunction +with ``bsd.*.mk`` on BSD. + sys.mk ------ @@ -76,7 +84,8 @@ When bmake starts, it looks for ``sys.mk`` and reads it before doing anything else. Thus, this is the place to setup the environment for everyone else. -In this distribution, ``sys.mk`` avoids doing anything platform dependent. +In this distribution, ``sys.mk`` avoids doing anything platform or +site dependent. It is quite short, and includes a number of other files (which may or may not exists) @@ -143,6 +152,8 @@ examples/sys.clean-env.mk host-target.mk Is used to set macros like ``HOST_TARGET``, ``HOST_OS`` and ``host_os`` which are used to find the next step. + Note: since 20130303 bmake provides ``.MAKE.OS`` set to + the equivalent of ``HOST_OS``. sys/\*.mk Platform specific additions, such as ``Darwin.mk`` or ``SunOS.mk`` @@ -159,27 +170,40 @@ local.sys.mk The above arrangement makes it easy for the mk files to be part of a src tree on an NFS volume and to allow building on multiple platforms. +options.mk +---------- + +Inspired by FreeBSD's ``bsd.own.mk`` but more flexible. +FreeBSD now have similar functionality in ``bsd.mkopt.mk``. + +It allows users to express their intent with respect to options +``MK_*`` by setting ``WITH_*`` or ``WITHOUT_*``. + +Note: ``WITHOUT_*`` wins if both are set, and makefiles can set +``NO_*`` to say they cannot handle that option, or even ``MK_*`` if +they really need to. + lib.mk ------ This file is used to build a number of different libraries from the same SRCS. -lib${LIB}.a +``lib${LIB}.a`` An archive lib of ``.o`` files, this is the default -lib${LIB}_p.a +``lib${LIB}_p.a`` A profiled lib of ``.po`` files. Still an archive lib, but all the objects are built with profiling in mind - hence the different extension. - It is skipped if ``MKPROFILE`` is "no". + It is skipped if ``MK_PROFILE`` is "no". -lib${LIB}_pic.a +``lib${LIB}_pic.a`` An archive of ``.so`` objects compiled for relocation. On NetBSD this is the input to ``lib${LIB}.${LD_so}``, it is - skipped if ``MKPICLIB`` is "no". + skipped if ``MK_PIC`` or ``MK_PICLIB`` are "no". -lib${LIB}.${LD_so} +``lib${LIB}.${LD_so}`` A shared library. The value of ``LD_so`` is very platform specific. For example:: @@ -190,7 +214,7 @@ lib${LIB}.${LD_so} libsslfd.1.dylib This library will only be built if ``SHLIB_MAJOR`` has - a value, and ``MKPIC`` is not set to "no". + a value, and ``MK_PIC`` is not set to "no". There is a lot of platform specific tweaking in ``lib.mk``, largely the result of the original distributions trying to avoid interfering with @@ -202,7 +226,7 @@ libnames.mk This is included by both ``prog.mk`` and ``lib.mk`` and tries to include ``*.libnames.mk`` of which: -local.libnames.mk +``local.libnames.mk`` does not exist unless you create it. It is a handy way for you to customize without touching the distributed files. For example, on a test machine I needed to build openssl but @@ -217,7 +241,7 @@ local.libnames.mk The makefile created an openssl dir in ``${OBJ_libcrypto}`` to gather all the headers. dpadd.mk_ did the rest. -host.libnames.mk +``host.libnames.mk`` contains logic to find any libs named in ``HOST_LIBS`` in ``HOST_LIBDIRS``. @@ -256,15 +280,15 @@ else in various ways:: Any library (referenced by its full path) in any of the above, is added to ``DPMAGIC_LIBS`` with the following results, for each lib *foo*. -SRC_libfoo +``SRC_libfoo`` Is set to indicate where the src for libfoo is. By default it is derived from ``LIBFOO`` by replacing ``${OBJTOP}`` with ``${SRCTOP}``. -OBJ_libfoo +``OBJ_libfoo`` Not very exciting, is just the dir where libfoo lives. -INCLUDES_libfoo +``INCLUDES_libfoo`` What to add to ``CFLAGS`` to find the public headers. The default varies. If ``${SRC_libfoo}/h`` exists, it is assumed to be the home of all public headers and thus the default is @@ -273,7 +297,7 @@ INCLUDES_libfoo Otherwise we make no assumptions and the default is ``-I${SRC_libfoo} -I${OBJ_libfoo}`` -LDADD_libfoo +``LDADD_libfoo`` This only applies to libs reference via ``DPLIBS``. The default is ``-lfoo``, ``LDADD_*`` provides a hook to instantiate other linker flags at the appropriate point @@ -300,16 +324,23 @@ obj.mk One of the cool aspects of BSD make, is its support for separating object files from the src tree. This is also the source of much -confusion to some. +confusion for people unfamiliar with it. Traditionally one had to do a separate ``make obj`` pass through the -tree. If ``MKOBJDIRS`` is "auto", we include auto.obj.mk_. +tree. If ``MK_AUTO_OBJ`` is set we include auto.obj.mk_. + +In fact if ``MKOBJDIRS`` is set to "auto", `sys.mk`_ will set +``MK_AUTO_OBJ=yes`` and include auto.obj.mk_ since it is best done early. auto.obj.mk ----------- -This leverages the ``.OBJDIR`` target introduced some years ago to -NetBSD make, to automatically create the desired object dir. +Creates object dirs and leverages the ``.OBJDIR`` target introduced +some years ago to NetBSD make, to use them. + +Note that if ``auto.obj.mk`` is to be used it should be included +early - before bmake has established ``.PATH``, thus we include it +from ``sys.mk`` rather than ``obj.mk``. subdir.mk --------- @@ -334,6 +365,8 @@ you can suppress that - or enhance it by setting ``ECHO_DIR``:: # print time stamps ECHO_DIR=echo @ `date "+%s [%Y-%m-%d %T] "` +I prefer to use `dirdeps.mk`_ which makes ``subdir.mk`` irrelevant. + links.mk -------- @@ -367,9 +400,12 @@ dep.mk Deals with collecting dependencies. Another useful feature of BSD make is the separation of this sort of information into a ``.depend`` -file. ``MKDEP`` needs to point to a suitable tool (like mkdeps.sh_) +file. ``MKDEP_CMD`` needs to point to a suitable tool (like mkdeps.sh_) + +If ``MK_AUTODEP`` is "yes" it sets ``MKDEP_MK`` to autodep.mk_ by default. -If ``USE_AUTODEP_MK`` is "yes" includes autodep.mk_ +``MKDEP_MK`` can also be set to `auto.dep.mk`_ which is more efficient +but does not support an explicit ``depend`` target. autodep.mk ---------- @@ -397,19 +433,9 @@ to avoid possible conflicts during parallel builds. This precludes the use of suffix rules to drive ``make depend``, so dep.mk_ handles that if specifically requested. -options.mk ----------- - -Inspired by FreeBSD's ``bsd.own.mk`` more flexible. -FreeBSD now have similar functionality in ``bsd.mkopt.mk``. - -It allows users to express their intent with respect to options -``MK_*`` by setting ``WITH_*`` or ``WITHOUT_*``. - -Note: ``WITHOUT_*`` wins if both are set, and makefiles can set -``NO_*`` to say they cannot handle that option, or even ``MK_*`` if -they really need to. - +If ``bmake`` is 20160218 or newer, ``auto.dep.mk`` uses ``.dinclude`` +to includes the ``*.d`` files directly thus avoiding the need to +create a ``.depend`` file from them. own.mk ------ @@ -424,7 +450,9 @@ ldorder.mk Leverages ``bmake`` to compute optimal link order for libraries. This works nicely and makes refactoring a breeze - so long as you -have not (or few) cicular dependencies between libraries. +have no (or few) cicular dependencies between libraries. + +Consider this experimental. man.mk ------ @@ -448,7 +476,7 @@ would add all the warnings in ``${HIGH_WARNINGS}`` to CFLAGS, but on sparc, ``-Wno-unused`` would replace ``-Wunused``. You should never need to edit ``warnings.mk``, it will include -``warnings-sets.mk`` if it exists and you use that to make any local +``warnings-sets.mk`` and/or ``local.warnings.mk`` to pick up customizations. rst2htm.mk @@ -463,17 +491,88 @@ Logic to build Python C interface modules using Cython_ .. _Cython: http://www.cython.org/ -Meta mode +cc-wrap.mk +---------- + +This makefile leverages two new features in bmake 20220126 and later. + +First is the ablity to set target local variables (GNU make has done +this for ages). + +The second (only intersting if using `meta mode`_) +allows filtering commands before comparison with previous run to +decide if a target is out-of-date. + +In the past, making use of compiler wrappers like ``ccache``, +``distcc`` or the newer ``icecc`` could get quite ugly. +Using ``cc-wrap.mk`` it could not be simpler. + +jobs.mk +------- + +This should be included by the top-level makefile. +If you do:: + + make something-jobs + +then ``jobs.mk`` will run:: + + make -j${JOB_MAX} someting > ${JOB_LOGDIR}/something.log 2>&1 + +this ensures you get a build log and JOB_MAX is assumed to be set +optimally for the host. + +META_MODE ========= The 20110505 and later versions of ``mk-files`` include a number of makefiles contributed by Juniper Networks, Inc. These allow the latest version of bmake_ to run in `meta mode`_ -see `dirdeps.mk`_ +see `dirdeps.mk`_ and DIRDEPS_BUILD_ below. .. _`dirdeps.mk`: /help/sjg/dirdeps.htm .. _`meta mode`: bmake-meta-mode.htm +DIRDEPS_BUILD +============= + +When the `meta mode`_ was originally done, there was no distinction +between META_MODE_ and ``DIRDEPS_BUILD``, but as these were integrated +into FreeBSD it became clear that META_MODE_ could be useful to many +developers independently of ``DIRDEPS_BUILD``. + +Thus today we distinguish between the two. +We have the following makefiles which are relevant to +``DIRDEPS_BUILD`` or META_MODE_:: + + share/mk/auto.obj.mk + share/mk/dirdeps-cache-update.mk + share/mk/dirdeps-options.mk + share/mk/dirdeps-targets.mk + share/mk/dirdeps.mk + share/mk/gendirdeps.mk + share/mk/host-target.mk + share/mk/install-new.mk + share/mk/meta.autodep.mk + share/mk/meta.stage.mk + share/mk/meta.sys.mk + share/mk/meta2deps.py + share/mk/meta2deps.sh + share/mk/sys.dependfile.mk + share/mk/sys.dirdeps.mk + +and the following are typically used for customization. +See `freebsd-meta-mode`_ and `netbsd-meta-mode`_:: + + share/mk/local.dirdeps-build.mk + share/mk/local.dirdeps-missing.mk + share/mk/local.dirdeps.mk + share/mk/local.meta.sys.mk + share/mk/local.sys.dirdeps.env.mk + share/mk/local.sys.dirdeps.mk + share/mk/local.sys.mk + + Install ======= @@ -484,7 +583,7 @@ destination directory, and unless told not to, create ``bsd.*.mk`` links for ``lib.mk`` etc. If you just want to create the ``bsd.*.mk`` links in the directory -where you unpacked the tar file, you can:: +where you unpacked the tar file, you can use:: ./mk/install-mk ./mk @@ -492,9 +591,11 @@ where you unpacked the tar file, you can:: .. _bmake: bmake.htm .. _NetBSD: http://www.netbsd.org/ -.. _mkdeps.sh: http://www.crufty.net/ftp/pub/sjg/mkdeps.sh -.. _mk.tar.gz: http://www.crufty.net/ftp/pub/sjg/mk.tar.gz +.. _mkdeps.sh: https://www.crufty.net/ftp/pub/sjg/mkdeps.sh +.. _mk.tar.gz: https://www.crufty.net/ftp/pub/sjg/mk.tar.gz +.. _`freebsd-meta-mode`: https://www.crufty.net/sjg/docs/freebsd-meta-mode.htm +.. _`netbsd-meta-mode`: https://www.crufty.net/sjg/docs/netbsd-meta-mode.htm :Author: sjg@crufty.net -:Revision: $Id: mk-files.txt,v 1.20 2020/08/19 17:51:53 sjg Exp $ +:Revision: $Id: mk-files.txt,v 1.25 2023/07/14 23:51:11 sjg Exp $ :Copyright: Crufty.NET |