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

Annotation of src/doc/BUILDING.mdoc, Revision 1.4

1.4     ! lukem       1: .\"    $NetBSD: BUILDING.mdoc,v 1.3 2002/11/25 19:18:45 wiz Exp $
1.1       lukem       2: .\"
                      3: .\" Copyright (c) 2001, 2002 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: .\"
                     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.4     ! lukem      41: .Dd December 8, 2002
1.1       lukem      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 default setting of
                     65: .Sy TOOLCHAIN_MISSING
                     66: in
                     67: .Aq bsd.own.mk .
                     68: Platforms which have not yet been switched to the new toolchain should
                     69: continue building traditionally, using the notes specified in the file
                     70: .Sy UPDATING .
                     71: .
                     72: .Sh REQUIREMENTS
                     73: .
                     74: .Nx
                     75: is designed to be buildable on most POSIX-compliant host systems.
                     76: The basic build procedure is the same whether compiling
                     77: .Em natively
                     78: (on the same
                     79: .Nx
                     80: architecture) or
                     81: .Em cross compiling
                     82: (on another architecture or OS).
                     83: .Pp
                     84: This source tree contains a special subtree,
                     85: .Dq tools ,
                     86: which uses the host system to create a build toolchain for the target
                     87: architecture.  The host system must have at least C and C++
                     88: compilers in order to create the toolchain
                     89: .Nm ( make
                     90: is not required); all other tools are created as part of the
                     91: .Nx
                     92: build process.
                     93: .Pp
                     94: .Bd -ragged -offset indent
                     95: .Em Note :
                     96: A couple host toolchain components are not yet available in the tools
                     97: directory.  Also, some tools use non-POSIX, non-ANSI C extensions
                     98: and need to be standardized.  As a result, cross-compiling from
                     99: systems other than
                    100: .Nx
                    101: is not currently supported.
                    102: .Ed
                    103: .
                    104: .Sh FILES
                    105: .
                    106: .Ss Source tree layout
                    107: .
                    108: .Bl -tag -width "BUILDING.mdoc"
