Annotation of src/doc/BUILDING.mdoc, Revision 1.1
1.1 ! lukem 1: .\" $NetBSD: BUILDING.mdoc,v 1.21 2002/09/21 05:17:52 lukem Exp $
! 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: .\"
! 41: .Dd September 21, 2002
! 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"
! 109: .It Sy BUILDING.mdoc
! 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
! 520: .Sy -j ,
! 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: .
! 582: .It Sy -j Em njob
! 583: Run up to
! 584: .Em njob
! 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: .
! 592: .It Sy -m Em dir
! 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: .
! 603: .It Sy -n
! 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: .
! 607: .It Sy -v Em var
! 608: Print
! 609: .Xr make 1 Ns 's
! 610: idea of the value of
! 611: .Em var .
! 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: .
! 781: .It Sy -a Em arch
! 782: Set the value of
! 783: .Sy MACHINE_ARCH
! 784: to
! 785: .Em arch .
! 786: .
! 787: .It Sy -B Em buildid
! 788: Set the value of
! 789: .Sy BUILDID
! 790: to
! 791: .Em buildid .
! 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: .
! 797: .It Sy -b
! 798: Bootstrap
! 799: .Dq make
! 800: and create a
! 801: .Sy nbmake-MACHINE
! 802: script (see below).
! 803: .
! 804: .It Sy -d
! 805: Build a full distribution.
! 806: This differs from a default build in that files will also be installed to
! 807: .Pa /dev ,
! 808: .Pa /etc ,
! 809: .Pa /root
! 810: and
! 811: .Pa /var .
! 812: Note this does not build a
! 813: .Dq release ;
! 814: no release sets are placed in ${RELEASEDIR}.
! 815: .Sy -d
! 816: is implied by
! 817: .Sy -R .
! 818: .
! 819: .It Sy -j Em njob
! 820: Passed through to
! 821: .Xr make 1 .
! 822: Makefiles should use .WAIT or have explicit dependancies
! 823: as necessary to enforce build ordering.
! 824: If you see build failures with -j, please save complete build logs
! 825: so the failures can be analyzed.
! 826: .
! 827: .It Sy -m Em mach
! 828: Set the value of
! 829: .Sy MACHINE
! 830: to
! 831: .Em mach .
! 832: This will also override any value of
! 833: .Sy MACHINE_ARCH
! 834: in the process environment with a value deduced from
! 835: .Em mach ,
! 836: unless
! 837: .Sy -a
! 838: is specified. All cross builds require
! 839: .Sy -m ,
! 840: but if unset on a NetBSD host, the host's value of MACHINE will be
! 841: detected and used automatically.
! 842: .
! 843: .It Sy -n
! 844: Show the commands that would be executed by
! 845: .Sy build.sh ,
! 846: but do not make any changes. This is similar in concept to
! 847: .Dq make -n .
! 848: .
! 849: .It Sy -o
! 850: Set the value of
! 851: .Sy MKOBJDIRS
! 852: to
! 853: .Dq no .
! 854: .
! 855: .It Sy -r
! 856: Remove the contents of
! 857: .Sy DESTDIR
! 858: and
! 859: .Sy TOOLDIR
! 860: before building (provides a clean starting point). This will skip deleting
! 861: .Sy DESTDIR
! 862: if building on a native system to the root directory.
! 863: .
! 864: .It Sy -t
! 865: Build and install the host tools from
! 866: .Sy src/tools
! 867: only. This option implies
! 868: .Sy -b .
! 869: .
! 870: .It Sy -u
! 871: Set the
! 872: .Sy UPDATE
! 873: variable.
! 874: .
! 875: .It Sy -w Em wrapper
! 876: Create the nbmake wrapper script (see below) in a custom location,
! 877: specified by
! 878: .Em wrapper .
! 879: This allows, for instance, to place the wrapper in
! 880: .Sy PATH
! 881: automatically. Note that
! 882: .Em wrapper
! 883: is the full name of the file, not just a directory name.
! 884: .
! 885: .It Sy -D Em dest
! 886: Set the value of
! 887: .Sy DESTDIR
! 888: to
! 889: .Em dest .
! 890: .
! 891: .It Sy -M Em obj
! 892: Set
! 893: .Sy MAKEOBJDIRPREFIX
! 894: to
! 895: .Em obj .
! 896: .
! 897: .It Sy -O Em obj
! 898: Create an appropriate transform macro for
! 899: .Sy MAKEOBJDIR
! 900: that will place the built object files under
! 901: .Em obj .
! 902: For instance, a setting of
! 903: .Sy /usr/obj
! 904: will place build-time files under
! 905: .Sy /usr/obj/bin , /usr/obj/lib ,
! 906: and so forth.
! 907: .
! 908: .It Sy -R Em rel
! 909: Set the value of
! 910: .Sy RELEASEDIR
! 911: to
! 912: .Em rel .
! 913: Setting this option will cause
! 914: .Sy build.sh
! 915: to run
! 916: .Dq make release
! 917: instead of
! 918: .Dq make build .
! 919: .
! 920: .It Sy -T Em tools
! 921: Set the value of
! 922: .Sy TOOLDIR
! 923: to
! 924: .Em tools .
! 925: If set, the bootstrap
! 926: .Dq make
! 927: will only be rebuilt as needed (when the source files for
! 928: .Xr make 1
! 929: change).
! 930: .
! 931: .It Sy -U
! 932: Set the
! 933: .Sy UNPRIVED
! 934: variable.
! 935: .
! 936: .El
! 937: .
! 938: .Ss The \*qnbmake-MACHINE\*q wrapper script
! 939: .
! 940: If using the
! 941: .Sy build.sh
! 942: script to build
! 943: .Nx ,
! 944: a
! 945: .Sy nbmake-MACHINE
! 946: script will be created in
! 947: .Sy TOOLDIR/bin
! 948: upon the first build to assist in building subtrees on a cross-compile
! 949: host.
! 950: .Pp
! 951: .Sy nbmake-MACHINE
! 952: can be invoked in lieu of
! 953: .Xr make 1 ,
! 954: and will instead call the up-to-date version of
! 955: .Dq nbmake
! 956: installed into
! 957: .Sy TOOLDIR/bin
! 958: with several key variables pre-set, including
! 959: .Sy MACHINE , MACHINE_ARCH ,
! 960: and
! 961: .Sy TOOLDIR .
! 962: This script can be symlinked into a directory listed in
! 963: .Sy PATH ,
! 964: or called with an absolute path.
! 965: .
! 966: .Sh OBSOLETE VARIABLES
! 967: .
! 968: .Bl -tag -width "NBUILDJOBS"
! 969: .
! 970: .It Sy NBUILDJOBS
! 971: Use the
! 972: .Xr make 1
! 973: option
! 974: .Sy -j ,
! 975: instead.
! 976: .
! 977: .It Sy USE_NEW_TOOLCHAIN
! 978: The new toolchain is now the default.
! 979: To disable, use
! 980: .Sy TOOLCHAIN_MISSING=yes .
! 981: .El
! 982: .Sh SEE ALSO
! 983: .Xr make 1 ,
! 984: .Xr hier 7 ,
! 985: .Xr release 7
! 986: .
! 987: .Sh HISTORY
! 988: .
! 989: The
! 990: .Nm build.sh
! 991: based build scheme was introduced for
! 992: .Nx 1.6
! 993: as
! 994: .Sy USE_NEW_TOOLCHAIN ,
! 995: and re-worked to
! 996: .Sy TOOLCHAIN_MISSING
! 997: after that.
! 998: .
! 999: .Sh BUGS
! 1000: .
! 1001: A few platforms are not yet using this build system.
CVSweb <webmaster@jp.NetBSD.org>
![[BACK]](/icons/back.gif){kind=icon}
Return to BUILDING.mdoc CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [cvs.NetBSD.org] / src / doc