1 $NetBSD: README,v 1.7 2025/05/01 07:40:42 martin Exp $ 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 release build. Tools are relevant only when the make(1) variable 12 USETOOLS=yes, which is the default for most NetBSD builds. 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 31 Most tools should restrict themselves to C language features that are 32 defined in C99 (ISO/IEC 9899-1999); they should avoid using C11 language 33 features, such as <threads.h>, _Alignof, <uchar.h>, _Generic, 34 static_assert, anonymous structures and unions. 35 36 Tools may use library features such as functions, macros, and types, 37 that are defined in C99 and in POSIX (IEEE Std 1003.1) (XXX year?), and 38 features that are provided by the compatibility framework 39 (src/tools/compat) described in a separate section below. 40 41 If a tool attempts to use a feature that is not available on the host 42 platform, then the tools build will fail. This can be addressed by 43 changing the tool to avoid that feature, or by adding the feature to the 44 src/tools/compat framework. It is usually easy to add new macros or 45 functions to src/tools/compat, and that is usually better than adding 46 compatibility definitions to individual tools. 47 48 49 Compatibility framework 50 ======================= 51 52 src/tools/compat provides a compatibility framework for use by tools. 53 It installs the following components, and more: 54 55 ${TOOLDIR}/lib/libnbcompat.a 56 57 A library containing functions that are needed by some tools. 58 59 ${TOOLDIR}/include/compat/nbtool_config.h 60 61 A header file defining macros that are needed by some tools. 62 63 ${TOOLDIR}/share/compat/defs.mk 64 65 A makefile fragment, to be included by other makefiles, 66 to define make variables appropriate for building tools. 67 68 Among other things, this makefile fragment automatically adds 69 the libnbcompat.a library to the LDADD and DPADD variables, 70 so that tools will be linked with that library, and adds 71 -I${NETBSDSRCDIR}/tools/compat and -DHAVE_NBTOOL_CONFIG_H=1 to the 72 HOST_CPPFLAGS variable, so that compiled programs can detect when 73 they are being built as tools. 74 75 76 Adapting Makefiles for use with tools 77 ===================================== 78 79 Makefiles under src/tools/*/Makefile should define the HOSTPROG 80 variable. This is typically done by tools/Makefile.hostprog, 81 which is directly or indirectly included by all Makefiles in 82 src/tools/*/Makefile. 83 84 Makefiles in the non-tools part of the src tree can test whether or not 85 the HOSTPROG variable is defined, in order tell the difference between 86 building a tool and building part of a NetBSD release, and they may 87 alter their behavior accordingly. 88 89 For example, the Makefile may conditionally refrain from compiling and 90 linking certain files, and the Makefile may conditionally pass macros to 91 the compiler via constructs like this: 92 93 .if defined(HOSTPROG) 94 CPPFLAGS+= -DWITH_FEATURE_X=0 # exclude feature X from tools build 95 .else 96 CPPFLAGS+= -DWITH_FEATURE_X=1 # include feature X in release build 97 .endif 98 99 Adapting Programs for use with tools 100 ==================================== 101 102 When a tool is being built, the C compiler should automatically be 103 invoked with -DHAVE_NBTOOL_CONFIG_H=1. This is done as a result of 104 settings in ${TOOLDIR}/share/compat/defs.mk, which should be included 105 from src/tools/Makefile.host, which should be included directly or 106 indirectly from src/tools/*/Makefile. 107 108 A C source file can test whether the HAVE_NBTOOL_CONFIG_H macro is 109 defined, in order to tell whether or not it is being compiled as part of 110 a tool. 111 112 In order to obtain the definitions provided by the tools compatibility 113 framework, almost every C source file that is built as part of a tool 114 should have lines like these as the first non-comment lines: 115 116 #if HAVE_NBTOOL_CONFIG_H 117 #include "nbtool_config.h" 118 #endif 119 120 To omit features from the tools version of a program, the program 121 may test the HAVE_NBTOOL_CONFIG_H macro, like this: 122 123 #if HAVE_NBTOOL_CONFIG_H 124 ... code to be used when built as a tool 125 #else 126 ... code to be used when built as part of a release 127 #endif 128 129 It is often preferable to use macros whose names refer to the features 130 that should be included or omitted. See the section on "Adapting 131 Makefiles for use with tools" for an example in which the Makefile 132 passes -DWITH_FEATURE_X=0 or -DWITH_FEATURE_X=1 to the compiler 133 according to whether or not the program is being built as a tool. Then 134 the program can use code like this: 135 136 #if WITH_FEATURE_X 137 ... code to be used when FEATURE X is desired, 138 ... e.g. when being built as part of a release. 139 #else 140 ... code to be used when FEATURE X is not desired, 141 ... e.g. when being built as a tool. 142 #endif 143
Indexes created Sat Sep 20 22:09:52 GMT 2025