1.3       wiz       109: .It Sy doc/BUILDING.mdoc
1.1       lukem     110: This document (in -mdoc troff format; the original copy).
                    111: .It Sy BUILDING
                    112: This document (in plaintext).
                    113: .It Sy Makefile
                    114: The main Makefile for
                    115: .Nx ;
                    116: should only be run for native builds with an appropriately up-to-date
                    117: version of
                    118: .Nx
                    119: .Xr make 1 .
                    120: (For building from out-of-date systems or on a non-native host, see the
                    121: .Nm build.sh
                    122: shell script.)
                    123: .It Sy UPDATING
                    124: Special notes for updating from an earlier revision of
                    125: .Nx .
                    126: It is important to read this file before every build of an updated
                    127: source tree.
                    128: .It Sy build.sh
                    129: Bourne-compatible shell script used for building the host build tools
                    130: and the
                    131: .Nx
                    132: system from scratch.  Can be used for both native and cross builds, and
                    133: should be used instead of
                    134: .Xr make 1
                    135: for any source tree that is updated and recompiled regularly.
                    136: .It Sy crypto/dist/ , dist/ , gnu/dist/
                    137: Sources imported verbatim from third parties, without mangling the
                    138: existing build structure.  Other source trees in
                    139: .Sy bin
                    140: through
                    141: .Sy usr.sbin
                    142: use the
                    143: .Nx
                    144: .Xr make 1
                    145: .Dq reachover
                    146: Makefile semantics when building these programs for a native host.
                    147: .It Sy distrib/ , etc/
                    148: Sources for items used when making a full release snapshot, such as
                    149: files installed in
                    150: .Sy /etc
                    151: on the destination system, boot media, and release notes.
                    152: .It Sy regress/
                    153: Regression test harness.  Can be cross-compiled, but only run natively.
                    154: .It Sy sys/
                    155: .Nx
                    156: kernel sources.
                    157: .It Sy tools/
                    158: .Dq Reachover
                    159: build structure for the host build tools.  This has a special method of
                    160: determining out-of-date status.
                    161: .It Sy bin/ ... usr.sbin/
                    162: Sources to the
                    163: .Nx
                    164: userland (non-kernel) programs.  If any of these directories are
                    165: missing, they will be skipped during the build.
                    166: .El
                    167: .
                    168: .Ss Build tree layout
                    169: .
                    170: The
                    171: .Nx
                    172: build tree is described in
                    173: .Xr hier 7 ,
                    174: and the release layout is described in
                    175: .Xr release 7 .
                    176: .Pp
                    177: .
                    178: .Sh CONFIGURATION
                    179: .
                    180: .Ss Environment variables
                    181: ..
                    182: Several environment variables control the behaviour of
                    183: .Nx
                    184: builds.
                    185: .
                    186: .Bl -tag -width "MAKEOBJDIRPREFIX"
                    187: .
                    188: .It Sy MACHINE
                    189: Machine type.
                    190: .
                    191: .It Sy MACHINE_ARCH
                    192: Machine architecture.
                    193: .
                    194: .It Sy MAKE
                    195: Path name to invoke
                    196: .Xr make 1
                    197: as.
                    198: .
                    199: .It Sy MAKEFLAGS
                    200: Flags to invoke
                    201: .Xr make 1
                    202: with.
                    203: .
                    204: .It Sy MAKEOBJDIR
                    205: Directory to use as the
                    206: .Sy .OBJDIR
                    207: for the current directory.
                    208: Used only if
                    209: .Sy MAKEOBJDIRPREFIX
                    210: is not defined.
                    211: .Sy MAKEOBJDIR
                    212: can only be provided in the environment.
                    213: .
                    214: .It Sy MAKEOBJDIRPREFIX
                    215: Top level directory of the object directory tree.
                    216: If this is defined,
                    217: ${MAKEOBJDIRPREFIX}/${.CURDIR}
                    218: is used as the
                    219: .Sy .OBJDIR
                    220: for the current directory.
                    221: The current directory may be read only.
                    222: .Sy MAKEOBJDIRPREFIX
                    223: can only be provided in the environment.
                    224: .
                    225: .El
                    226: .
                    227: .Ss \*qmake\*q variables
                    228: .
                    229: .de YorN
                    230: Can be set to
                    231: .Dq yes
                    232: or
                    233: .Dq no .
                    234: ..
                    235: .de DFLT
                    236: .Pp
                    237: .Em Default :
                    238: ..
                    239: .de DFLTu
                    240: .DFLT
                    241: Unset.
                    242: ..
                    243: .de DFLTy
                    244: .DFLT
                    245: .Dq yes
                    246: ..
                    247: .de DFLTn
                    248: .DFLT
                    249: .Dq no
                    250: ..
                    251: Several variables control the behavior of
                    252: .Nx
                    253: builds.  Unless otherwise specified, these variables may be set in
                    254: either the process environment or the
                    255: .Xr make 1
                    256: configuration file specified by
                    257: .Sy MAKECONF .
                    258: .
                    259: .Bl -tag -width "MKCATPAGES"
                    260: .
                    261: .It Sy BUILDID
                    262: Identifier for the build.  The identifier will be appended to
                    263: object directory names, and can be consulted in the
                    264: .Xr make 1
                    265: configuration file in order to set additional build parameters,
                    266: such as compiler flags.
                    267: .
                    268: .It Sy DESTDIR
                    269: Directory to contain the built
                    270: .Nx
                    271: system.  If set, special options are passed to the compilation tools to
                    272: prevent their default use of the host system's
                    273: .Sy /usr/include , /usr/lib ,
                    274: and so forth.  This pathname should
                    275: .Em not
                    276: end with a slash
                    277: .Pq /
                    278: character (for installation into the system's root directory, set
                    279: .Sy DESTDIR
                    280: to an empty string).
                    281: The directory must reside on a file system which supports long file
                    282: names and hard links.
                    283: .DFLT
                    284: Empty string if
                    285: .Sy USETOOLS
                    286: is
                    287: .Dq yes ;
                    288: unset otherwise.
                    289: .
                    290: .It Sy MAKECONF
                    291: The name of the
                    292: .Xr make 1
                    293: configuration file.
                    294: .Em Only settable in the process environment.
                    295: .DFLT
                    296: .Dq /etc/mk.conf
                    297: .
                    298: .It Sy MKCATPAGES
                    299: .YorN
                    300: Indicates whether preformatted plaintext manual pages will be created
                    301: during a build.
                    302: .DFLTy
                    303: .
                    304: .It Sy MKCRYPTO
                    305: .YorN
                    306: Indicates whether cryptographic code will be included in a build;
                    307: provided for the benefit of countries that do not allow strong
                    308: cryptography.  Will not affect use of the standard low-security password
                    309: encryption system,
                    310: .Xr crypt 3 .
                    311: .DFLTy
                    312: .
                    313: .It Sy MKDOC
                    314: .YorN
                    315: Indicates whether system documentation destined for
                    316: .Sy /usr/share/doc
                    317: will be installed during a build.
                    318: .DFLTy
                    319: .
                    320: .It Sy MKHOSTOBJ
                    321: .YorN
                    322: If set to
                    323: .Dq yes ,
                    324: then for programs intended to be run on the compile host,
                    325: the name, release, and architecture of the host operating system
                    326: will be suffixed to the name of the object directory created by
                    327: .Dq make obj .
                    328: (This allows multiple host systems to compile NetBSD for a single target.)
                    329: If set to
                    330: .Dq no ,
                    331: then programs built to be run on the compile host will use the same
                    332: object directory names as programs built to be run on the target.
                    333: .DFLTn
                    334: .
                    335: .It Sy MKINFO
                    336: .YorN
                    337: Indicates whether GNU Info files, used for the documentation for
                    338: most of the compilation tools, will be created and installed during a
                    339: build.
                    340: .DFLTy
                    341: .
                    342: .It Sy MKLINT
                    343: .YorN
                    344: Indicates whether
                    345: .Xr lint 1
                    346: will be run against portions of the
                    347: .Nx
                    348: source code during the build, and whether lint libraries will be
                    349: installed into
                    350: .Sy /usr/libdata/lint .
                    351: .DFLTy
                    352: .
                    353: .It Sy MKMAN
                    354: .YorN
                    355: Indicates whether manual pages will be installed during a build.
                    356: .DFLTy
                    357: .
                    358: .It Sy MKNLS
                    359: .YorN
                    360: Indicates whether Native Language System locale zone files will be
                    361: compiled and installed during a build.
                    362: .DFLTy
                    363: .
                    364: .It Sy MKOBJ
                    365: .YorN
                    366: Indicates whether object directories will be created when running
                    367: .Dq make obj .
                    368: If set to
                    369: .Dq no ,
                    370: then all built files will be located inside the regular source tree.
                    371: .DFLTy
                    372: .
                    373: .It Sy MKPIC
                    374: .YorN
                    375: Indicates whether shared objects and libraries will be created and
                    376: installed during a build.  If set to
                    377: .Dq no ,
                    378: the entire built system will be statically linked.
                    379: .DFLT
                    380: Platform dependent.  As of this writing, all platforms except
                    381: .Sy sh3
                    382: default to
                    383: .Dq yes .
                    384: .
                    385: .It Sy MKPICINSTALL
                    386: .YorN
                    387: Indicates whether the
                    388: .Xr ar 1
                    389: format libraries
                    390: .Sy ( lib*_pic.a ) ,
                    391: used to generate shared libraries, are installed during a build.
                    392: .DFLTy
                    393: .
                    394: .It Sy MKPROFILE
                    395: .YorN
                    396: Indicates whether profiled libraries
                    397: .Sy ( lib*_p.a )
                    398: will be built and installed during a build.
                    399: .DFLT
                    400: .Dq yes ;
                    401: however, some platforms turn off
                    402: .Sy MKPROFILE
                    403: by default at times due to toolchain problems with profiled code.
                    404: .
                    405: .It Sy MKSHARE
                    406: .YorN
                    407: Indicates whether files destined to reside in
                    408: .Sy /usr/share
                    409: will be built and installed during a build.  If set to
                    410: .Dq no ,
                    411: then all of
                    412: .Sy MKCATPAGES , MKDOC , MKINFO , MKMAN ,
                    413: and
                    414: .Sy MKNLS
                    415: will be set to
                    416: .Dq no
                    417: unconditionally.
                    418: .DFLTy
                    419: .
                    420: .It Sy TOOLDIR
                    421: Directory to hold the host tools, once built.  This directory should be
                    422: unique to a given host system and
                    423: .Nx
                    424: source tree.  (However, multiple targets may share the same
                    425: .Sy TOOLDIR ;
                    426: the target-dependent files have unique names.)  If unset, a default based
                    427: on the
                    428: .Xr uname 1
                    429: information of the host platform will be created in the
                    430: .Sy .OBJDIR
                    431: of
                    432: .Sy src/tools .
                    433: .DFLTu
                    434: .
                    435: .It Sy UNPRIVED
                    436: If set, then an unprivileged install will occur.
                    437: The user, group, permissions, and file flags, will not be set on
                    438: the installed item; instead the information will be appended to
                    439: a file called
                    440: .Pa METALOG
                    441: in
                    442: .Sy DESTDIR .
                    443: The contents of
                    444: .Pa METALOG
                    445: is used during the generation of the distribution tar files to ensure
                    446: that the appropriate file ownership is stored.
                    447: .DFLTu
                    448: .
                    449: .It Sy UPDATE
                    450: If set, then all install operations intended to write to
                    451: .Sy DESTDIR
                    452: will compare file timestamps before installing, and skip the install
                    453: phase if the destination files are up-to-date.  This also has
                    454: implications on full builds (see next subsection).
                    455: .DFLTu
                    456: .
                    457: .It Sy USETOOLS
                    458: Indicates whether the tools specified by
                    459: .Sy TOOLDIR
                    460: should be used as part of a build in progress.  Must be set to
                    461: .Dq yes
                    462: if cross-compiling.
                    463: .Bl -tag -width "never"
                    464: .It Sy yes
                    465: Use the tools from
                    466: .Sy TOOLDIR .
                    467: .It Sy no
                    468: Do not use the tools from
                    469: .Sy TOOLDIR ,
                    470: but refuse to build native compilation tool components that are
                    471: version-specific for that tool.
                    472: .It Sy never
                    473: Do not use the tools from
                    474: .Sy TOOLDIR ,
                    475: even when building native tool components.  This is similar to the
                    476: traditional
                    477: .Nx
                    478: build method, but does
                    479: .Em not
                    480: verify that the compilation tools in use are up-to-date enough in order
                    481: to build the tree successfully.  This may cause build or runtime
                    482: problems when building the whole
                    483: .Nx
                    484: source tree.
                    485: .El
                    486: .DFLT
                    487: .Dq yes
                    488: if building all or part of a whole
                    489: .Nx
                    490: source tree (detected automatically);
                    491: .Dq no
                    492: otherwise (to preserve traditional semantics of the
                    493: .Aq bsd.*.mk
                    494: .Xr make 1
                    495: include files).
                    496: .
                    497: .El
                    498: .
                    499: .Ss \*qmake\*q variables for full builds
                    500: These variables only affect the top level
                    501: .Dq Makefile
                    502: and do not affect manually building subtrees of the
                    503: .Nx
                    504: source code.
                    505: .
                    506: .Bl -tag -width "NODISTRIBDIRS"
                    507: .
                    508: .It Sy MKOBJDIRS
                    509: .YorN
                    510: Indicates whether object directories will be created automatically
                    511: (via a
                    512: .Dq make obj
                    513: pass) at the start of a build.
                    514: .DFLTy
                    515: .
                    516: .It Sy NBUILDJOBS
                    517: Now obsolete.  Use the
                    518: .Xr make 1
                    519: option
