Module Name: src
Committed By: apb
Date: Tue Sep 30 07:34:50 UTC 2014
Modified Files:
src/tools: README
Log Message:
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.
To generate a diff of this commit:
cvs rdiff -u -r1.2 -r1.3 src/tools/README
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: src/tools/README
diff -u src/tools/README:1.2 src/tools/README:1.3
--- src/tools/README:1.2 Wed Sep 24 16:17:39 2014
+++ src/tools/README Tue Sep 30 07:34:50 2014
@@ -1,4 +1,4 @@
-$NetBSD: README,v 1.2 2014/09/24 16:17:39 apb Exp $
+$NetBSD: README,v 1.3 2014/09/30 07:34:50 apb Exp $
Notes for NetBSD src/tools
@@ -7,9 +7,9 @@ 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 main build. Tools are relevant only when USETOOLS=yes, which is the
-default.
+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
@@ -27,13 +27,20 @@ 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.
-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.
+
+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.
+
+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
@@ -66,48 +73,68 @@ ${TOOLDIR}/share/compat/defs.mk
Adapting Makefiles for use with tools
=====================================
-Makefiles under src/tools/*/Makefile should define HOSTPROG in the
-make environment. This is typically done by tools/Makefile.hostprog,
+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 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.
+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
+ CPPFLAGS+= -DWITH_FEATURE_X=0 # exclude feature X from tools build
.else
- CPPFLAGS+= -DWITH_FEATURE_X=1
+ CPPFLAGS+= -DWITH_FEATURE_X=1 # include feature X in release build
.endif
Adapting Programs for use with tools
====================================
-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:
+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 /* HAVE_NBTOOL_CONFIG_H */
+ #endif
-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:
+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
- ...
- #endif /* 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
