Home | History | Annotate | Line # | Download | only in tools
README revision 1.1 
      1 $NetBSD: README,v 1.1 2014/09/01 13:50:15 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 
     35 Compatibility framework
     36 =======================
     37 
     38 src/tools/compat provides a compatibility framework for use by tools.
     39 It 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 
     62 Adapting Makefiles for use with tools
     63 =====================================
     64 
     65 Makefiles under src/tools/*/Makefile should define HOSTPROG in the
     66 make environment.  This is typically done by tools/Makefile.hostprog,
     67 which is directly or indirectly included by all Makefiles in
     68 src/tools/*/Makefile.
     69 
     70 Makefiles 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
     72 is being built as a tool, and to modify their behaviour accordingly.
     73 For example, the Makefile may conditionally refrain from compiling and
     74 linking certain files, and the Makefile may conditionally pass macros to
     75 the 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 
     83 Adapting Programs for use with tools
     84 ====================================
     85 
     86 The 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
     89 src/tools/Makefile.host, which should be included directly or indirectly
     90 from src/tools/*/Makefile.
     91 
     92 In order to obtain the compatibility macros provided by the tools
     93 compatibility framework, almost every C source file that is built as
     94 part of a tool should have lines like this as the first non-comment
     95 lines:
     96 
     97     #if HAVE_NBTOOL_CONFIG_H
     98     #include "nbtool_config.h"
     99     #endif /* HAVE_NBTOOL_CONFIG_H */
    100 
    101 To omit features from the tools version of a program, the program's
    102 source code should use preprocessor macros that are conditionally passed
    103 from its Makefile via CPPFLAGS.  For example, it could use something
    104 like this:
    105 
    106     #if WITH_FEATURE_X 
    107        ...
    108     #endif /* WITH_FEATURE_X */
    109 
    110