Module Name: src
Committed By: apb
Date: Mon Sep 1 13:50:15 UTC 2014
Added Files:
src/tools: README
Log Message:
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 */
To generate a diff of this commit:
cvs rdiff -u -r0 -r1.1 src/tools/README
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Added files:
Index: src/tools/README
diff -u /dev/null src/tools/README:1.1
--- /dev/null Mon Sep 1 13:50:15 2014
+++ src/tools/README Mon Sep 1 13:50:15 2014
@@ -0,0 +1,109 @@
+$NetBSD: README,v 1.1 2014/09/01 13:50:15 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 main build. Tools are relevant only when USETOOLS=yes, which is the
+default.
+
+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.
+They should restrict themselves to features that are defined in relevant
+standards, and features that are provided by the src/tools/compat
+framework.
+
+
+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 HOSTPROG in the
+make environment. 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.
+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
+ .else
+ CPPFLAGS+= -DWITH_FEATURE_X=1
+ .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:
+
+ #if HAVE_NBTOOL_CONFIG_H
+ #include "nbtool_config.h"
+ #endif /* HAVE_NBTOOL_CONFIG_H */
+
+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:
+
+ #if WITH_FEATURE_X
+ ...
+ #endif /* WITH_FEATURE_X */
+