1.4     ! lukem     520: .Fl j ,
1.1       lukem     521: instead (see below)
                    522: .DFLTu
                    523: .
                    524: .It Sy NOCLEANDIR
                    525: If set, avoids the
                    526: .Dq make cleandir
                    527: phase of a full build.  This has the effect of allowing only changed
                    528: files in a source tree to be recompiled.  This can speed up builds when
                    529: updating only a few files in the tree.
                    530: .DFLTu
                    531: .
                    532: .It Sy NODISTRIBDIRS
                    533: If set, avoids the
                    534: .Dq make distrib-dirs
                    535: phase of a full build.  This skips running
                    536: .Xr mtree 8
                    537: on
                    538: .Sy DESTDIR ,
                    539: useful on systems where building as an unprivileged user, or where it is
                    540: known that the system-wide mtree files have not changed.
                    541: .DFLTu
                    542: .
                    543: .It Sy NOINCLUDES
                    544: If set, avoids the
                    545: .Dq make includes
                    546: phase of a full build.  This has the effect of preventing
                    547: .Xr make 1
                    548: from thinking that some programs are out-of-date simply because the
                    549: system include files have changed.  However, this option should not be
                    550: used when updating the entire
                    551: .Nx
                    552: source tree arbitrarily; it is suggested to use
                    553: .Sy UPDATE
                    554: in that case.
                    555: .DFLTu
                    556: .
                    557: .It Sy RELEASEDIR
                    558: If set, specifies the directory to which a
                    559: .Xr release 7
                    560: layout will be written at the end of a
                    561: .Dq make release .
                    562: .DFLTu
                    563: .
                    564: .It Sy UPDATE
                    565: If set, then in addition to the effects described for UPDATE above, this
                    566: implies the effects of
                    567: .Sy NOCLEANDIR .
                    568: .
                    569: .El
                    570: .
                    571: .Sh BUILDING
                    572: .
                    573: .Ss \*qmake\*q command line options
                    574: This is only a summary of options available to
                    575: .Xr make 1 ;
                    576: only the options used most frequently with
                    577: .Nx
                    578: builds are listed here.
                    579: .
                    580: .Bl -tag -width "var=value"
                    581: .
