[BACK]Return to BUILDING.mdoc CVS log [TXT][DIR] Up to [cvs.NetBSD.org] / src

Annotation of src/BUILDING.mdoc, Revision 1.2

1.2     ! tv          1: .\"    $NetBSD: BUILDING.mdoc,v 1.1 2001/10/29 19:46:47 tv Exp $
1.1       tv          2: .\"
                      3: .\" Copyright (c) 2001 The NetBSD Foundation, Inc.
                      4: .\" All rights reserved.
                      5: .\"
                      6: .\" This code is derived from software contributed to The NetBSD Foundation
                      7: .\" by Todd Vierling.
                      8: .\"
                      9: .\" Redistribution and use in source and binary forms, with or without
                     10: .\" modification, are permitted provided that the following conditions
                     11: .\" are met:
                     12: .\" 1. Redistributions of source code must retain the above copyright
                     13: .\"    notice, this list of conditions and the following disclaimer.
                     14: .\" 2. Redistributions in binary form must reproduce the above copyright
                     15: .\"    notice, this list of conditions and the following disclaimer in the
                     16: .\"    documentation and/or other materials provided with the distribution.
                     17: .\" 3. All advertising materials mentioning features or use of this software
                     18: .\"    must display the following acknowledgement:
                     19: .\"        This product includes software developed by the NetBSD
                     20: .\"        Foundation, Inc. and its contributors.
                     21: .\" 4. Neither the name of The NetBSD Foundation nor the names of its
                     22: .\"    contributors may be used to endorse or promote products derived
                     23: .\"    from this software without specific prior written permission.
                     24: .\"
                     25: .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
                     26: .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
                     27: .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
                     28: .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
                     29: .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
                     30: .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
                     31: .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
                     32: .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
                     33: .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
                     34: .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
                     35: .\" POSSIBILITY OF SUCH DAMAGE.
                     36: .\"
1.2     ! tv         37: .\" =====
        !            38: .\" NOTE: After changing this file, run "make build-docs" to generate the
        !            39: .\" proper plaintext versions, and check in all BUILDING.* files!
        !            40: .\"
1.1       tv         41: .Dd October 29, 2001
                     42: .Dt BUILDING 8
                     43: .Os NetBSD
                     44: .
                     45: .Sh NAME
                     46: .
                     47: .Nm BUILDING
                     48: .Nd Procedure for building
                     49: .Nx
                     50: from source code.
                     51: .
                     52: .Sh STATUS
                     53: .
                     54: This document is a work-in-progress.  As such, the information described
                     55: here may not match the reality of the build system as of this writing.
                     56: Once this document is completely in sync with reality, this paragraph
                     57: will be removed.
                     58: .Pp
                     59: Discrepancies between this documentation and the current reality of
                     60: implementation are noted specially, as with the note below:
                     61: .Pp
                     62: .Em Note :
                     63: This document applies only to platforms which use the new toolchain as
                     64: indicated by the setting of
                     65: .Sy USE_NEW_TOOLCHAIN
                     66: in
                     67: .Sy /etc/mk.conf
                     68: or
                     69: .Aq bsd.own.mk .
                     70: Platforms which have not yet been switched to the new toolchain should
                     71: continue building traditionally, using the notes specified in the file
                     72: .Sy UPDATING .
                     73: .
                     74: .Sh REQUIREMENTS
                     75: .
                     76: .Nx
                     77: is designed to be buildable on most POSIX-compliant host systems.
                     78: The basic build procedure is the same whether compiling
                     79: .Em natively
                     80: (on the same
                     81: .Nx
                     82: architecture) or
                     83: .Em cross compiling
                     84: (on another architecture or OS).
                     85: .Pp
                     86: This source tree contains a special subtree,
                     87: .Dq tools ,
                     88: which uses the host system to create a build toolchain for the target
                     89: architecture.  The host system must have at least C and C++
                     90: compilers in order to create the toolchain
                     91: .Nm ( make
                     92: is not required); all other tools are created as part of the
                     93: .Nx
                     94: build process.
                     95: .Pp
                     96: .Bd -ragged -offset indent
                     97: .Em Note :
                     98: A couple host toolchain components are not yet available in the tools
                     99: directory.  Also, some tools use non-POSIX, non-ANSI C extensions
                    100: and need to be standardized.  As a result, cross-compiling from
                    101: systems other than
                    102: .Nx
                    103: is not currently supported.
                    104: .Ed
                    105: .
                    106: .Sh FILES
                    107: .
                    108: .Ss Source tree layout
                    109: .
                    110: .Bl -tag -width "BUILDING.mdoc"
                    111: .It Sy BUILDING.mdoc
