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