1.4     ! lukem     582: .It Fl j Ar njob
1.1       lukem     583: Run up to
1.4     ! lukem     584: .Ar njob
1.1       lukem     585: .Xr make 1
                    586: subjobs in parallel.
                    587: Makefiles should use .WAIT or have explicit dependancies
                    588: as necessary to enforce build ordering.
                    589: If you see build failures with -j, please save complete build logs
                    590: so the failures can be analyzed.
                    591: .
1.4     ! lukem     592: .It Fl m Ar dir
1.1       lukem     593: Specify the default directory for searching for system Makefile
                    594: segments, mainly the
                    595: .Aq bsd.*.mk
                    596: files.  When building any full
                    597: .Nx
                    598: source tree, this should be set to the
                    599: .Dq share/mk
                    600: directory in the source tree.  (This is set automatically when building
                    601: from the top level.)
                    602: .
1.4     ! lukem     603: .It Fl n
1.1       lukem     604: Display the commands that would have been executed, but do not
                    605: actually execute them.  This will still cause recursion to take place.
                    606: .
1.4     ! lukem     607: .It Fl v Ar var
1.1       lukem     608: Print
                    609: .Xr make 1 Ns 's
                    610: idea of the value of
1.4     ! lukem     611: .Ar var .
1.1       lukem     612: Does not build any targets.
                    613: .
                    614: .It Em var=value
                    615: Set the variable
                    616: .Em var
                    617: to
                    618: .Em value ,
                    619: overriding any setting specified by the process environment, the
                    620: .Sy MAKECONF
                    621: configuration file, or the system Makefile segments.
                    622: .
                    623: .El
                    624: .
                    625: .Ss \*qmake\*q targets
                    626: .
                    627: These default targets may be built by running
                    628: .Xr make 1
                    629: in any subtree of the
                    630: .Nx
                    631: source code.  It is recommended that none of these be used from the top
                    632: level Makefile; as a specific exception,
                    633: .Dq make obj
                    634: and
                    635: .Dq make cleandir
                    636: are useful in that context.
                    637: .
                    638: .Bl -tag -width "dependall"
                    639: .
                    640: .It Sy all
                    641: Build programs, libraries, and preformatted documentation.
                    642: .
                    643: .It Sy clean
                    644: Remove program and library object code files.
                    645: .
                    646: .It Sy cleandir
                    647: Same as
                    648: .Sy clean ,
                    649: but also remove preformatted documentation, dependency files generated
                    650: by
                    651: .Dq make depend ,
                    652: and any other files known to be created at build time.
                    653: .Dq make distclean
                    654: may be used as a synonym, for familiarity with a similar well-known
                    655: convention.
                    656: .
                    657: .It Sy depend
                    658: Create dependency files
                    659: .Sy ( .depend )
                    660: containing more detailed information about the dependencies of source
                    661: code on header files.  Allows programs to be recompiled automatically
                    662: when a dependency changes.
                    663: .
                    664: .It Sy dependall
                    665: Does a
                    666: .Dq make depend
                    667: immediately followed by a
                    668: .Dq make all .
                    669: This improves cache locality of the build since both passes read the source
                    670: files in their entirety.
                    671: .
                    672: .It Sy includes
                    673: Build and install system header files.  Typically needed before any
                    674: system libraries or programs can be built.
                    675: .
                    676: .It Sy install
                    677: Install programs, libraries, and documentation into
                    678: .Sy DESTDIR .
                    679: Few files will be installed to
                    680: .Pa /dev ,
                    681: .Pa /etc ,
                    682: .Pa /root
                    683: or
                    684: .Pa /var
                    685: in order to prevent user supplied configuration data from being overwritten.
                    686: .It Sy lint
                    687: Run
                    688: .Xr lint 1
                    689: against the C source code, where appropriate, and generate
                    690: system-installed lint libraries.
                    691: .
                    692: .It Sy obj
                    693: Create object directories to be used for built files, instead of
                    694: building directly in the source tree.
                    695: .
                    696: .It Sy tags
                    697: Create
                    698: .Xr ctags 1
                    699: searchable function lists usable by the
                    700: .Xr ex 1
                    701: and
                    702: .Xr vi 1
                    703: text editors.
                    704: .
                    705: .El
                    706: .
                    707: .Ss \*qmake\*q targets for the top level
                    708: .
                    709: Additional
                    710: .Xr make 1
                    711: targets are usable specifically from the top source level to facilitate
                    712: building the entire
                    713: .Nx
                    714: source tree.
                    715: .
                    716: .Bl -tag -width "dependall"
                    717: .
                    718: .It Sy build
                    719: Build the entire
                    720: .Nx
                    721: system.  This orders portions of the source tree such that prerequisites
                    722: will be built in the proper order.
                    723: .
                    724: .It Sy release
                    725: Do a
                    726: .Dq make build ,
                    727: then package the system into a standard release layout as described by
                    728: .Xr release 7 .
                    729: This requires that
                    730: .Sy RELEASEDIR
                    731: be set (see above).
                    732: .
                    733: .It Sy regression-tests
                    734: Can only be run after building the regression tests in the directory
                    735: .Dq regress .
                    736: Runs the compiled regression tests on the local host.
                    737: .
                    738: .El
                    739: .
                    740: .Ss The \*qbuild.sh\*q script
                    741: .
                    742: This script file is a Bourne shell script designed to build the
                    743: entire
                    744: .Nx
                    745: system on any host with a Bourne shell in
                    746: .Sy /bin/sh ,
                    747: including many that are not POSIX compliant.  Note that if a host
                    748: system's
                    749: .Sy /bin/sh
                    750: is unusually old and broken, the Korn Shell
                    751: .Sy ( /bin/ksh ) ,
                    752: if available, may be a usable alternative.
                    753: .Pp
                    754: All cross-compile builds, and most native builds, of the entire system
                    755: should make use of
                    756: .Sy build.sh
                    757: rather than just running
                    758: .Dq make .
                    759: This way, the
                    760: .Xr make 1
                    761: program will be bootstrapped properly, in case the host system has an
                    762: older or incompatible
                    763: .Dq make
                    764: program.
                    765: .Pp
                    766: When compiling the entire system via
                    767: .Sy build.sh ,
                    768: many
                    769: .Xr make 1
                    770: variables are set for you in order to help encapsulate the build
                    771: process.  In the list of options below, variables that are automatically
                    772: set by
                    773: .Sy build.sh
                    774: are noted where applicable.
                    775: .Pp
                    776: The following are available command line options that may be supplied to
                    777: .Sy build.sh :
                    778: .
                    779: .Bl -tag -width "-T tools"
                    780: .
