Return to README CVS log

Up to [cvs.NetBSD.org] / src / tools

Annotation of src/tools/README, Revision 1.1

1.1     ! apb         1: $NetBSD$
        !             2:
        !             3: Notes for NetBSD src/tools
        !             4:
        !             5:
        !             6: Background
        !             7: ==========
        !             8:
        !             9: Several programs that are part of NetBSD are also built as tools.  Such
        !            10: programs are typically built twice, once as a tool and once as part of
        !            11: the main build.  Tools are relevant only when USETOOLS=yes, which is the
        !            12: default.
        !            13:
        !            14: Tools are built on the host platform, using the host compiler,
        !            15: and will run on the host platform during the cross-build of the
        !            16: remainder of NetBSD.  They are built near the beginning of a NetBSD
        !            17: build (e.g. "build.sh tools" or "make tools" from the top level src
        !            18: directory), and installed in ${TOOLDIR}.
        !            19:
        !            20: Tools are executed during the main part of the build, when several
        !            21: TOOL_* variables defined in src/share/mk/bsd.*.mk will refer to the
        !            22: tools installed in ${TOOLDIR}.
        !            23:
        !            24:
        !            25: Portability
        !            26: ===========
        !            27:
        !            28: Programs that are built as tools need to be more portable than other
        !            29: parts of NetBSD, because they will need to run on the host platform.
        !            30: They should restrict themselves to features that are defined in relevant
        !            31: standards, and features that are provided by the src/tools/compat
        !            32: framework.
        !            33:
        !            34:
        !            35: Compatibility framework
        !            36: =======================
        !            37:
        !            38: src/tools/compat provides a compatibility framework for use by tools.
        !            39: It installs the following components, and more:
        !            40:
        !            41: ${TOOLDIR}/lib/libnbcompat.a
        !            42:
        !            43:     A library containing functions that are needed by some tools.
        !            44:
        !            45: ${TOOLDIR}/include/nbtool_compat.h
        !            46:
        !            47:     A header file defining macros that are needed by some tools.
        !            48:
        !            49: ${TOOLDIR}/share/compat/defs.mk
        !            50:
        !            51:     A makefile fragment, to be included by other makefiles,
        !            52:     to define make variables appropriate for building tools.
        !            53:
        !            54:     Among other things, this makefile fragment automatically adds
        !            55:     the libnbcompat.a library to the LDADD and DPADD variables,
        !            56:     so that tools will be linked with that library, and adds
        !            57:     -I${NETBSDSRCDIR}/tools/compat and -DHAVE_NBTOOL_CONFIG_H=1 to the
        !            58:     HOST_CPPFLAGS variable, so that compiled programs can detect when
        !            59:     they are being built as tools.
        !            60:
        !            61:
        !            62: Adapting Makefiles for use with tools
        !            63: =====================================
        !            64:
        !            65: Makefiles under src/tools/*/Makefile should define HOSTPROG in the
        !            66: make environment.  This is typically done by tools/Makefile.hostprog,
        !            67: which is directly or indirectly included by all Makefiles in
        !            68: src/tools/*/Makefile.
        !            69:
        !            70: Makefiles in the non-tools part of the src tree make use tests such as
        !            71: ".if defined(HOSTPROG)" to test whether or not the associated program
        !            72: is being built as a tool, and to modify their behaviour accordingly.
        !            73: For example, the Makefile may conditionally refrain from compiling and
        !            74: linking certain files, and the Makefile may conditionally pass macros to
        !            75: the compiler via constructs like this:
        !            76:
        !            77:     .if defined(HOSTPROG)
        !            78:     CPPFLAGS+= -DWITH_FEATURE_X=0
        !            79:     .else
        !            80:     CPPFLAGS+= -DWITH_FEATURE_X=1
        !            81:     .endif
        !            82:
        !            83: Adapting Programs for use with tools
        !            84: ====================================
        !            85:
        !            86: The compiler should automatically be invoked with
        !            87: -DHAVE_NBTOOL_CONFIG_H=1, as a result of settings in
        !            88: ${TOOLDIR}/share/compat/defs.mk, which should be included from
        !            89: src/tools/Makefile.host, which should be included directly or indirectly
        !            90: from src/tools/*/Makefile.
        !            91:
        !            92: In order to obtain the compatibility macros provided by the tools
        !            93: compatibility framework, almost every C source file that is built as
        !            94: part of a tool should have lines like this as the first non-comment
        !            95: lines:
        !            96:
        !            97:     #if HAVE_NBTOOL_CONFIG_H
        !            98:     #include "nbtool_config.h"
        !            99:     #endif /* HAVE_NBTOOL_CONFIG_H */
        !           100:
        !           101: To omit features from the tools version of a program, the program's
        !           102: source code should use preprocessor macros that are conditionally passed
        !           103: from its Makefile via CPPFLAGS.  For example, it could use something
        !           104: like this:
        !           105:
        !           106:     #if WITH_FEATURE_X
        !           107:        ...
        !           108:     #endif /* WITH_FEATURE_X */
        !           109: