xref: /src/tools/README

$NetBSD: README,v 1.2 2014/09/24 16:17:39 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.

It is usually easy to add new definitions to src/tools/compat, and that
is usually better than adding compatibility definitions to individual
tools.


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 */