1.4     ! lukem     781: .It Fl a Ar arch
1.1       lukem     782: Set the value of
                    783: .Sy MACHINE_ARCH
                    784: to
1.4     ! lukem     785: .Ar arch .
1.1       lukem     786: .
1.4     ! lukem     787: .It Fl B Ar buildid
1.1       lukem     788: Set the value of
                    789: .Sy BUILDID
                    790: to
1.4     ! lukem     791: .Ar buildid .
1.1       lukem     792: This will also append the build idenfitier to the name of the
                    793: .Dq make
                    794: wrapper script so that the resulting name is of the form
                    795: .Dq Sy nbmake-MACHINE-BUILDID .
                    796: .
1.4     ! lukem     797: .It Fl b
1.1       lukem     798: Bootstrap
                    799: .Dq make
                    800: and create a
                    801: .Sy nbmake-MACHINE
                    802: script (see below).
                    803: .
1.4     ! lukem     804: .It Fl D Ar dest
        !           805: Set the value of
        !           806: .Sy DESTDIR
        !           807: to
        !           808: .Ar dest .
        !           809: .
        !           810: .It Fl d
1.1       lukem     811: Build a full distribution.
                    812: This differs from a default build in that files will also be installed to
                    813: .Pa /dev ,
                    814: .Pa /etc ,
                    815: .Pa /root
                    816: and
                    817: .Pa /var .
                    818: Note this does not build a
                    819: .Dq release ;
                    820: no release sets are placed in ${RELEASEDIR}.
1.4     ! lukem     821: .Fl d
1.1       lukem     822: is implied by
1.4     ! lukem     823: .Fl R .
1.1       lukem     824: .
1.4     ! lukem     825: .It Fl j Ar njob
1.1       lukem     826: Passed through to
                    827: .Xr make 1 .
                    828: Makefiles should use .WAIT or have explicit dependancies
                    829: as necessary to enforce build ordering.
                    830: If you see build failures with -j, please save complete build logs
                    831: so the failures can be analyzed.
                    832: .
1.4     ! lukem     833: .It Fl k Em kernel
1.2       lukem     834: Build a new kernel.
                    835: The
1.4     ! lukem     836: .Ar kernel
1.2       lukem     837: argument is the name of a configuration file suitable
                    838: for use by
                    839: .Xr config 8 .
                    840: If
1.4     ! lukem     841: .Ar kernel
1.2       lukem     842: does not contain any
                    843: .Sq /
                    844: characters, the configuration file is expected to be found in the
                    845: .Sy KERNCONFDIR
                    846: directory, which is typically
                    847: .Sy sys/arch/MACHINE/conf .
                    848: The new kernel will be built in a subdirectory of
                    849: .Sy KERNOBJDIR ,
                    850: which is typically
                    851: .Sy sys/arch/MACHINE/compile
                    852: or an associated object directory.
                    853: In order to ensure that the kernel is built using up-to-date tools,
                    854: it is strongly recommended that the tools be rebuilt (using the
1.4     ! lukem     855: .Fl t
1.2       lukem     856: option) in a separate invocation of
                    857: .Nm build.sh
                    858: prior to using the
1.4     ! lukem     859: .Fl k
1.2       lukem     860: option, or that the
1.4     ! lukem     861: .Fl t
1.2       lukem     862: and
1.4     ! lukem     863: .Fl k
1.2       lukem     864: options be used together in a single invocation of
                    865: .Nm build.sh .
                    866: .
1.4     ! lukem     867: .It Fl M Ar obj
        !           868: Set
        !           869: .Sy MAKEOBJDIRPREFIX
        !           870: to
        !           871: .Ar obj .
        !           872: .
        !           873: .It Fl m Ar mach
1.1       lukem     874: Set the value of
                    875: .Sy MACHINE
                    876: to
1.4     ! lukem     877: .Ar mach .
1.1       lukem     878: This will also override any value of
                    879: .Sy MACHINE_ARCH
                    880: in the process environment with a value deduced from
1.4     ! lukem     881: .Ar mach ,
1.1       lukem     882: unless
1.4     ! lukem     883: .Fl a
1.1       lukem     884: is specified.  All cross builds require
1.4     ! lukem     885: .Fl m ,
1.1       lukem     886: but if unset on a NetBSD host, the host's value of MACHINE will be
                    887: detected and used automatically.
                    888: .
1.4     ! lukem     889: .It Fl n
1.1       lukem     890: Show the commands that would be executed by
                    891: .Sy build.sh ,
                    892: but do not make any changes.  This is similar in concept to
                    893: .Dq make -n .
                    894: .
1.4     ! lukem     895: .It Fl O Ar obj
1.1       lukem     896: Create an appropriate transform macro for
                    897: .Sy MAKEOBJDIR
                    898: that will place the built object files under
1.4     ! lukem     899: .Ar obj .
1.1       lukem     900: For instance, a setting of
                    901: .Sy /usr/obj
                    902: will place build-time files under
                    903: .Sy /usr/obj/bin , /usr/obj/lib ,
                    904: and so forth.
                    905: .
1.4     ! lukem     906: .It Fl o
        !           907: Set the value of
        !           908: .Sy MKOBJDIRS
        !           909: to
        !           910: .Dq no .
        !           911: .
        !           912: .It Fl R Ar rel
1.1       lukem     913: Set the value of
                    914: .Sy RELEASEDIR
                    915: to
1.4     ! lukem     916: .Ar rel .
1.1       lukem     917: Setting this option will cause
                    918: .Sy build.sh
                    919: to run
                    920: .Dq make release
                    921: instead of
                    922: .Dq make build .
                    923: .
1.4     ! lukem     924: .It Fl r
        !           925: Remove the contents of
        !           926: .Sy DESTDIR
        !           927: and
        !           928: .Sy TOOLDIR
        !           929: before building (provides a clean starting point).  This will skip deleting
        !           930: .Sy DESTDIR
        !           931: if building on a native system to the root directory.
        !           932: .
        !           933: .It Fl T Ar tools
1.1       lukem     934: Set the value of
                    935: .Sy TOOLDIR
                    936: to
1.4     ! lukem     937: .Ar tools .
1.1       lukem     938: If set, the bootstrap
                    939: .Dq make
                    940: will only be rebuilt as needed (when the source files for
                    941: .Xr make 1
                    942: change).
                    943: .
