1$NetBSD: README,v 1.4 2015/01/03 13:20:11 apb Exp $ 2 3Notes for NetBSD src/tools 4 5 6Background 7========== 8 9Several programs that are part of NetBSD are also built as tools. Such 10programs are typically built twice: once as a tool and once as part of 11the release build. Tools are relevant only when the make(1) variable 12USETOOLS=yes, which is the default for most NetBSD builds. 13 14Tools are built on the host platform, using the host compiler, 15and will run on the host platform during the cross-build of the 16remainder of NetBSD. They are built near the beginning of a NetBSD 17build (e.g. "build.sh tools" or "make tools" from the top level src 18directory), and installed in ${TOOLDIR}. 19 20Tools are executed during the main part of the build, when several 21TOOL_* variables defined in src/share/mk/bsd.*.mk will refer to the 22tools installed in ${TOOLDIR}. 23 24 25Portability 26=========== 27 28Programs that are built as tools need to be more portable than other 29parts of NetBSD, because they will need to run on the host platform. 30 31Most tools should restrict themselves to C language features that are 32defined in C89 (ISO 9899-1989); they should avoid using C99 language 33features. There are a few tools, such as compilers, where it is not 34practical for the C89 restriction to be maintained. There are also a 35few features, such as the long long data type, that are used by many 36tools despite not being defined in C89. 37 38Tools may use library features such as functions, macros, and 39types, that are defined in C89 and in POSIX (IEEE Std 1003.1) (XXX 40year?), and features that are provided by the compatibility framework 41(src/tools/compat) described in a separate section below. This is 42usually not an onerous burden, because many C99 library features, and 43NetBSD-specific features, are already provided by src/tools/compat, or 44can be added when the need for them becomes apparent. 45 46If a tool attempts to use a feature that is not available on the host 47platform, then the tools build will fail. This can be addressed by 48changing the tool to avoid that feature, or by adding the feature to the 49src/tools/compat framework. It is usually easy to add new macros or 50functions to src/tools/compat, and that is usually better than adding 51compatibility definitions to individual tools. 52 53 54Compatibility framework 55======================= 56 57src/tools/compat provides a compatibility framework for use by tools. 58It installs the following components, and more: 59 60${TOOLDIR}/lib/libnbcompat.a 61 62 A library containing functions that are needed by some tools. 63 64${TOOLDIR}/include/nbtool_compat.h 65 66 A header file defining macros that are needed by some tools. 67 68${TOOLDIR}/share/compat/defs.mk 69 70 A makefile fragment, to be included by other makefiles, 71 to define make variables appropriate for building tools. 72 73 Among other things, this makefile fragment automatically adds 74 the libnbcompat.a library to the LDADD and DPADD variables, 75 so that tools will be linked with that library, and adds 76 -I${NETBSDSRCDIR}/tools/compat and -DHAVE_NBTOOL_CONFIG_H=1 to the 77 HOST_CPPFLAGS variable, so that compiled programs can detect when 78 they are being built as tools. 79 80 81Adapting Makefiles for use with tools 82===================================== 83 84Makefiles under src/tools/*/Makefile should define the HOSTPROG 85variable. This is typically done by tools/Makefile.hostprog, 86which is directly or indirectly included by all Makefiles in 87src/tools/*/Makefile. 88 89Makefiles in the non-tools part of the src tree can test whether or not 90the HOSTPROG variable is defined, in order tell the difference between 91building a tool and building part of a NetBSD release, and they may 92alter their behavior accordingly. 93 94For example, the Makefile may conditionally refrain from compiling and 95linking certain files, and the Makefile may conditionally pass macros to 96the compiler via constructs like this: 97 98 .if defined(HOSTPROG) 99 CPPFLAGS+= -DWITH_FEATURE_X=0 # exclude feature X from tools build 100 .else 101 CPPFLAGS+= -DWITH_FEATURE_X=1 # include feature X in release build 102 .endif 103 104Adapting Programs for use with tools 105==================================== 106 107When a tool is being built, the C compiler should automatically be 108invoked with -DHAVE_NBTOOL_CONFIG_H=1. This is done as a result of 109settings in ${TOOLDIR}/share/compat/defs.mk, which should be included 110from src/tools/Makefile.host, which should be included directly or 111indirectly from src/tools/*/Makefile. 112 113A C source file can test whether the HAVE_NBTOOL_CONFIG_H macro is 114defined, in order to tell whether or not it is being compiled as part of 115a tool. 116 117In order to obtain the definitions provided by the tools compatibility 118framework, almost every C source file that is built as part of a tool 119should have lines like these as the first non-comment lines: 120 121 #if HAVE_NBTOOL_CONFIG_H 122 #include "nbtool_config.h" 123 #endif 124 125To omit features from the tools version of a program, the program 126may test the HAVE_NBTOOL_CONFIG_H macro, like this: 127 128 #if HAVE_NBTOOL_CONFIG_H 129 ... code to be used when built as a tool 130 #else 131 ... code to be used when built as part of a release 132 #endif 133 134It is often preferable to use macros whose names refer to the features 135that should be included or omitted. See the section on "Adapting 136Makefiles for use with tools" for an example in which the Makefile 137passes -DWITH_FEATURE_X=0 or -DWITH_FEATURE_X=1 to the compiler 138according to whether or not the program is being built as a tool. Then 139the program can use code like this: 140 141 #if WITH_FEATURE_X 142 ... code to be used when FEATURE X is desired, 143 ... e.g. when being built as part of a release. 144 #else 145 ... code to be used when FEATURE X is not desired, 146 ... e.g. when being built as a tool. 147 #endif 148