1.2     ! tv        112: This document (in -mdoc troff format; the original copy).
        !           113: .It Sy BUILDING.html
        !           114: This document (in formatted HTML).
        !           115: .It Sy BUILDING.txt
        !           116: This document (in plaintext).
1.1       tv        117: .It Sy Makefile
                    118: The main Makefile for
                    119: .Nx ;
                    120: should only be run for native builds with an appropriately up-to-date
                    121: version of
                    122: .Nx
                    123: .Xr make 1 .
                    124: (For building from out-of-date systems or on a non-native host, see the
                    125: .Nm build.sh
                    126: shell script.)
                    127: .It Sy UPDATING
                    128: Special notes for updating from an earlier revision of
                    129: .Nx .
                    130: It is important to read this file before every build of an updated
                    131: source tree.
                    132: .It Sy build.sh
                    133: Bourne-compatible shell script used for building the host build tools
                    134: and the
                    135: .Nx
                    136: system from scratch.  Can be used for both native and cross builds, and
                    137: should be used instead of
                    138: .Xr make 1
                    139: for any source tree that is updated and recompiled regularly.
                    140: .It Sy crypto/dist/ , dist/ , gnu/dist/
                    141: Sources imported verbatim from third parties, without mangling the
                    142: existing build structure.  Other source trees in
                    143: .Sy bin
                    144: through
                    145: .Sy usr.sbin
                    146: use the
                    147: .Nx
                    148: .Xr make 1
                    149: .Dq reachover
                    150: Makefile semantics when building these programs for a native host.
                    151: .It Sy distrib/ , etc/
                    152: Sources for items used when making a full release snapshot, such as
                    153: files installed in
                    154: .Sy /etc
                    155: on the destination system, boot media, and release notes.
                    156: .It Sy regress/
                    157: Regression test harness.  Can be cross-compiled, but only run natively.
                    158: .It Sy sys/
                    159: .Nx
                    160: kernel sources.
                    161: .It Sy tools/
                    162: .Dq Reachover
                    163: build structure for the host build tools.  This has a special method of
                    164: determining out-of-date status.
                    165: .It Sy bin/ ... usr.sbin/
                    166: Sources to the
                    167: .Nx
                    168: userland (non-kernel) programs.  If any of these directories are
                    169: missing, they will be skipped during the build.
                    170: .El
                    171: .
                    172: .Ss Build tree layout
                    173: .
                    174: The
                    175: .Nx
                    176: build tree is described in
                    177: .Xr hier 7 ,
                    178: and the release layout is described in
                    179: .Xr release 7 .
                    180: .Pp
                    181: .
                    182: .Sh CONFIGURATION
                    183: .
                    184: .Ss "make" variables
                    185: .
                    186: .de YorN
                    187: Can be set to
                    188: .Dq yes
                    189: or
                    190: .Dq no .
                    191: ..
                    192: .de DFLT
                    193: .Pp
                    194: .Em Default :
                    195: ..
                    196: .de DFLTu
                    197: .DFLT
                    198: Unset.
                    199: ..
                    200: .de DFLTy
                    201: .DFLT
                    202: .Dq yes
                    203: ..
                    204: .de DFLTn
                    205: .DFLT
                    206: .Dq no
                    207: ..
                    208: Several variables control the behavior of
                    209: .Nx
                    210: builds.  Unless otherwise specified, these variables may be set in
                    211: either the process environment or the
                    212: .Xr make 1
                    213: configuration file specified by
                    214: .Sy MAKECONF .
                    215: .
                    216: .Bl -tag -width "MKCATPAGES"
                    217: .
                    218: .It Sy DESTDIR
                    219: Directory to contain the built
                    220: .Nx
                    221: system.  If set, special options are passed to the compilation tools to
                    222: prevent their default use of the host system's
                    223: .Sy /usr/include , /usr/lib ,
                    224: and so forth.  This pathname should
                    225: .Em not
                    226: end with a slash
                    227: .Pq /
                    228: character (for installation into the system's root directory, set
                    229: .Sy DESTDIR
                    230: to an empty string).
                    231: .DFLT
                    232: Empty string if
                    233: .Sy USETOOLS
                    234: is
                    235: .Dq yes ;
                    236: unset otherwise.
                    237: .
                    238: .It Sy MAKECONF
                    239: The name of the
                    240: .Xr make 1
                    241: configuration file.
                    242: .Em Only settable in the process environment.
                    243: .DFLT
                    244: .Dq /etc/mk.conf
                    245: .
                    246: .It Sy MKCATPAGES
                    247: .YorN
                    248: Indicates whether preformatted plaintext manual pages will be created
                    249: during a build.
                    250: .DFLTy
                    251: .
                    252: .It Sy MKCRYPTO
                    253: .YorN
                    254: Indicates whether cryptographic code will be included in a build;
                    255: provided for the benefit of countries that do not allow strong
                    256: cryptography.  Will not affect use of the standard low-security password
                    257: encryption system,
                    258: .Xr crypt 3 .
                    259: .DFLTy
                    260: .
                    261: .It Sy MKDOC
                    262: .YorN
                    263: Indicates whether system documentation destined for
                    264: .Sy /usr/share/doc
                    265: will be installed during a build.
                    266: .DFLTy
                    267: .
                    268: .It Sy MKINFO
                    269: .YorN
                    270: Indicates whether GNU Info files, used for the documentation for
                    271: most of the compilation tools, will be created and installed during a
                    272: build.
                    273: .DFLTy
                    274: .
                    275: .It Sy MKLINT
                    276: .YorN
                    277: Indicates whether
                    278: .Xr lint 1
                    279: will be run against portions of the
                    280: .Nx
                    281: source code during the build, and whether lint libraries will be
                    282: installed into
                    283: .Sy /usr/libdata/lint .
                    284: .DFLTy
                    285: .
                    286: .It Sy MKMAN
                    287: .YorN
                    288: Indicates whether manual pages will be installed during a build.
                    289: .DFLTy
                    290: .
                    291: .It Sy MKNLS
                    292: .YorN
                    293: Indicates whether Native Language System locale zone files will be
                    294: compiled and installed during a build.
                    295: .DFLTy
                    296: .
                    297: .It Sy MKOBJ
                    298: .YorN
                    299: Indicates whether object directories will be created when running
                    300: .Dq make obj .
                    301: If set to
                    302: .Dq no ,
                    303: then all built files will be located inside the regular source tree.
                    304: .DFLTy
                    305: .
                    306: .It Sy MKPIC
                    307: .YorN
                    308: Indicates whether shared objects and libraries will be created and
                    309: installed during a build.  If set to
                    310: .Dq no ,
                    311: the entire built system will be statically linked.
                    312: .DFLT
                    313: Platform dependent.  As of this writing, all platforms except
                    314: .Sy sh3
                    315: default to
                    316: .Dq yes .
                    317: .
                    318: .It Sy MKPICINSTALL
                    319: .YorN
                    320: Indicates whether the
                    321: .Xr ar 1
                    322: format libraries
                    323: .Sy ( lib*_pic.a ) ,
                    324: used to generate shared libraries, are installed during a build.
                    325: .DFLTy
                    326: .
                    327: .It Sy MKPROFILE
                    328: .YorN
                    329: Indicates whether profiled libraries
                    330: .Sy ( lib*_p.a )
                    331: will be built and installed during a build.
                    332: .DFLT
                    333: .Dq yes ;
                    334: however, some platforms turn off
                    335: .Sy MKPROFILE
                    336: by default at times due to toolchain problems with profiled code.
                    337: .
                    338: .It Sy MKSHARE
                    339: .YorN
                    340: Indicates whether files destined to reside in
                    341: .Sy /usr/share
                    342: will be built and installed during a build.  If set to
                    343: .Dq no ,
                    344: then all of
                    345: .Sy MKCATPAGES , MKDOC , MKINFO , MKMAN ,
                    346: and
                    347: .Sy MKNLS
                    348: will be set to
                    349: .Dq no
                    350: unconditionally.
                    351: .DFLTy
                    352: .
                    353: .It Sy TOOLDIR
                    354: Directory to hold the host tools, once built.  This directory should be
                    355: unique to a given host system and
                    356: .Nx
                    357: source tree.  (However, multiple targets may share the same
                    358: .Sy TOOLDIR ;
                    359: the target-dependent files have unique names.)  Must be set if USETOOLS
                    360: is
                    361: .Dq yes .
                    362: .DFLTu
                    363: .
                    364: .It Sy UPDATE
                    365: If set, then all install operations intended to write to
                    366: .Sy DESTDIR
                    367: will compare file timestamps before installing, and skip the install
                    368: phase if the destination files are up-to-date.  This also has
                    369: implications on full builds (see next subsection).
                    370: .DFLTu
                    371: .
                    372: .It Sy USETOOLS
                    373: Indicates whether the tools specified by
                    374: .Sy TOOLDIR
                    375: should be used as part of a build in progress.  Must be set to
                    376: .Dq yes
                    377: if cross-compiling.
                    378: .Bl -tag -width "never"
                    379: .It Sy yes
                    380: Use the tools from
                    381: .Sy TOOLDIR .
                    382: .It Sy no
                    383: Do not use the tools from
                    384: .Sy TOOLDIR ,
                    385: but refuse to build native compilation tool components that are
                    386: version-specific for that tool.
                    387: .It Sy never
                    388: Do not use the tools from
                    389: .Sy TOOLDIR ,
                    390: even when building native tool components.  This is similar to the
                    391: traditional
                    392: .Nx
                    393: build method, but does
                    394: .Em not
                    395: verify that the compilation tools in use are up-to-date enough in order
                    396: to build the tree successfully.  This may cause build or runtime
                    397: problems when building the whole
                    398: .Nx
                    399: source tree.
                    400: .El
                    401: .DFLT
                    402: .Dq yes
                    403: if building all or part of a whole
                    404: .Nx
                    405: source tree (detected automatically);
                    406: .Dq no
                    407: otherwise (to preserve traditional semantics of the
                    408: .Aq bsd.*.mk
                    409: .Xr make 1
                    410: include files).
                    411: .Pp
                    412: .Em Note :
                    413: Currently, the
                    414: .Dq no
                    415: option functions similarly to the
                    416: .Dq never
                    417: option.  Proper checks will be added in the near future to add the
                    418: described functionality for version-specific tool components.
                    419: .
                    420: .El
                    421: .
                    422: .Ss "make" variables for full builds
                    423: These variables only affect the top level
                    424: .Dq Makefile
                    425: and do not manually building subtrees of the
                    426: .Nx
                    427: source code.
                    428: .
                    429: .Bl -tag -width "NODISTRIBDIRS"
                    430: .
                    431: .It Sy MKOBJDIRS
                    432: .YorN
                    433: Indicates whether object directories will be created automatically
                    434: (via a
                    435: .Dq make obj
                    436: pass) at the start of a build.
                    437: .DFLTy
                    438: .
                    439: .It Sy MKTOOLS
                    440: Indicates whether the host tools will be built and installed
                    441: automatically if they are out-of-date.
                    442: .Bl -tag -width "never"
                    443: .It Sy yes
                    444: Build tools as needed into
                    445: .Sy TOOLDIR ,
                    446: but only if the tools in question are out-of-date.
                    447: .It Sy no
                    448: Do not update the tools in
                    449: .Sy TOOLDIR ;
                    450: halt the build as a safety precaution if tools are out-of-date.
                    451: .It Sy always
                    452: Always rebuild the tools in
                    453: .Sy TOOLDIR
                    454: from scratch during a build.  This is similar to the standard
                    455: .Nx
                    456: source tree build method, but is not typically required for host tools.
                    457: .El
                    458: .DFLTn
                    459: .
                    460: .It Sy NBUILDJOBS
                    461: If set, specifies the number of parallel
                    462: .Xr make 1
                    463: processes that should be run simultaneously.  This can speed up builds
                    464: on SMP machines, or machines with much more CPU power than I/O
                    465: availability.  This should be used
                    466: .Em instead
                    467: of the
                    468: .Xr make 1
                    469: option
                    470: .Sy -j ,
                    471: in order to ensure proper ordering of build components.
                    472: .DFLTu
                    473: .
                    474: .It Sy NOCLEANDIR
                    475: If set, avoids the
                    476: .Dq make cleandir
                    477: phase of a full build.  This has the effect of allowing only changed
                    478: files in a source tree to be recompiled.  This can speed up builds when
                    479: updating only a few files in the tree.
                    480: .DFLTu
                    481: .
                    482: .It Sy NODISTRIBDIRS
                    483: If set, avoids the
                    484: .Dq make distrib-dirs
                    485: phase of a full build.  This skips running
                    486: .Xr mtree 1
                    487: on
                    488: .Sy DESTDIR ,
                    489: useful on systems where building as an unprivileged user, or where it is
                    490: known that the system-wide mtree files have not changed.
                    491: .DFLTu
                    492: .
                    493: .It Sy NOINCLUDES
                    494: If set, avoids the
                    495: .Dq make includes
                    496: phase of a full build.  This has the effect of preventing
                    497: .Xr make 1
                    498: from thinking that some programs are out-of-date simply because the
                    499: system include files have changed.  However, this option should not be
                    500: used when updating the entire
                    501: .Nx
                    502: source tree arbitrarily; it is suggested to use
                    503: .Sy UPDATE
                    504: in that case.
                    505: .DFLTu
                    506: .
                    507: .It Sy RELEASEDIR
                    508: If set, specifies the directory to which a
                    509: .Xr release 7
                    510: layout will be written at the end of a
                    511: .Dq make release .
                    512: .DFLTu
                    513: .
                    514: .It Sy UPDATE
                    515: If set, then in addition to the effects described for UPDATE above, this
                    516: implies the effects of
                    517: .Sy NOCLEANDIR .
                    518: .
                    519: .El
                    520: .
                    521: .Sh BUILDING
                    522: .
                    523: .Ss "make" command line options
                    524: This is only a summary of options available to
                    525: .Xr make 1 ;
                    526: only the options used most frequently with
                    527: .Nx
                    528: builds are listed here.
                    529: .
                    530: .Bl -tag -width "var=value"
                    531: .
                    532: .It Sy -m Em dir
                    533: Specify the default directory for searching for system Makefile
                    534: segments, mainly the
                    535: .Aq bsd.*.mk
                    536: files.  When building any full
                    537: .Nx
                    538: source tree, this should be set to the
                    539: .Dq share/mk
                    540: directory in the source tree.  (This is set automatically when building
                    541: from the top level.)
                    542: .
                    543: .It Sy -n
                    544: Display the commands that would have been executed, but do not
                    545: actually execute them.  This will still cause recursion to take place.
                    546: .
                    547: .It Sy -v Em var
                    548: Print
                    549: .Xr make 1 's
                    550: idea of the value of
                    551: .Em var .
                    552: Does not build any targets.
                    553: .
                    554: .It Em var=value
                    555: Set the variable
                    556: .Em var
                    557: to
                    558: .Em value ,
                    559: overriding any setting specified by the process environment, the
                    560: .Sy MAKECONF
                    561: configuration file, or the system Makefile segments.
                    562: .
                    563: .El
                    564: .
                    565: .Ss "make" targets
                    566: .
                    567: These default targets may be built by running
                    568: .Xr make 1
                    569: in any subtree of the
                    570: .Nx
                    571: source code.  It is recommended that none of these be used from the top
                    572: level Makefile; as a specific exception,
                    573: .Dq make obj
                    574: and
                    575: .Dq make cleandir
                    576: are useful in that context.
                    577: .
                    578: .Bl -tag -width "dependall"
                    579: .
                    580: .It Sy all
                    581: Build programs, libraries, and preformatted documentation.
                    582: .
                    583: .It Sy clean
                    584: Remove program and library object code files.
                    585: .
                    586: .It Sy cleandir
                    587: Same as
                    588: .Sy clean ,
                    589: but also remove preformatted documentation, dependency files generated
                    590: by
                    591: .Dq make depend ,
                    592: and any other files known to be created at build time.
                    593: .Dq make distclean
                    594: may be used as a synonym, for familiarity with a similar well-known
                    595: convention.
                    596: .
                    597: .It Sy depend
                    598: Create dependency files
                    599: .Sy ( .depend )
                    600: containing more detailed information about the dependencies of source
                    601: code on header files.  Allows programs to be recompiled automatically
                    602: when a dependency changes.
                    603: .
                    604: .It Sy dependall
                    605: Does a
                    606: .Dq make depend
                    607: immediately followed by a
                    608: .Dq make all .
                    609: This combined target recurses as an atomic unit, so that the
                    610: .Dq make depend
                    611: phase can participate in
                    612: .Sy make -j
                    613: parallelism.
                    614: .
                    615: .It Sy includes
                    616: Build and install system header files.  Typically needed before any
                    617: system libraries or programs can be built.
                    618: .
                    619: .It Sy install
                    620: Install programs, libraries, and documentation into
                    621: .Sy DESTDIR .
                    622: .
                    623: .It Sy lint
                    624: Run
                    625: .Xr lint 1
                    626: against the C source code, where appropriate, and generate
                    627: system-installed lint libraries.
                    628: .
                    629: .It Sy obj
                    630: Create object directories to be used for built files, instead of
                    631: building directly in the source tree.
                    632: .
                    633: .It Sy tags
                    634: Create
                    635: .Xr ctags 1
                    636: searchable function lists usable by the
                    637: .Xr ex 1
                    638: and
                    639: .Xr vi 1
                    640: text editors.
                    641: .
                    642: .El
                    643: .
                    644: .Ss "make" targets for the top level
                    645: .
                    646: Additional
                    647: .Xr make 1
                    648: targets are usable specifically from the top source level to facilitate
                    649: building the entire
                    650: .Nx
                    651: source tree.
                    652: .
                    653: .Bl -tag -width "dependall"
                    654: .
                    655: .It Sy build
                    656: Build the entire
                    657: .Nx
                    658: system.  This orders portions of the source tree such that prerequisites
                    659: will be built in the proper order.
                    660: .
                    661: .It Sy release
                    662: Do a
                    663: .Dq make build ,
                    664: then package the system into a standard release layout as described by
                    665: .Xr release 7 .
                    666: This requires that
                    667: .Sy RELEASEDIR
                    668: be set (see above).
                    669: .
                    670: .It Sy regression-tests
                    671: Can only be run after building the regression tests in the directory
                    672: .Dq regress .
                    673: Runs the compiled regression tests on the local host.
                    674: .
                    675: .El
                    676: .
                    677: .Ss The "build.sh" script
                    678: .
                    679: This script file is a Bourne shell script designed to build the
                    680: entire
                    681: .Nx
                    682: system on any host with a Bourne shell in
                    683: .Sy /bin/sh ,
                    684: including many that are not POSIX compliant.  Note that if a host
                    685: system's
                    686: .Sy /bin/sh
                    687: is unusually old and broken, the Korn Shell
                    688: .Sy ( /bin/ksh ) ,
                    689: if available, may be a usable alternative.
                    690: .Pp
                    691: All cross-compile builds, and most native builds, of the entire system
                    692: should make use of
                    693: .Sy build.sh
                    694: rather than just running
                    695: .Dq make .
                    696: This way, the
                    697: .Xr make 1
                    698: program will be bootstrapped properly, in case the host system has an
                    699: older or incompatible
                    700: .Dq make
                    701: program.
                    702: .Pp
                    703: When compiling the entire system via
                    704: .Sy build.sh ,
                    705: many
                    706: .Xr make 1
                    707: variables are set for you in order to help encapsulate the build
                    708: process.  In particular, both
                    709: .Sy USETOOLS
                    710: and
                    711: .Sy MKTOOLS
                    712: are set to
                    713: .Dq yes ,
                    714: and
                    715: .Sy MACHINE_ARCH
                    716: (if unset) is deduced from the value of
                    717: .Sy MACHINE .
                    718: .Pp
                    719: The variables
                    720: .Sy DESTDIR , MACHINE , MACHINE_ARCH ,
                    721: and
                    722: .Sy TOOLDIR
                    723: are required in order for
                    724: .Sy build.sh
                    725: to function, and thus they cannot be set in the configuration file
                    726: specified by
                    727: .Sy MAKECONF .
                    728: They may be set either in the process environment, or via command line
                    729: options to
                    730: .Sy build.sh .
                    731: .Pp
                    732: The following are available command line options that may be supplied to
                    733: .Sy build.sh :
                    734: .
                    735: .Bl -tag -width "-T tools"
                    736: .
                    737: .It Sy -a Em arch
                    738: Set the value of
                    739: .Sy MACHINE_ARCH
                    740: to
                    741: .Em arch .
                    742: .
                    743: .It Sy -D Em dest
                    744: Set the value of
                    745: .Sy DESTDIR
                    746: to
                    747: .Em dest .
                    748: .
                    749: .It Sy -j Em njob
                    750: Set the value of
                    751: .Sy NBUILDJOBS
                    752: to
                    753: .Em njob .
                    754: This provides similar functionality to the familiar
                    755: .Dq make -j ,
                    756: but preserves the ordering of the top level
                    757: .Dq make build .
                    758: .
                    759: .It Sy -m Em mach
                    760: Set the value of
                    761: .Sy MACHINE
                    762: to
                    763: .Em mach .
                    764: This will also override any value of
                    765: .Sy MACHINE_ARCH
                    766: in the process environment with a value deduced from
                    767: .Em mach ,
                    768: unless
                    769: .Sy -a
                    770: is specified.
                    771: .
                    772: .It Sy -R Em rel
                    773: Set the value of
                    774: .Sy RELEASEDIR
                    775: to
                    776: .Em rel .
                    777: Setting this option will make
                    778: .Sy build.sh
                    779: run
                    780: .Dq make release
                    781: instead of
                    782: .Dq make build .
                    783: .
                    784: .It Sy -r
                    785: Remove the contents of
                    786: .Sy DESTDIR
                    787: and
                    788: .Sy TOOLDIR
                    789: before building (provides a clean starting point).
                    790: .
                    791: .It Sy -T Em tools
                    792: Set the value of
                    793: .Sy TOOLDIR
                    794: to
                    795: .Em tools .
                    796: .
                    797: .El
                    798: .
                    799: .Sh The "nbmake-MACHINE" wrapper script
                    800: .
                    801: If using the
                    802: .Sy build.sh
                    803: script to build
                    804: .Nx ,
                    805: a
                    806: .Sy nbmake-MACHINE
                    807: script will be created in
                    808: .Sy TOOLDIR/bin
                    809: upon the first build to assist in building subtrees on a cross-compile
                    810: host.
                    811: .Pp
                    812: .Sy nbmake-MACHINE
                    813: can be invoked in lieu of
                    814: .Xr make 1 ,
                    815: and will instead call the up-to-date version of
                    816: .Dq nbmake
                    817: installed into
                    818: .Sy TOOLDIR/bin
                    819: with several key variables pre-set, including
                    820: .Sy MACHINE , MACHINE_ARCH ,
                    821: and
                    822: .Sy TOOLDIR .
                    823: This script can be symlinked into a directory listed in
                    824: .Sy PATH ,
                    825: or called with an absolute path.
                    826: .
                    827: .Sh SEE ALSO
                    828: .Xr make 1 ,
                    829: .Xr hier 7 ,
                    830: .Xr release 7
                    831: .
                    832: .Sh BUGS
                    833: .
                    834: Many platforms are not yet using the
                    835: .Sy USE_NEW_TOOLCHAIN
                    836: system.
                    837: .
                    838: .Sh HISTORY
                    839: .
                    840: The
                    841: .Sy USE_NEW_TOOLCHAIN
                    842: based build scheme was introduced in the
                    843: .Dq NetBSD-current
                    844: development sources between
                    845: .Nx 1.5
                    846: and
                    847: .Nx 1.6.

CVSweb <webmaster@jp.NetBSD.org>