1.4     ! lukem     944: .It Fl t
        !           945: Build and install the host tools from
        !           946: .Sy src/tools
        !           947: only.  This option implies
        !           948: .Fl b .
        !           949: .
        !           950: .It Fl U
1.1       lukem     951: Set the
                    952: .Sy UNPRIVED
                    953: variable.
                    954: .
1.4     ! lukem     955: .It Fl u
        !           956: Set the
        !           957: .Sy UPDATE
        !           958: variable.
        !           959: .
        !           960: .It Fl w Ar wrapper
        !           961: Create the nbmake wrapper script (see below) in a custom location,
        !           962: specified by
        !           963: .Ar wrapper .
        !           964: This allows, for instance, to place the wrapper in
        !           965: .Sy PATH
        !           966: automatically.  Note that
        !           967: .Ar wrapper
        !           968: is the full name of the file, not just a directory name.
        !           969: .
1.1       lukem     970: .El
                    971: .
                    972: .Ss The \*qnbmake-MACHINE\*q wrapper script
                    973: .
                    974: If using the
                    975: .Sy build.sh
                    976: script to build
                    977: .Nx ,
                    978: a
                    979: .Sy nbmake-MACHINE
                    980: script will be created in
                    981: .Sy TOOLDIR/bin
                    982: upon the first build to assist in building subtrees on a cross-compile
                    983: host.
                    984: .Pp
                    985: .Sy nbmake-MACHINE
                    986: can be invoked in lieu of
                    987: .Xr make 1 ,
                    988: and will instead call the up-to-date version of
                    989: .Dq nbmake
                    990: installed into
                    991: .Sy TOOLDIR/bin
                    992: with several key variables pre-set, including
                    993: .Sy MACHINE , MACHINE_ARCH ,
                    994: and
                    995: .Sy TOOLDIR .
                    996: This script can be symlinked into a directory listed in
                    997: .Sy PATH ,
                    998: or called with an absolute path.
1.2       lukem     999: .
                   1000: .Sh EXAMPLES
                   1001: .Bl -tag -width "build.sh"
                   1002: .It Li "./build.sh -t"
                   1003: Build a new toolchain.
                   1004: .It Li "cd ${KERNCONFDIR} ; ${TOOLDIR}/bin/nbconfig GENERIC"
                   1005: Use the new version of
                   1006: .Xr config 8
                   1007: to prepare to build a new GENERIC kernel.
                   1008: .It Li "cd ${KERNOBJDIR}/GENERIC ; ${TOOLDIR}/bin/nbmake-${MACHINE} dependall"
                   1009: Use the new toolchain to build a new GENERIC kernel.
                   1010: .It Li "./build.sh -t -k GENERIC"
                   1011: Build a new toolchain, and use the new toolchain to
                   1012: configure and build a new GENERIC kernel.
                   1013: .It Li "./build.sh -U -d"
                   1014: Using unprivileged mode,
                   1015: build a complete distribution in
                   1016: .Sy DESTDIR .
                   1017: .It Li "./build.sh -U -R /some/dir/RELEASE"
                   1018: Using unprivileged mode,
                   1019: build a complete release in the specified release directory.
                   1020: .El
1.1       lukem    1021: .
                   1022: .Sh OBSOLETE VARIABLES
                   1023: .
                   1024: .Bl -tag -width "NBUILDJOBS"
                   1025: .
                   1026: .It Sy NBUILDJOBS
                   1027: Use the
                   1028: .Xr make 1
                   1029: option
1.4     ! lukem    1030: .Fl j ,
1.1       lukem    1031: instead.
                   1032: .
                   1033: .It Sy USE_NEW_TOOLCHAIN
                   1034: The new toolchain is now the default.
                   1035: To disable, use
                   1036: .Sy TOOLCHAIN_MISSING=yes .
                   1037: .El
                   1038: .Sh SEE ALSO
                   1039: .Xr make 1 ,
                   1040: .Xr hier 7 ,
                   1041: .Xr release 7
                   1042: .
                   1043: .Sh HISTORY
                   1044: .
                   1045: The
                   1046: .Nm build.sh
                   1047: based build scheme was introduced for
                   1048: .Nx 1.6
                   1049: as
                   1050: .Sy USE_NEW_TOOLCHAIN ,
                   1051: and re-worked to
                   1052: .Sy TOOLCHAIN_MISSING
                   1053: after that.
                   1054: .
                   1055: .Sh BUGS
                   1056: .
                   1057: A few platforms are not yet using this build system.

CVSweb <webmaster@jp.NetBSD.org>