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