head 1.5; access; symbols netbsd-10-0-RELEASE:1.5 netbsd-10-0-RC6:1.5 netbsd-10-0-RC5:1.5 netbsd-10-0-RC4:1.5 netbsd-10-0-RC3:1.5 netbsd-10-0-RC2:1.5 netbsd-10-0-RC1:1.5 netbsd-10:1.5.0.2 netbsd-10-base:1.5 netbsd-9-3-RELEASE:1.4 cjep_sun2x-base1:1.4 cjep_sun2x:1.4.0.24 cjep_sun2x-base:1.4 cjep_staticlib_x-base1:1.4 netbsd-9-2-RELEASE:1.4 cjep_staticlib_x:1.4.0.22 cjep_staticlib_x-base:1.4 netbsd-9-1-RELEASE:1.4 phil-wifi-20200421:1.4 phil-wifi-20200411:1.4 is-mlppp:1.4.0.20 is-mlppp-base:1.4 phil-wifi-20200406:1.4 netbsd-8-2-RELEASE:1.4 netbsd-9-0-RELEASE:1.4 netbsd-9-0-RC2:1.4 netbsd-9-0-RC1:1.4 phil-wifi-20191119:1.4 netbsd-9:1.4.0.18 netbsd-9-base:1.4 phil-wifi-20190609:1.4 netbsd-8-1-RELEASE:1.4 netbsd-8-1-RC1:1.4 pgoyette-compat-merge-20190127:1.4 pgoyette-compat-20190127:1.4 pgoyette-compat-20190118:1.4 pgoyette-compat-1226:1.4 pgoyette-compat-1126:1.4 pgoyette-compat-1020:1.4 pgoyette-compat-0930:1.4 pgoyette-compat-0906:1.4 pgoyette-compat-0728:1.4 netbsd-8-0-RELEASE:1.4 phil-wifi:1.4.0.16 phil-wifi-base:1.4 pgoyette-compat-0625:1.4 netbsd-8-0-RC2:1.4 pgoyette-compat-0521:1.4 pgoyette-compat-0502:1.4 pgoyette-compat-0422:1.4 netbsd-8-0-RC1:1.4 pgoyette-compat-0415:1.4 pgoyette-compat-0407:1.4 pgoyette-compat-0330:1.4 pgoyette-compat-0322:1.4 pgoyette-compat-0315:1.4 pgoyette-compat:1.4.0.14 pgoyette-compat-base:1.4 matt-nb8-mediatek:1.4.0.12 matt-nb8-mediatek-base:1.4 perseant-stdc-iso10646:1.4.0.10 perseant-stdc-iso10646-base:1.4 netbsd-8:1.4.0.8 netbsd-8-base:1.4 prg-localcount2-base3:1.4 prg-localcount2-base2:1.4 prg-localcount2-base1:1.4 prg-localcount2:1.4.0.6 prg-localcount2-base:1.4 pgoyette-localcount-20170426:1.4 bouyer-socketcan-base1:1.4 pgoyette-localcount-20170320:1.4 bouyer-socketcan:1.4.0.4 bouyer-socketcan-base:1.4 pgoyette-localcount-20170107:1.4 pgoyette-localcount-20161104:1.4 localcount-20160914:1.4 pgoyette-localcount-20160806:1.4 pgoyette-localcount-20160726:1.4 pgoyette-localcount:1.4.0.2 pgoyette-localcount-base:1.4; locks; strict; comment @# @; 1.5 date 2022.02.03.20.32.38; author rillig; state Exp; branches; next 1.4; commitid YHmimDqJgDjTddrD; 1.4 date 2015.01.03.13.20.11; author apb; state Exp; branches; next 1.3; commitid il4C3LpJoG1M1A4y; 1.3 date 2014.09.30.07.34.50; author apb; state Exp; branches; next 1.2; commitid 3Gl4xdQunWaxblSx; 1.2 date 2014.09.24.16.17.39; author apb; state Exp; branches; next 1.1; commitid QwRzwRXiAeLRdCRx; 1.1 date 2014.09.01.13.50.15; author apb; state Exp; branches; next ; commitid P7QTK1z1lAD8cEOx; desc @@ 1.5 log @tools: allow tools to use C99 The previous requirement was that tools should only use C89 features. Several tools did not follow this rule for years. Since nobody complained about not being able to build NetBSD in a C89 environment, drop that rule, now requiring C99. https://mail-index.netbsd.org/tech-toolchain/2022/01/30/msg004091.html @ text @$NetBSD: README,v 1.4 2015/01/03 13:20:11 apb Exp $ Notes for NetBSD src/tools Background ========== Several programs that are part of NetBSD are also built as tools. Such programs are typically built twice: once as a tool and once as part of the release build. Tools are relevant only when the make(1) variable USETOOLS=yes, which is the default for most NetBSD builds. Tools are built on the host platform, using the host compiler, and will run on the host platform during the cross-build of the remainder of NetBSD. They are built near the beginning of a NetBSD build (e.g. "build.sh tools" or "make tools" from the top level src directory), and installed in ${TOOLDIR}. Tools are executed during the main part of the build, when several TOOL_* variables defined in src/share/mk/bsd.*.mk will refer to the tools installed in ${TOOLDIR}. Portability =========== Programs that are built as tools need to be more portable than other parts of NetBSD, because they will need to run on the host platform. Most tools should restrict themselves to C language features that are defined in C99 (ISO/IEC 9899-1999); they should avoid using C11 language features, such as , _Alignof, , _Generic, static_assert, anonymous structures and unions. Tools may use library features such as functions, macros, and types, that are defined in C99 and in POSIX (IEEE Std 1003.1) (XXX year?), and features that are provided by the compatibility framework (src/tools/compat) described in a separate section below. If a tool attempts to use a feature that is not available on the host platform, then the tools build will fail. This can be addressed by changing the tool to avoid that feature, or by adding the feature to the src/tools/compat framework. It is usually easy to add new macros or functions to src/tools/compat, and that is usually better than adding compatibility definitions to individual tools. Compatibility framework ======================= src/tools/compat provides a compatibility framework for use by tools. It installs the following components, and more: ${TOOLDIR}/lib/libnbcompat.a A library containing functions that are needed by some tools. ${TOOLDIR}/include/nbtool_compat.h A header file defining macros that are needed by some tools. ${TOOLDIR}/share/compat/defs.mk A makefile fragment, to be included by other makefiles, to define make variables appropriate for building tools. Among other things, this makefile fragment automatically adds the libnbcompat.a library to the LDADD and DPADD variables, so that tools will be linked with that library, and adds -I${NETBSDSRCDIR}/tools/compat and -DHAVE_NBTOOL_CONFIG_H=1 to the HOST_CPPFLAGS variable, so that compiled programs can detect when they are being built as tools. Adapting Makefiles for use with tools ===================================== Makefiles under src/tools/*/Makefile should define the HOSTPROG variable. This is typically done by tools/Makefile.hostprog, which is directly or indirectly included by all Makefiles in src/tools/*/Makefile. Makefiles in the non-tools part of the src tree can test whether or not the HOSTPROG variable is defined, in order tell the difference between building a tool and building part of a NetBSD release, and they may alter their behavior accordingly. For example, the Makefile may conditionally refrain from compiling and linking certain files, and the Makefile may conditionally pass macros to the compiler via constructs like this: .if defined(HOSTPROG) CPPFLAGS+= -DWITH_FEATURE_X=0 # exclude feature X from tools build .else CPPFLAGS+= -DWITH_FEATURE_X=1 # include feature X in release build .endif Adapting Programs for use with tools ==================================== When a tool is being built, the C compiler should automatically be invoked with -DHAVE_NBTOOL_CONFIG_H=1. This is done as a result of settings in ${TOOLDIR}/share/compat/defs.mk, which should be included from src/tools/Makefile.host, which should be included directly or indirectly from src/tools/*/Makefile. A C source file can test whether the HAVE_NBTOOL_CONFIG_H macro is defined, in order to tell whether or not it is being compiled as part of a tool. In order to obtain the definitions provided by the tools compatibility framework, almost every C source file that is built as part of a tool should have lines like these as the first non-comment lines: #if HAVE_NBTOOL_CONFIG_H #include "nbtool_config.h" #endif To omit features from the tools version of a program, the program may test the HAVE_NBTOOL_CONFIG_H macro, like this: #if HAVE_NBTOOL_CONFIG_H ... code to be used when built as a tool #else ... code to be used when built as part of a release #endif It is often preferable to use macros whose names refer to the features that should be included or omitted. See the section on "Adapting Makefiles for use with tools" for an example in which the Makefile passes -DWITH_FEATURE_X=0 or -DWITH_FEATURE_X=1 to the compiler according to whether or not the program is being built as a tool. Then the program can use code like this: #if WITH_FEATURE_X ... code to be used when FEATURE X is desired, ... e.g. when being built as part of a release. #else ... code to be used when FEATURE X is not desired, ... e.g. when being built as a tool. #endif @ 1.4 log @Update documentation about tools being restricted to C89 (or not). It's not practical for the C89 restriction to be maintained for compilers, but it is still desirable for most tools. The "long long" data type is in wide use despite not being in C89. C99 library features (as opposed to language features) can often be added to the compat framework when the need becomes apparent. @ text @d1 1 a1 1 $NetBSD: README,v 1.3 2014/09/30 07:34:50 apb Exp $ d32 8 a39 13 defined in C89 (ISO 9899-1989); they should avoid using C99 language features. There are a few tools, such as compilers, where it is not practical for the C89 restriction to be maintained. There are also a few features, such as the long long data type, that are used by many tools despite not being defined in C89. Tools may use library features such as functions, macros, and types, that are defined in C89 and in POSIX (IEEE Std 1003.1) (XXX year?), and features that are provided by the compatibility framework (src/tools/compat) described in a separate section below. This is usually not an onerous burden, because many C99 library features, and NetBSD-specific features, are already provided by src/tools/compat, or can be added when the need for them becomes apparent. @ 1.3 log @Say that tools should use C89, not C99; Say that tools may use HAVE_NBTOOL_CONFIG_H to conditionally exclude features. Many other small changes. @ text @d1 1 a1 1 $NetBSD: README,v 1.2 2014/09/24 16:17:39 apb Exp $ d31 14 a44 6 Tools should restrict themselves to C language features that are defined in C89 (ISO 9899-1989); they should avoid using C99 features. Tools may library features defined in C89 and in POSIX (IEEE Std 1003.1) (XXX year?), and features that are provided by the src/tools/compat framework described below. a147 1 @ 1.2 log @It is usually easy to add new definitions to src/tools/compat, and that is usually better than adding compatibility definitions to individual tools. @ text @d1 1 a1 1 $NetBSD: README,v 1.1 2014/09/01 13:50:15 apb Exp $ d10 3 a12 3 programs are typically built twice, once as a tool and once as part of the main build. Tools are relevant only when USETOOLS=yes, which is the default. d30 14 a43 7 They should restrict themselves to features that are defined in relevant standards, and features that are provided by the src/tools/compat framework. It is usually easy to add new definitions to src/tools/compat, and that is usually better than adding compatibility definitions to individual tools. d76 2 a77 2 Makefiles under src/tools/*/Makefile should define HOSTPROG in the make environment. This is typically done by tools/Makefile.hostprog, d81 5 a85 3 Makefiles in the non-tools part of the src tree make use tests such as ".if defined(HOSTPROG)" to test whether or not the associated program is being built as a tool, and to modify their behaviour accordingly. d91 1 a91 1 CPPFLAGS+= -DWITH_FEATURE_X=0 d93 1 a93 1 CPPFLAGS+= -DWITH_FEATURE_X=1 d99 13 a111 10 The compiler should automatically be invoked with -DHAVE_NBTOOL_CONFIG_H=1, as a result of settings in ${TOOLDIR}/share/compat/defs.mk, which should be included from src/tools/Makefile.host, which should be included directly or indirectly from src/tools/*/Makefile. In order to obtain the compatibility macros provided by the tools compatibility framework, almost every C source file that is built as part of a tool should have lines like this as the first non-comment lines: d115 1 a115 1 #endif /* HAVE_NBTOOL_CONFIG_H */ d117 15 a131 4 To omit features from the tools version of a program, the program's source code should use preprocessor macros that are conditionally passed from its Makefile via CPPFLAGS. For example, it could use something like this: d134 6 a139 2 ... #endif /* WITH_FEATURE_X */ @ 1.1 log @Add tools/README, to collect hints like how to use .if defined(HOSTPROG) and #if HAVE_NBTOOL_CONFIG_H #include "nbtool_config.h" #endif /* HAVE_NBTOOL_CONFIG_H */ @ text @d1 1 a1 1 $NetBSD$ d34 4 @