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