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