tools/README

   1 $NetBSD: README,v 1.4 2015/01/03 13:20:11 apb Exp $
   2
   3 Notes for NetBSD src/tools
   4
   5
   6 Background
   7 ==========
   8
   9 Several programs that are part of NetBSD are also built as tools.  Such
  10 programs are typically built twice: once as a tool and once as part of
  11 the release build.  Tools are relevant only when the make(1) variable
  12 USETOOLS=yes, which is the default for most NetBSD builds.
  13
  14 Tools are built on the host platform, using the host compiler,
  15 and will run on the host platform during the cross-build of the
  16 remainder of NetBSD.  They are built near the beginning of a NetBSD
  17 build (e.g. "build.sh tools" or "make tools" from the top level src
  18 directory), and installed in ${TOOLDIR}.
  19
  20 Tools are executed during the main part of the build, when several
  21 TOOL_* variables defined in src/share/mk/bsd.*.mk will refer to the
  22 tools installed in ${TOOLDIR}.
  23
  24
  25 Portability
  26 ===========
  27
  28 Programs that are built as tools need to be more portable than other
  29 parts of NetBSD, because they will need to run on the host platform.
  30
  31 Most tools should restrict themselves to C language features that are
  32 defined in C89 (ISO 9899-1989); they should avoid using C99 language
  33 features.  There are a few tools, such as compilers, where it is not
  34 practical for the C89 restriction to be maintained.  There are also a
  35 few features, such as the long long data type, that are used by many
  36 tools despite not being defined in C89.
  37
  38 Tools may use library features such as functions, macros, and
  39 types, that are defined in C89 and in POSIX (IEEE Std 1003.1) (XXX
  40 year?), and features that are provided by the compatibility framework
  41 (src/tools/compat) described in a separate section below.  This is
  42 usually not an onerous burden, because many C99 library features, and
  43 NetBSD-specific features, are already provided by src/tools/compat, or
  44 can be added when the need for them becomes apparent.
  45
  46 If a tool attempts to use a feature that is not available on the host
  47 platform, then the tools build will fail.  This can be addressed by
  48 changing the tool to avoid that feature, or by adding the feature to the
  49 src/tools/compat framework.  It is usually easy to add new macros or
  50 functions to src/tools/compat, and that is usually better than adding
  51 compatibility definitions to individual tools.
  52
  53
  54 Compatibility framework
  55 =======================
  56
  57 src/tools/compat provides a compatibility framework for use by tools.
  58 It installs the following components, and more:
  59
  60 ${TOOLDIR}/lib/libnbcompat.a
  61
  62     A library containing functions that are needed by some tools.
  63
  64 ${TOOLDIR}/include/nbtool_compat.h
  65
  66     A header file defining macros that are needed by some tools.
  67
  68 ${TOOLDIR}/share/compat/defs.mk
  69
  70     A makefile fragment, to be included by other makefiles,
  71     to define make variables appropriate for building tools.
  72
  73     Among other things, this makefile fragment automatically adds
  74     the libnbcompat.a library to the LDADD and DPADD variables,
  75     so that tools will be linked with that library, and adds
  76     -I${NETBSDSRCDIR}/tools/compat and -DHAVE_NBTOOL_CONFIG_H=1 to the
  77     HOST_CPPFLAGS variable, so that compiled programs can detect when
  78     they are being built as tools.
  79
  80
  81 Adapting Makefiles for use with tools
  82 =====================================
  83
  84 Makefiles under src/tools/*/Makefile should define the HOSTPROG
  85 variable.  This is typically done by tools/Makefile.hostprog,
  86 which is directly or indirectly included by all Makefiles in
  87 src/tools/*/Makefile.
  88
  89 Makefiles in the non-tools part of the src tree can test whether or not
  90 the HOSTPROG variable is defined, in order tell the difference between
  91 building a tool and building part of a NetBSD release, and they may
  92 alter their behavior accordingly.
  93
  94 For example, the Makefile may conditionally refrain from compiling and
  95 linking certain files, and the Makefile may conditionally pass macros to
  96 the compiler via constructs like this:
  97
  98     .if defined(HOSTPROG)
  99     CPPFLAGS+= -DWITH_FEATURE_X=0 # exclude feature X from tools build
 100     .else
 101     CPPFLAGS+= -DWITH_FEATURE_X=1 # include feature X in release build
 102     .endif
 103
 104 Adapting Programs for use with tools
 105 ====================================
 106
 107 When a tool is being built, the C compiler should automatically be
 108 invoked with -DHAVE_NBTOOL_CONFIG_H=1.  This is done as a result of
 109 settings in ${TOOLDIR}/share/compat/defs.mk, which should be included
 110 from src/tools/Makefile.host, which should be included directly or
 111 indirectly from src/tools/*/Makefile.
 112
 113 A C source file can test whether the HAVE_NBTOOL_CONFIG_H macro is
 114 defined, in order to tell whether or not it is being compiled as part of
 115 a tool.
 116
 117 In order to obtain the definitions provided by the tools compatibility
 118 framework, almost every C source file that is built as part of a tool
 119 should have lines like these as the first non-comment lines:
 120
 121     #if HAVE_NBTOOL_CONFIG_H
 122     #include "nbtool_config.h"
 123     #endif
 124
 125 To omit features from the tools version of a program, the program
 126 may test the HAVE_NBTOOL_CONFIG_H macro, like this:
 127
 128     #if HAVE_NBTOOL_CONFIG_H
 129        ... code to be used when built as a tool
 130     #else
 131        ... code to be used when built as part of a release
 132     #endif
 133
 134 It is often preferable to use macros whose names refer to the features
 135 that should be included or omitted.  See the section on "Adapting
 136 Makefiles for use with tools" for an example in which the Makefile
 137 passes -DWITH_FEATURE_X=0 or -DWITH_FEATURE_X=1 to the compiler
 138 according to whether or not the program is being built as a tool.  Then
 139 the program can use code like this:
 140
 141     #if WITH_FEATURE_X
 142        ... code to be used when FEATURE X is desired,
 143        ... e.g. when being built as part of a release.
 144     #else
 145        ... code to be used when FEATURE X is not desired,
 146        ... e.g. when being built as a tool.
 147     #endif