Annotation of wikisrc/guide/build.mdwn, revision 1.3

1.3     ! jdf         1: **Contents**
        !             2: 
        !             3: [[!toc levels=3]]
        !             4: 
1.1       jdf         5: # Crosscompiling NetBSD with build.sh
                      6: 
1.2       jdf         7: When targeting a product for an embedded platform, it's not feasible to have all
                      8: the development tools available on that same platform. Instead, some method of
                      9: crosscompiling is usually used today. NetBSD 1.6 and forward comes with a
                     10: framework to build both the operating system's kernel and the whole userland for
                     11: either the same platform that the compiler runs on, or for a different platform,
                     12: using crosscompiling. Crosscompiling requires assembler, linker, compiler etc.
                     13: to be available and built for the target platform. The new build scheme will
                     14: take care of creating these tools for a given platform, and make them available
1.1       jdf        15: ready to use to do development work.
                     16: 
1.2       jdf        17: In this chapter, we will show how to use `build.sh` to first create a
                     18: crosscompiling toolchain, including cross-compiler, cross-assembler,
                     19: cross-linker and so on. While native kernel builds are covered in [[Compiling
                     20: the kernel|guide/kernel]], these tools are then used to manually configure and
                     21: crosscompile a kernel for a different platform, and then show how to use
                     22: `build.sh` as a convenient alternative. After that works, the whole NetBSD
                     23: userland will be compiled and packed up in the format of a NetBSD release. In
                     24: the examples, we will use the Sun UltraSPARC (*sparc64*) 64-bit platform as
                     25: target platform, any other platform supported by NetBSD can be targetted as well
1.1       jdf        26: specifying its name (see `/usr/src/sys/arch`).
                     27: 
1.2       jdf        28: Before starting, take note that it is assumed that the NetBSD sources from the
1.1       jdf        29: `netbsd-4-0` branch are available in `/usr/src` as described in
                     30: [[Obtaining the sources|guide/fetch]].
                     31: 
