1*afeb3d00Srillig$NetBSD: README,v 1.5 2022/02/03 20:32:38 rillig Exp $ 20ecf7ee7Sapb 30ecf7ee7SapbNotes for NetBSD src/tools 40ecf7ee7Sapb 50ecf7ee7Sapb 60ecf7ee7SapbBackground 70ecf7ee7Sapb========== 80ecf7ee7Sapb 90ecf7ee7SapbSeveral programs that are part of NetBSD are also built as tools. Such 10a4a57f7bSapbprograms are typically built twice: once as a tool and once as part of 11a4a57f7bSapbthe release build. Tools are relevant only when the make(1) variable 12a4a57f7bSapbUSETOOLS=yes, which is the default for most NetBSD builds. 130ecf7ee7Sapb 140ecf7ee7SapbTools are built on the host platform, using the host compiler, 150ecf7ee7Sapband will run on the host platform during the cross-build of the 160ecf7ee7Sapbremainder of NetBSD. They are built near the beginning of a NetBSD 170ecf7ee7Sapbbuild (e.g. "build.sh tools" or "make tools" from the top level src 180ecf7ee7Sapbdirectory), and installed in ${TOOLDIR}. 190ecf7ee7Sapb 200ecf7ee7SapbTools are executed during the main part of the build, when several 210ecf7ee7SapbTOOL_* variables defined in src/share/mk/bsd.*.mk will refer to the 220ecf7ee7Sapbtools installed in ${TOOLDIR}. 230ecf7ee7Sapb 240ecf7ee7Sapb 250ecf7ee7SapbPortability 260ecf7ee7Sapb=========== 270ecf7ee7Sapb 280ecf7ee7SapbPrograms that are built as tools need to be more portable than other 290ecf7ee7Sapbparts of NetBSD, because they will need to run on the host platform. 300ecf7ee7Sapb 31106ab6c8SapbMost tools should restrict themselves to C language features that are 32*afeb3d00Srilligdefined in C99 (ISO/IEC 9899-1999); they should avoid using C11 language 33*afeb3d00Srilligfeatures, such as <threads.h>, _Alignof, <uchar.h>, _Generic, 34*afeb3d00Srilligstatic_assert, anonymous structures and unions. 35a4a57f7bSapb 36*afeb3d00SrilligTools may use library features such as functions, macros, and types, 37*afeb3d00Srilligthat are defined in C99 and in POSIX (IEEE Std 1003.1) (XXX year?), and 38*afeb3d00Srilligfeatures that are provided by the compatibility framework 39*afeb3d00Srillig(src/tools/compat) described in a separate section below. 40a4a57f7bSapb 41a4a57f7bSapbIf a tool attempts to use a feature that is not available on the host 42a4a57f7bSapbplatform, then the tools build will fail. This can be addressed by 43a4a57f7bSapbchanging the tool to avoid that feature, or by adding the feature to the 44a4a57f7bSapbsrc/tools/compat framework. It is usually easy to add new macros or 45a4a57f7bSapbfunctions to src/tools/compat, and that is usually better than adding 46a4a57f7bSapbcompatibility definitions to individual tools. 47f6ecb478Sapb 480ecf7ee7Sapb 490ecf7ee7SapbCompatibility framework 500ecf7ee7Sapb======================= 510ecf7ee7Sapb 520ecf7ee7Sapbsrc/tools/compat provides a compatibility framework for use by tools. 530ecf7ee7SapbIt installs the following components, and more: 540ecf7ee7Sapb 550ecf7ee7Sapb${TOOLDIR}/lib/libnbcompat.a 560ecf7ee7Sapb 570ecf7ee7Sapb A library containing functions that are needed by some tools. 580ecf7ee7Sapb 590ecf7ee7Sapb${TOOLDIR}/include/nbtool_compat.h 600ecf7ee7Sapb 610ecf7ee7Sapb A header file defining macros that are needed by some tools. 620ecf7ee7Sapb 630ecf7ee7Sapb${TOOLDIR}/share/compat/defs.mk 640ecf7ee7Sapb 650ecf7ee7Sapb A makefile fragment, to be included by other makefiles, 660ecf7ee7Sapb to define make variables appropriate for building tools. 670ecf7ee7Sapb 680ecf7ee7Sapb Among other things, this makefile fragment automatically adds 690ecf7ee7Sapb the libnbcompat.a library to the LDADD and DPADD variables, 700ecf7ee7Sapb so that tools will be linked with that library, and adds 710ecf7ee7Sapb -I${NETBSDSRCDIR}/tools/compat and -DHAVE_NBTOOL_CONFIG_H=1 to the 720ecf7ee7Sapb HOST_CPPFLAGS variable, so that compiled programs can detect when 730ecf7ee7Sapb they are being built as tools. 740ecf7ee7Sapb 750ecf7ee7Sapb 760ecf7ee7SapbAdapting Makefiles for use with tools 770ecf7ee7Sapb===================================== 780ecf7ee7Sapb 79a4a57f7bSapbMakefiles under src/tools/*/Makefile should define the HOSTPROG 80a4a57f7bSapbvariable. This is typically done by tools/Makefile.hostprog, 810ecf7ee7Sapbwhich is directly or indirectly included by all Makefiles in 820ecf7ee7Sapbsrc/tools/*/Makefile. 830ecf7ee7Sapb 84a4a57f7bSapbMakefiles in the non-tools part of the src tree can test whether or not 85a4a57f7bSapbthe HOSTPROG variable is defined, in order tell the difference between 86a4a57f7bSapbbuilding a tool and building part of a NetBSD release, and they may 87a4a57f7bSapbalter their behavior accordingly. 88a4a57f7bSapb 890ecf7ee7SapbFor example, the Makefile may conditionally refrain from compiling and 900ecf7ee7Sapblinking certain files, and the Makefile may conditionally pass macros to 910ecf7ee7Sapbthe compiler via constructs like this: 920ecf7ee7Sapb 930ecf7ee7Sapb .if defined(HOSTPROG) 94a4a57f7bSapb CPPFLAGS+= -DWITH_FEATURE_X=0 # exclude feature X from tools build 950ecf7ee7Sapb .else 96a4a57f7bSapb CPPFLAGS+= -DWITH_FEATURE_X=1 # include feature X in release build 970ecf7ee7Sapb .endif 980ecf7ee7Sapb 990ecf7ee7SapbAdapting Programs for use with tools 1000ecf7ee7Sapb==================================== 1010ecf7ee7Sapb 102a4a57f7bSapbWhen a tool is being built, the C compiler should automatically be 103a4a57f7bSapbinvoked with -DHAVE_NBTOOL_CONFIG_H=1. This is done as a result of 104a4a57f7bSapbsettings in ${TOOLDIR}/share/compat/defs.mk, which should be included 105a4a57f7bSapbfrom src/tools/Makefile.host, which should be included directly or 106a4a57f7bSapbindirectly from src/tools/*/Makefile. 1070ecf7ee7Sapb 108a4a57f7bSapbA C source file can test whether the HAVE_NBTOOL_CONFIG_H macro is 109a4a57f7bSapbdefined, in order to tell whether or not it is being compiled as part of 110a4a57f7bSapba tool. 111a4a57f7bSapb 112a4a57f7bSapbIn order to obtain the definitions provided by the tools compatibility 113a4a57f7bSapbframework, almost every C source file that is built as part of a tool 114a4a57f7bSapbshould have lines like these as the first non-comment lines: 1150ecf7ee7Sapb 1160ecf7ee7Sapb #if HAVE_NBTOOL_CONFIG_H 1170ecf7ee7Sapb #include "nbtool_config.h" 118a4a57f7bSapb #endif 1190ecf7ee7Sapb 120a4a57f7bSapbTo omit features from the tools version of a program, the program 121a4a57f7bSapbmay test the HAVE_NBTOOL_CONFIG_H macro, like this: 122a4a57f7bSapb 123a4a57f7bSapb #if HAVE_NBTOOL_CONFIG_H 124a4a57f7bSapb ... code to be used when built as a tool 125a4a57f7bSapb #else 126a4a57f7bSapb ... code to be used when built as part of a release 127a4a57f7bSapb #endif 128a4a57f7bSapb 129a4a57f7bSapbIt is often preferable to use macros whose names refer to the features 130a4a57f7bSapbthat should be included or omitted. See the section on "Adapting 131a4a57f7bSapbMakefiles for use with tools" for an example in which the Makefile 132a4a57f7bSapbpasses -DWITH_FEATURE_X=0 or -DWITH_FEATURE_X=1 to the compiler 133a4a57f7bSapbaccording to whether or not the program is being built as a tool. Then 134a4a57f7bSapbthe program can use code like this: 1350ecf7ee7Sapb 1360ecf7ee7Sapb #if WITH_FEATURE_X 137a4a57f7bSapb ... code to be used when FEATURE X is desired, 138a4a57f7bSapb ... e.g. when being built as part of a release. 139a4a57f7bSapb #else 140a4a57f7bSapb ... code to be used when FEATURE X is not desired, 141a4a57f7bSapb ... e.g. when being built as a tool. 142a4a57f7bSapb #endif 143