1.2       jdf        32: A more detailed description of the `build.sh` framework can be found in Luke
                     33: Mewburn and Matthew Green's
                     34: [paper](http://www.mewburn.net/luke/papers/build.sh.pdf) and their
                     35: [presentation](http://www.mewburn.net/luke/talks/bsdcon-2003/index.html) from
1.1       jdf        36: BSDCon 2003 as well as in `/usr/src/BUILDING`.
                     37: 
                     38: ## Building the crosscompiler
                     39: 
1.2       jdf        40: The first step to do cross-development is to get all the necessary tools
                     41: available. In NetBSD terminology, this is called the "toolchain", and it
1.1       jdf        42: includes BSD-compatible
                     43: [make(1)](http://netbsd.gw.com/cgi-bin/man-cgi?make+1+NetBSD-current),
1.2       jdf        44: C/C++ compilers, linker, assembler,
                     45: [config(8)](http://netbsd.gw.com/cgi-bin/man-cgi?config+8+NetBSD-current),
                     46: as well as a fair number of tools that are only required when crosscompiling a
1.1       jdf        47: full NetBSD release, which we won't cover here.
                     48: 
1.2       jdf        49: The command to create the crosscompiler is quite simple, using NetBSD's new
                     50: `src/build.sh` script. Please note that all the commands here can be run as
1.1       jdf        51: normal (non-root) user:
                     52: 
                     53:     $ cd /usr/src
                     54:     $ ./build.sh -m sparc64 tools
                     55: 
1.2       jdf        56: Make sure that the directory `/usr/obj` does exist, or add a `-O` option to the
1.1       jdf        57: build.sh call, redirecting the object directory someplace else.
                     58: 
1.2       jdf        59: If the tools have been built previously and they only need updated, then the
1.1       jdf        60: update option `-u` can be used to only rebuild tools that have changed:
                     61: 
                     62:     $ ./build.sh -u -m sparc64 tools
                     63: 
1.2       jdf        64: When the tools are built, information about them and several environment
1.1       jdf        65: variables is printed out:
                     66: 
                     67:     ...
                     68:     ===> build.sh started: Thu Dec  2 22:18:11 CET 2007
                     69:     ===> build.sh ended:   Thu Dec  2 22:28:22 CET 2007
                     70:     ===> Summary of results:
                     71:              build.sh command: ./build.sh -m sparc64 tools
                     72:              build.sh started: Thu Dec  2 22:18:11 CET 2007
                     73:              No nonexistent/bin/nbmake, needs building.
                     74:              Bootstrapping nbmake
                     75:              MACHINE:          sparc64
                     76:              MACHINE_ARCH:     sparc64
                     77:              TOOLDIR path:     /usr/src/tooldir.NetBSD-4.0-i386
                     78:              DESTDIR path:     /usr/src/destdir.sparc64
                     79:              RELEASEDIR path:  /usr/src/releasedir
                     80:              Created /usr/src/tooldir.NetBSD-4.0-i386/bin/nbmake
                     81:              makewrapper:      /usr/src/tooldir.NetBSD-4.0-i386/bin/nbmake-sparc64
                     82:              Updated /usr/src/tooldir.NetBSD-4.0-i386/bin/nbmake-sparc64
                     83:              Tools built to /usr/src/tooldir.NetBSD-4.0-i386
                     84:              build.sh started: Thu Dec  2 22:18:11 CET 2007
                     85:              build.sh ended:   Thu Dec  2 22:28:22 CET 2007
1.2       jdf        86:     ===> .
1.1       jdf        87: 
1.2       jdf        88: During the build, object directories are used consistently, i.e. special
                     89: directories are kept that keep the platform-specific object files and compile
                     90: results. In our example, they will be kept in directories named `obj.sparc64` as
1.1       jdf        91: we build for UltraSPARC as target platform.
                     92: 
1.2       jdf        93: The toolchain itself is part of this, but as it's hosted and compiled for a i386
                     94: system, it will get placed in its own directory indicating where to cross-build
1.1       jdf        95: from. Here's where our crosscompiler tools are located:
                     96: 
                     97:     $ pwd
                     98:     /usr/src
                     99:     $ ls -d tooldir.*
                    100:     tooldir.NetBSD-4.0-i386
                    101: 
1.2       jdf       102: So the general rule of thumb is for a given `host` and `target` system
                    103: combination, the crosscompiler will be placed in the `src/tooldir.host`
                    104: directory by default. A full list of all tools created for crosscompiling the
1.1       jdf       105: whole NetBSD operating system includes:
                    106: 
                    107:     $ ls tooldir.NetBSD-4.0-i386/bin/
                    108:     nbasn1_compile          nbmakefs                nbzic
                    109:     nbcap_mkdb              nbmakeinfo              sparc64--netbsd-addr2li
                    110:     nbcat                   nbmakewhatis            sparc64--netbsd-ar
                    111:     nbcksum                 nbmenuc                 sparc64--netbsd-as
                    112:     nbcompile_et            nbmkcsmapper            sparc64--netbsd-c++
                    113:     nbconfig                nbmkdep                 sparc64--netbsd-c++filt
                    114:     nbcrunchgen             nbmkesdb                sparc64--netbsd-cpp
                    115:     nbctags                 nbmklocale              sparc64--netbsd-dbsym
                    116:     nbdb                    nbmknod                 sparc64--netbsd-g++
                    117:     nbeqn                   nbmktemp                sparc64--netbsd-g77
                    118:     nbfgen                  nbmsgc                  sparc64--netbsd-gcc
                    119:     nbfile                  nbmtree                 sparc64--netbsd-gcc-3.3
                    120:     nbgencat                nbnroff                 sparc64--netbsd-gccbug
                    121:     nbgroff                 nbpax                   sparc64--netbsd-gcov
                    122:     nbhexdump               nbpic                   sparc64--netbsd-ld
                    123:     nbhost-mkdep            nbpwd_mkdb              sparc64--netbsd-lint
                    124:     nbindxbib               nbrefer                 sparc64--netbsd-mdsetim
                    125:     nbinfo                  nbrpcgen                sparc64--netbsd-nm
                    126:     nbinfokey               nbsoelim                sparc64--netbsd-objcopy
                    127:     nbinstall               nbstat                  sparc64--netbsd-objdump
                    128:     nbinstall-info          nbsunlabel              sparc64--netbsd-ranlib
                    129:     nbinstallboot           nbtbl                   sparc64--netbsd-readelf
                    130:     nblex                   nbtexi2dvi              sparc64--netbsd-size
                    131:     nblorder                nbtexindex              sparc64--netbsd-strings
                    132:     nbm4                    nbtsort                 sparc64--netbsd-strip
                    133:     nbmake                  nbuudecode
1.2       jdf       134:     nbmake-sparc64          nbyacc
1.1       jdf       135: 
1.2       jdf       136: As you can see, most of the tools that are available native on NetBSD are
                    137: present with some program prefix to identify the target platform for tools that
1.1       jdf       138: are specific to a certain target platform.
                    139: 
1.2       jdf       140: One important tool that should be pointed out here is `nbmake-sparc64`. This is
                    141: a shell wrapper for a BSD compatible
                    142: [make(1)](http://netbsd.gw.com/cgi-bin/man-cgi?make+1+NetBSD-5.0.1+i386) command
                    143: that's setup to use all the right commands from the crosscompiler toolchain.
                    144: Using this wrapper instead of `/usr/bin/make` allows crosscompiling programs
                    145: that were written using the NetBSD Makefile infrastructure (see `src/share/mk`).
                    146: We will use this
                    147: [make(1)](http://netbsd.gw.com/cgi-bin/man-cgi?make+1+NetBSD-5.0.1+i386) wrapper
1.1       jdf       148: in a second to cross compile the kernel!
                    149: 
                    150: ## Configuring the kernel manually
                    151: 
1.2       jdf       152: Now that we have a working crosscompiler available, the "usual" steps for
                    153: building a kernel are needed - create a kernel config file, run
                    154: [config(1)](http://netbsd.gw.com/cgi-bin/man-cgi?config+1+NetBSD-5.0.1+i386),
                    155: then build. As the
                    156: [config(1)](http://netbsd.gw.com/cgi-bin/man-cgi?config+1+NetBSD-5.0.1+i386)
                    157: program used to create header files and Makefile for a kernel build is platform
                    158: specific, we need to use the `nbconfig` program that's part of our new
                    159: toolchain. That aside, the procedure is just as like compiling a "native" NetBSD
1.1       jdf       160: kernel. Commands involved here are:
                    161: 
                    162:     $ cd /usr/src/sys/arch/sparc64/conf
                    163:     $ cp GENERIC MYKERNEL
                    164:     $ vi MYKERNEL
                    165:     $ /usr/src/tooldir.NetBSD-4.0-i386/bin/nbconfig MYKERNEL
                    166: 
1.2       jdf       167: That's all. This command has created a directory `../compile/MYKERNEL` with a
                    168: number of header files defining information about devices to compile into the
                    169: kernel, a Makefile that is setup to build all the needed files for the kernel,
1.1       jdf       170: and link them together.
                    171: 
                    172: ## Crosscompiling the kernel manually
                    173: 
1.2       jdf       174: We have all the files and tools available to crosscompile our UltraSPARC-based
                    175: kernel from our Intel-based host system, so let's get to it! After changing in
                    176: the directory created in the previous step, we need to use the crosscompiler
                    177: toolchain's `nbmake-sparc64` shell wrapper, which just calls make(1) with all
1.1       jdf       178: the necessary settings for crosscompiling for a sparc64 platform:
                    179: 
                    180:     $ cd ../compile/MYKERNEL/
                    181:     $ /usr/src/tooldir.NetBSD-4.0-i386/bin/nbmake-sparc64 depend
                    182:     $ /usr/src/tooldir.NetBSD-4.0-i386/bin/nbmake-sparc64
                    183: 
                    184: This will churn away a bit, then spit out a kernel:
                    185: 
                    186:     ...
                    187:        text    data     bss     dec     hex filename
                    188:     5016899  163728  628752 5809379  58a4e3 netbsd
                    189:     $ ls -l netbsd
                    190:     -rwxr-xr-x  1 feyrer  666  5874663 Dec  2 23:17 netbsd
                    191:     $ file netbsd
1.2       jdf       192:     netbsd: ELF 64-bit MSB executable, SPARC V9, version 1 (SYSV), statically linked, not stripped
1.1       jdf       193: 
1.2       jdf       194: Now the kernel in the file `netbsd` can either be transferred to a UltraSPARC
                    195: machine (via NFS, FTP, scp, etc.) and booted from a possible harddisk, or
1.1       jdf       196: directly from our cross-development machine using NFS.
                    197: 
1.2       jdf       198: After configuring and crosscompiling the kernel, the next logical step is to
                    199: crosscompile the whole system, and bring it into a distribution-ready format.
                    200: Before doing so, an alternative approach to crosscompiling a kernel will be
                    201: shown in the next section, using the `build.sh` script to do configuration and
1.1       jdf       202: crosscompilation of the kernel in one step.
                    203: 
                    204: ## Crosscompiling the kernel with build.sh
                    205: 
1.2       jdf       206: A cross compiled kernel can be done manually as described in the previous
1.1       jdf       207: sections, or by the easier method of using `build.sh`, which will be shown here.
                    208: 
                    209: Preparation of the kernel config file is the same as described above:
                    210: 
                    211:     $ cd /usr/src/sys/arch/sparc64/conf
                    212:     $ cp GENERIC MYKERNEL
1.2       jdf       213:     $ vi MYKERNEL
1.1       jdf       214: 
1.2       jdf       215: Then edit `MYKERNEL` and once finished, all that needs to be done is to use
                    216: `build.sh` to build the kernel (it will also configure it, running the steps
1.1       jdf       217: shown above):
                    218: 
                    219:     $ cd /usr/src
                    220:     $ ./build.sh -u -m sparc64 kernel=MYKERNEL
                    221: 
1.2       jdf       222: Notice that update (`-u`) was specified, the tools are already built, there is
                    223: no reason to rebuild all of the tools. Once the kernel is built, `build.sh` will
1.1       jdf       224: print out the location of it along with other information:
                    225: 
                    226:     ...
                    227:     ===> Summary of results:
                    228:              build.sh command: ./build.sh -u -m sparc64 kernel=MYKERNEL
                    229:              build.sh started: Thu Dec  2 23:30:02 CET 2007
                    230:              No nonexistent/bin/nbmake, needs building.
                    231:              Bootstrapping nbmake
                    232:              MACHINE:          sparc64
                    233:              MACHINE_ARCH:     sparc64
                    234:              TOOLDIR path:     /usr/src/tooldir.NetBSD-4.0-i386
                    235:              DESTDIR path:     /usr/src/destdir.sparc64
                    236:              RELEASEDIR path:  /usr/src/releasedir
                    237:              Created /usr/src/tooldir.NetBSD-4.0-i386/bin/nbmake
                    238:              makewrapper:      /usr/src/tooldir.NetBSD-4.0-i386/bin/nbmake-sparc64
                    239:              Updated /usr/src/tooldir.NetBSD-4.0-i386/bin/nbmake-sparc64
                    240:              Building kernel without building new tools
                    241:              Building kernel:  MYKERNEL
                    242:              Build directory:  /usr/src/sys/arch/sparc64/compile/obj.sparc64/GENERIC
                    243:              Kernels built from MYKERNEL:
                    244:               /usr/src/sys/arch/sparc64/compile/obj.sparc64/MYKERNEL/netbsd
                    245:              build.sh started: Thu Dec  2 23:30:02 CET 2007
                    246:              build.sh ended:   Thu Dec  2 23:38:22 CET 2007
1.2       jdf       247:     ===> .
1.1       jdf       248: 
1.2       jdf       249: The path to the kernel built is of interest here:
                    250: `/usr/src/sys/arch/sparc64/compile/obj.sparc64/MYKERNEL/netbsd`, it can be used
1.1       jdf       251: the same way as described above.
                    252: 
                    253: ## Crosscompiling the userland
                    254: 
1.2       jdf       255: By now it is probably becoming clear that the toolchain actually works in
                    256: stages. First the crosscompiler is built, then a kernel. Since `build.sh` will
                    257: attempt to rebuild the tools at every invocation, using `update` saves time. It
                    258: is probably also clear that outside of a few options, the `build.sh` semantics
                    259: are basically `build.sh command`. So, it stands to reason that building the
1.1       jdf       260: whole userland and/or a release is a matter of using the right commands.
                    261: 
1.2       jdf       262: It should be no surprise that building and creating a release would look like
1.1       jdf       263: the following:
                    264: 
                    265:     $ ./build.sh -U -u -m sparc64 release
                    266: 
1.2       jdf       267: These commands will compile the full NetBSD userland and put it into a
                    268: destination directory, and then build a release from it in a release directory.
                    269: The `-U` switch is added here for an *unprivileged* build, i.e. one that's
                    270: running as normal user and not as root. As no further switches to `build.sh`
                    271: were given nor any environment variables were set, the defaults of
                    272: `DESTDIR=/usr/src/destdir.sparc64` and `RELEASEDIR=/usr/src/releasedir` are
1.1       jdf       273: used, as shown in the `build.sh`-output above.
                    274: 
                    275: ## Crosscompiling the X Window System
                    276: 
1.2       jdf       277: The NetBSD project has its own copy of the X Window System's source which is
                    278: currently based on XFree86 version 4, and which contains changes to make X going
                    279: on as many of the platforms supported by NetBSD as possible. Due to this, it is
                    280: desirable to use the X Window System version available from and for NetBSD,
                    281: which can also be crosscompiled much like the kernel and base system. To do so,
                    282: the xsrc sources must be checked out from CVS into `/usr/xsrc` just as src
1.1       jdf       283: and pkgsrc were as described in [[Obtaining the sources|guide/fetch]].
                    284: 
1.2       jdf       285: After this, X can be crosscompiled for the target platform by adding the `-x`
1.1       jdf       286: switch to build.sh, e.g. when creating a full release:
                    287: 
                    288:     $ ./build.sh -U -x -u -m sparc64 release
                    289: 
1.2       jdf       290: The `-U` flag for doing unprivileged (non-root) builds and the `-u` flag for not
                    291: removing old files before building as well as the `-m arch` option to define the
                    292: target architecture have already been introduced, and the `-x` option to also
1.1       jdf       293: (cross)compile xsrc is another option.
                    294: 
                    295: ## Changing build behaviour
                    296: 
1.2       jdf       297: Similar to the old, manual building method, the new toolchain has a lot of
                    298: variables that can be used to direct things like where certain files go, what
                    299: (if any) tools are used and so on. A look in `src/BUILDING` covers most of them.
                    300: In this section some examples of changing default settings are given, each
1.1       jdf       301: following its own ways.
                    302: 
                    303: ### Changing the Destination Directory
                    304: 
1.2       jdf       305: Many people like to track NetBSD-current and perform cross compiles of
                    306: architectures that they use. The logic for this is simple, sometimes a new
                    307: feature or device becomes available and someone may wish to use it. By keeping
                    308: track of changes and building every now and again, one can be assured that these
1.1       jdf       309: architectures can build their own release.
                    310: 
1.2       jdf       311: It is reasonable to assume that if one is tracking and building for more than
                    312: one architecture, they might want to keep the builds in a different location
                    313: than the default. There are two ways to go about this, either use a script to
                    314: set the new DESTDIR, or simply do so interactively. In any case, it can be set
1.1       jdf       315: the same way as any other variable (depending on your shell of course).
                    316: 
                    317: For bash, the Bourne or Korn shell, this is:
                    318: 
                    319:     $ export DESTDIR=/usr/builds/sparc64
                    320: 
                    321: For tcsh and the C shell, the command is:
                    322: 
                    323:     $ setenv DESTDIR /usr/builds/sparc64
                    324: 
1.2       jdf       325: Simple enough. When the build is run, the binaries and files will be sent to
1.1       jdf       326: `/usr/builds`.
                    327: 
                    328: ### Static Builds
                    329: 
1.2       jdf       330: The NetBSD toolchain builds and links against shared libraries by default. Many
                    331: users still prefer to be able to link statically. Sometimes a small system can
                    332: be created without having shared libraries, which is a good example of doing a
                    333: full static build. If a particular build machine will always need one
                    334: environment variable set in a particular way, then it is easiest to simply add
1.1       jdf       335: the changed setting to `/etc/mk.conf`.
                    336: 
1.2       jdf       337: To make sure a build box always builds statically, simply add the following line
1.1       jdf       338: to `/etc/mk.conf`:
                    339: 
                    340:     LDSTATIC=-static
                    341: 
                    342: ### Using build.sh options
                    343: 
1.2       jdf       344: Besides variables in environment and `/etc/mk.conf`, the build process can be
                    345: influenced by a number of switches to the `build.sh` script itself, as we have
                    346: already seen when forcing unprivileged (non-root) builds, selecting the target
                    347: architecture or preventing deletion of old files before the build. All these
1.1       jdf       348: options can be listed by running `build.sh -h`:
                    349: 
                    350:     $ cd /usr/src
                    351:     $ build.sh -h
                    352:     Usage: build.sh [-EnorUux] [-a arch] [-B buildid] [-D dest] [-j njob]
                    353:             [-M obj] [-m mach] [-N noisy] [-O obj] [-R release] [-T tools]
                    354:             [-V var=[value]] [-w wrapper] [-X x11src] [-Z var]
                    355:             operation [...]
                    356:     
                    357:      Build operations (all imply "obj" and "tools"):
                    358:         build               Run "make build".
                    359:         distribution        Run "make distribution" (includes DESTDIR/etc/ files).
                    360:         release             Run "make release" (includes kernels and distrib media).
                    361:     
                    362:      Other operations:
                    363:         help                Show this message and exit.
                    364:         makewrapper         Create nbmake-${MACHINE} wrapper and nbmake.
                    365:                             Always performed.
                    366:         obj                 Run "make obj".  [Default unless -o is used]
                    367:         tools               Build and install tools.
                    368:         install=idir        Run "make installworld" to `idir' to install all sets
                    369:                 except `etc'.  Useful after "distribution" or "release"
                    370:         kernel=conf         Build kernel with config file `conf'
                    371:         releasekernel=conf  Install kernel built by kernel=conf to RELEASEDIR.
                    372:         sets                Create binary sets in RELEASEDIR/MACHINE/binary/sets.
                    373:                 DESTDIR should be populated beforehand.
                    374:         sourcesets          Create source sets in RELEASEDIR/source/sets.
                    375:         params              Display various make(1) parameters.
                    376:     
                    377:      Options:
                    378:         -a arch     Set MACHINE_ARCH to arch.  [Default: deduced from MACHINE]
                    379:         -B buildId  Set BUILDID to buildId.
                    380:         -D dest     Set DESTDIR to dest.  [Default: destdir.MACHINE]
                    381:         -E          Set "expert" mode; disables various safety checks.
                    382:                     Should not be used without expert knowledge of the build system.
                    383:         -j njob     Run up to njob jobs in parallel; see make(1) -j.
                    384:         -M obj      Set obj root directory to obj; sets MAKEOBJDIRPREFIX.
                    385:                     Unsets MAKEOBJDIR.
                    386:         -m mach     Set MACHINE to mach; not required if NetBSD native.
                    387:         -N noisy    Set the noisyness (MAKEVERBOSE) level of the build:
                    388:                 0   Quiet
                    389:                 1   Operations are described, commands are suppressed
                    390:                 2   Full output
                    391:             [Default: 2]
                    392:         -n          Show commands that would be executed, but do not execute them.
                    393:         -O obj      Set obj root directory to obj; sets a MAKEOBJDIR pattern.
                    394:                     Unsets MAKEOBJDIRPREFIX.
                    395:         -o          Set MKOBJDIRS=no; do not create objdirs at start of build.
                    396:         -R release  Set RELEASEDIR to release.  [Default: releasedir]
                    397:         -r          Remove contents of TOOLDIR and DESTDIR before building.
                    398:         -T tools    Set TOOLDIR to tools.  If unset, and TOOLDIR is not set in
                    399:                     the environment, nbmake will be (re)built unconditionally.
                    400:         -U          Set MKUNPRIVED=yes; build without requiring root privileges,
                    401:                 install from an UNPRIVED build with proper file permissions.
                    402:         -u          Set MKUPDATE=yes; do not run "make clean" first.
                    403:             Without this, everything is rebuilt, including the tools.
                    404:         -V v=[val]  Set variable `v' to `val'.
                    405:         -w wrapper  Create nbmake script as wrapper.
                    406:                     [Default: ${TOOLDIR}/bin/nbmake-${MACHINE}]
                    407:         -X x11src   Set X11SRCDIR to x11src.  [Default: /usr/xsrc]
                    408:         -x          Set MKX11=yes; build X11R6 from X11SRCDIR
1.2       jdf       409:         -Z v        Unset ("zap") variable `v'.
1.1       jdf       410: 
1.2       jdf       411: As can be seen, a number of switches can be set to change the standard build
                    412: behaviour. A number of them has already been introduced, others can be set as
1.1       jdf       413: appropriate.
                    414: 
                    415: ### make(1) variables used during build
                    416: 
1.2       jdf       417: Several variables control the behaviour of NetBSD builds. Unless otherwise
                    418: specified, these variables may be set in either the process environment or in
                    419: the [make(1)](http://netbsd.gw.com/cgi-bin/man-cgi?make+1+NetBSD-5.0.1+i386)
                    420: configuration file specified by `MAKECONF`. For a definitive list of these
                    421: options, see `BUILDING` and `share/mk/bsd.README` files in the toplevel source
1.1       jdf       422: directory.
                    423: 
1.2       jdf       424:  * *BUILDID* -- Identifier for the build. The identifier will be appended to
                    425:    object directory names, and can be consulted in the
                    426:    [make(1)](http://netbsd.gw.com/cgi-bin/man-cgi?make+1+NetBSD-5.0.1+i386)
                    427:    configuration file in order to set additional build parameters, such as
1.1       jdf       428:    compiler flags.
                    429: 
1.2       jdf       430:  * *DESTDIR* -- Directory to contain the built NetBSD system. If set, special
                    431:    options are passed to the compilation tools to prevent their default use of
                    432:    the host system's `/usr/include`, `/usr/lib`, and so forth. This pathname
                    433:    should not end with a slash (/) character (For installation into the system's
                    434:    root directory, set `DESTDIR` to an empty string). The directory must reside
1.1       jdf       435:    on a filesystem which supports long filenames and hard links.
                    436: 
1.2       jdf       437:    Defaults to an empty string if `USETOOLS` is `yes`; unset otherwise. Note:
                    438:    `build.sh` will provide a default (destdir.MACHINE in the top-level
1.1       jdf       439:    `.OBJDIR`) unless run in `expert` mode.
                    440: 
1.2       jdf       441:  * *EXTERNAL\_TOOLCHAIN* -- If defined by the user, points to the root of an
                    442:    external toolchain (e.g. `/usr/local/gnu`). This enables the cross-build
                    443:    framework even when default toolchain is not available (see
1.1       jdf       444:    `TOOLCHAIN_MISSING` below).
                    445: 
                    446:    Default: Unset
                    447: 
                    448:  * *MAKEVERBOSE* -- The verbosity of build messages. Supported values:
                    449: 
                    450:     * `0` -- No descriptive messages are shown.
                    451:     * `1` -- Descriptive messages are shown.
1.2       jdf       452:        * `2` -- Descriptive messages are shown (prefixed with a '\#') and command
1.1       jdf       453:          output is not suppressed.
                    454:    
                    455:    Default: 2
                    456: 
1.2       jdf       457:  * *MKCATPAGES* -- Can be set to `yes` or `no`. Indicates whether preformatted
1.1       jdf       458:    plaintext manual pages will be created during a build.
                    459: 
                    460:    Default: `yes`
                    461: 
1.2       jdf       462:  * *MKCRYPTO* -- Can be set to `yes` or `no`. Indicates whether cryptographic
                    463:    code will be included in a build; provided for the benefit of countries that
                    464:    do not allow strong cryptography. Will not affect the standard low-security
                    465:    password encryption system,
1.1       jdf       466:    [crypt(3)](http://netbsd.gw.com/cgi-bin/man-cgi?crypt+3+NetBSD-5.0.1+i386).
                    467: 
                    468:    Default: `yes`
                    469: 
1.2       jdf       470:  * *MKDOC* -- Can be set to `yes` or `no`. Indicates whether system
                    471:    documentation destined for `DESTDIR``/usr/share/doc` will be installed during
1.1       jdf       472:    a build.
                    473: 
                    474:    Default: `yes`
                    475: 
1.2       jdf       476:  * *MKHOSTOBJ* -- Can be set to `yes` or `no`. If set to `yes`, then for
                    477:    programs intended to be run on the compile host, the name, release and
                    478:    architecture of the host operating system will be suffixed to the name of the
                    479:    object directory created by `make obj`. This allows for multiple host systems
                    480:    to compile NetBSD for a single target. If set to `no`, then programs built to
                    481:    be run on the compile host will use the same object directory names as
1.1       jdf       482:    programs built to be run on the target.
                    483: 
                    484:    Default: `no`
                    485: 
1.2       jdf       486:  * *MKINFO* -- Can be set to `yes` or `no`. Indicates whether GNU info files,
                    487:    used for the documentation of most of the compilation tools, will be created
1.1       jdf       488:    and installed during a build.
                    489: 
                    490:    Default: `yes`
                    491: 
1.2       jdf       492:  * *MKLINT* -- Can be set to `yes` or `no`. Indicates whether
                    493:    [lint(1)](http://netbsd.gw.com/cgi-bin/man-cgi?lint+1+NetBSD-5.0.1+i386) will
                    494:    be run against portions of the NetBSD source code during the build, and
1.1       jdf       495:    whether lint libraries will be installed into `DESTDIR``/usr/libdata/lint`
                    496: 
                    497:    Default: `yes`
                    498: 
1.2       jdf       499:  * *MKMAN* -- Can be set to `yes` or `no`. Indicates whether manual pages will
1.1       jdf       500:    be installed during a build.
                    501: 
                    502:    Default: `yes`
                    503: 
1.2       jdf       504:  * *MKNLS* -- Can be set to `yes` or `no`. Indicates whether Native Language
1.1       jdf       505:    System locale zone files will be compiled and installed during a build.
                    506: 
                    507:    Default: `yes`
                    508: 
1.2       jdf       509:  * *MKOBJ* -- Can be set to `yes` or `no`. Indicates whether object directories
                    510:    will be created when running `make obj`. If set to `no`, then all built files
1.1       jdf       511:    will be located inside the regular source tree.
                    512: 
                    513:    Default: `yes`
                    514: 
1.2       jdf       515:  * *MKPIC* -- Can be set to `yes` or `no`. Indicates whether shared objects and
                    516:    libraries will be created and installed during a build. If set to `no`, the
1.1       jdf       517:    entire build will be statically linked.
                    518: 
                    519:    Default: Platform dependent. As of this writing, all platforms except sh3 default to `yes`
                    520: 
1.2       jdf       521:  * *MKPICINSTALL* -- Can be set to `yes` or `no`. Indicates whether the
                    522:    [ar(1)](http://netbsd.gw.com/cgi-bin/man-cgi?ar+1+NetBSD-5.0.1+i386) format
                    523:    libraries (`lib*_pic.a`), used to generate shared libraries, are installed
1.1       jdf       524:    during a build.
                    525: 
                    526:    Default: `yes`
                    527: 
1.2       jdf       528:  * *MKPROFILE* -- Can be set to `yes` or `no`. Indicates whether profiled
1.1       jdf       529:    libraries (`lib*_p.a`) will be built and installed during a build.
                    530: 
1.2       jdf       531:    Default: `yes`; however, some platforms turn off `MKPROFILE` by default at
1.1       jdf       532:    times due to toolchain problems with profiled code.
                    533: 
1.2       jdf       534:  * *MKSHARE* -- Can be set to `yes` or `no`. Indicates whether files destined to
                    535:    reside in `DESTDIR/usr/share` will be built and installed during a build.
                    536:    If set to `no`, then all of `MKCATPAGES`, `MKDOC`, `MKINFO`, `MKMAN` and
1.1       jdf       537:    `MKNLS` will be set to `no` unconditionally.
                    538: 
                    539:    Default: `yes`
                    540: 
1.2       jdf       541:  * *MKTTINTERP* -- Can be set to `yes` or `no`. For X builds, decides if the
                    542:    TrueType bytecode interpreter is turned on. See
1.1       jdf       543:    [freetype.org](http://freetype.org/patents.html) for details.
                    544: 
                    545:    Default: `no`
                    546: 
1.2       jdf       547:  * *MKUNPRIVED* -- Can be set to `yes` or `no`. Indicates whether an
                    548:    unprivileged install will occur. The user, group, permissions and file flags
                    549:    will not be set on the installed items; instead the information will be
                    550:    appended to a file called `METALOG` in `DESTDIR`. The contents of `METALOG`
                    551:    are used during the generation of the distribution tar files to ensure that
1.1       jdf       552:    the appropriate file ownership is stored.
                    553: 
                    554:    Default:  `no`
                    555: 
1.2       jdf       556:  * *MKUPDATE* -- Can be set to `yes` or `no`. Indicates whether all install
                    557:    operations intended to write to `DESTDIR` will compare file timestamps before
                    558:    installing, and skip the install phase if the destination files are
1.1       jdf       559:    up-to-date. This also has implications on full builds (See below).
                    560: 
                    561:    Default: `no`
                    562: 
1.2       jdf       563:  * *MKX11* -- Can be set to `yes` or `no`. Indicates whether X11R6 is built from
1.1       jdf       564:    `X11SRCDIR`.
                    565: 
                    566:    Default: `yes`
                    567: 
1.2       jdf       568:  * *TOOLDIR* -- Directory to hold the host tools, once built. This directory
                    569:    should be unique to a given host system and NetBSD source tree. (However,
                    570:    multiple targets may share the same `TOOLDIR`; the target-dependent files
                    571:    have unique names). If unset, a default based on the
                    572:    [uname(1)](http://netbsd.gw.com/cgi-bin/man-cgi?uname+1+NetBSD-5.0.1+i386)
1.1       jdf       573:    information of the host platform will be created in the `.OBJDIR` of `src`.
                    574: 
                    575:    Default: Unset.
                    576: 
1.2       jdf       577:  * *USETOOLS* -- Indicates whether the tools specified by `TOOLDIR` should be
1.1       jdf       578:    used as part of a build in progress. Must be set to `yes` if cross-compiling.
                    579: 
                    580:     * `yes` -- Use the tools from `TOOLDIR`.
1.2       jdf       581:        * `no` -- Do not use the tools from `TOOLNAME`, but refuse to build native
1.1       jdf       582:          compilation tool components that are version-specific for that tool.
1.2       jdf       583:        * `never` -- Do not use the tools from `TOOLNAME`, even when building native
                    584:          tool components. This is similar to the traditional NetBSD build method,
                    585:          but does not verify that the compilation tools in use are up-to-date
                    586:          enough in order to build the tree successfully. This may cause build or
1.1       jdf       587:          runtime problems when building the whole NetBSD source tree.
                    588: 
1.2       jdf       589:    Default: `yes` if building all or part of a whole NetBSD source tree
                    590:    (detected automatically); `no` otherwise (to preserve traditional semantics
                    591:    of the `bsd.*.mk`
                    592:    [make(1)](http://netbsd.gw.com/cgi-bin/man-cgi?make+1+NetBSD-5.0.1+i386)
1.1       jdf       593:    include files).
                    594: 
1.2       jdf       595:  * *X11SRCDIR* -- Directory containing the X11R6 source. The main X11R6 source
1.1       jdf       596:    is found in `X11SRCDIR/xfree/xc`.
                    597: 
                    598:    Default: `usr/xsrc`
                    599: 
1.2       jdf       600: The following variables only affect the top level `Makefile` and do not affect
1.1       jdf       601: manually building subtrees of the NetBSD source code.
                    602: 
1.2       jdf       603:  * *INSTALLWORLDDIR* -- Location for the `make installworld` target to install
1.1       jdf       604:    to.
                    605: 
                    606:    Default: `/`
                    607: 
1.2       jdf       608:  * *MKOBJDIRS* -- Can be set to `yes` or `no`. Indicates whether object
                    609:    directories will be created automatically (via a `make obj` pass) at the
1.1       jdf       610:    start of a build.
                    611: 
                    612:    Default: `no`
                    613: 
1.2       jdf       614:  * *MKUPDATE* -- Can be set to `yes` or `no`. If set, then addition to the
                    615:    effects described for `MKUPDATE=yes` above, this implies the effect of
1.1       jdf       616:    `NOCLEANDIR` (i.e., `make cleandir` is avoided).
                    617: 
                    618:    Default: `no`
                    619: 
1.2       jdf       620:  * *NOCLEANDIR* -- If set, avoids the `make cleandir` phase of a full build.
                    621:    This has the effect of allowing only changed files in a source tree to
                    622:    recompiled. This can speed up builds when updating only a few files in the
1.1       jdf       623:    tree.
                    624: 
                    625:    Default: Unset
                    626: 
1.2       jdf       627:  * *NODISTRIBDIRS* -- If set, avoids the `make distrib-dirs` of a full build.
                    628:    This skips running
                    629:    [mtree(8)](http://netbsd.gw.com/cgi-bin/man-cgi?mtree+8+NetBSD-5.0.1+i386) on
                    630:    `DESTDIR`, useful on systems where building as an unprivileged user, or where
1.1       jdf       631:    it is known that the system wide mtree files have not changed.
                    632: 
                    633:    Default: Unset
                    634: 
1.2       jdf       635:  * *NOINCLUDES* -- If set, avoids the `make includes` phase of a full build.
                    636:    This has the effect of preventing
                    637:    [make(1)](http://netbsd.gw.com/cgi-bin/man-cgi?make+1+NetBSD-5.0.1+i386) from
                    638:    thinking that some programs are out-of-date simply because system include
                    639:    files have changed. However, this option should not be trusted when updating
                    640:    the entire NetBSD source tree arbitrarily; it is suggested to use
1.1       jdf       641:    `MKUPDATE=yes` in that case.
                    642: 
                    643:    Default: Unset
                    644: 
1.2       jdf       645:  * *RELEASEDIR* -- If set, specifies the directory to which a
                    646:    [release(7)](http://netbsd.gw.com/cgi-bin/man-cgi?release+7+NetBSD-5.0.1+i386)
1.1       jdf       647:    layout will be written at the end of a `make release`.
                    648: 
                    649:    Default: Unset
                    650: 
1.2       jdf       651:  * *TOOLCHAIN\_MISSING* -- Set to `yes` on platforms for which there is no
                    652:    working in-tree toolchain, or if you need/wish using native system toolchain
1.1       jdf       653:    (i.e. non-cross tools available via your shell search path).
                    654: 
                    655:    Default: depends on target platform; on platforms with in-tree toolchain is set to `no`.
                    656: 

CVSweb for NetBSD wikisrc <wikimaster@NetBSD.org> software: FreeBSD-CVSweb