1.\" $NetBSD: BUILDING.mdoc,v 1.27 2003/07/29 10:07:16 lukem Exp $ 2.\" 3.\" Copyright (c) 2001-2003 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 and Luke Mewburn. 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.\" NOTE: After changing this file, run "make build-docs" to generate the 38.\" proper plaintext versions, and check in all BUILDING.* files! 39.\" 40.\" Toolchain prefix for commands 41.ds toolprefix nb 42. 43.Dd July 29, 2003 44.Dt BUILDING 8 45.Os NetBSD 46. 47.Sh NAME 48. 49.Nm BUILDING 50.Nd Procedure for building 51.Nx 52from source code. 53. 54.Sh STATUS 55. 56This document is a work-in-progress. 57As such, the information described 58here may not match the reality of the build system as of this writing. 59Once this document is completely in sync with reality, this paragraph 60will be removed. 61.Pp 62Discrepancies between this documentation and the current reality of 63implementation are noted specially, as with the note below: 64.Pp 65.Em Note : 66This document applies only to platforms which use the new toolchain as 67indicated by the default setting of 68.Sy TOOLCHAIN_MISSING 69in 70.Aq bsd.own.mk . 71Platforms which have not yet been switched to the new toolchain should 72continue building traditionally, using the notes specified in the file 73.Sy UPDATING . 74. 75.Sh REQUIREMENTS 76. 77.Nx 78is designed to be buildable on most POSIX-compliant host systems. 79The basic build procedure is the same whether compiling 80.Em natively 81(on the same 82.Nx 83architecture) or 84.Em cross compiling 85(on another architecture or OS). 86.Pp 87This source tree contains a special subtree, 88.Dq tools , 89which uses the host system to create a build toolchain for the target 90architecture. 91The host system must have at least C and C++ 92compilers in order to create the toolchain 93.Nm ( make 94is not required); all other tools are created as part of the 95.Nx 96build process. 97.Pp 98.Bd -ragged -offset indent 99.Em Note : 100A couple of host toolchain components are not yet available in the tools 101directory. 102Also, some tools use non-POSIX, non-ANSI C extensions 103and need to be standardized. 104As a result, cross-compiling from systems other than 105.Nx 106is not currently supported. 107.Ed 108. 109.Sh FILES 110. 111.Ss Source tree layout 112. 113.Bl -tag -width "BUILDING.mdoc" 114.It Sy doc/BUILDING.mdoc 115This document (in -mdoc troff format; the original copy). 116.It Sy BUILDING 117This document (in plaintext). 118.It Sy Makefile 119The main Makefile for 120.Nx ; 121should only be run for native builds with an appropriately up-to-date 122version of 123.Nx 124.Xr make 1 . 125(For building from out-of-date systems or on a non-native host, see the 126.Nm build.sh 127shell script.) 128.It Sy UPDATING 129Special notes for updating from an earlier revision of 130.Nx . 131It is important to read this file before every build of an updated 132source tree. 133.It Sy build.sh 134Bourne-compatible shell script used for building the host build tools 135and the 136.Nx 137system from scratch. 138Can be used for both native and cross builds, and should be used instead of 139.Xr make 1 140for any source tree that is updated and recompiled regularly. 141.It Sy crypto/dist/ , dist/ , gnu/dist/ 142Sources imported verbatim from third parties, without mangling the 143existing build structure. 144Other source trees in 145.Sy bin 146through 147.Sy usr.sbin 148use the 149.Nx 150.Xr make 1 151.Dq reachover 152Makefile semantics when building these programs for a native host. 153.It Sy distrib/ , etc/ 154Sources for items used when making a full release snapshot, such as 155files installed in 156.Sy DESTDIR Ns Pa /etc 157on the destination system, boot media, and release notes. 158.It Sy regress/ 159Regression test harness. 160Can be cross-compiled, but only run natively. 161.It Sy sys/ 162.Nx 163kernel sources. 164.It Sy tools/ 165.Dq Reachover 166build structure for the host build tools. 167This has a special method of determining out-of-date status. 168.It Sy bin/ ... usr.sbin/ 169Sources to the 170.Nx 171userland (non-kernel) programs. 172If any of these directories are missing, they will be skipped during the build. 173.El 174. 175.Ss Build tree layout 176. 177The 178.Nx 179build tree is described in 180.Xr hier 7 , 181and the release layout is described in 182.Xr release 7 . 183.Pp 184. 185.Sh CONFIGURATION 186. 187.Ss Environment variables 188.. 189Several environment variables control the behaviour of 190.Nx 191builds. 192. 193.Bl -tag -width "MAKEOBJDIRPREFIX" 194. 195.It Sy MACHINE 196Machine type. 197. 198.It Sy MACHINE_ARCH 199Machine architecture. 200. 201.It Sy MAKE 202Path name to invoke 203.Xr make 1 204as. 205. 206.It Sy MAKEFLAGS 207Flags to invoke 208.Xr make 1 209with. 210. 211.It Sy MAKEOBJDIR 212Directory to use as the 213.Sy .OBJDIR 214for the current directory. 215Used only if 216.Sy MAKEOBJDIRPREFIX 217is not defined. 218.Sy MAKEOBJDIR 219can only be provided in the environment or via the 220.Fl M 221flag of 222.Nm build.sh . 223. 224.It Sy MAKEOBJDIRPREFIX 225Top level directory of the object directory tree. 226If this is defined, 227${MAKEOBJDIRPREFIX}/${.CURDIR} 228is used as the 229.Sy .OBJDIR 230for the current directory. 231The current directory may be read only. 232.Sy MAKEOBJDIRPREFIX 233can only be provided in the environment or via the 234.Fl M 235flag of 236.Nm build.sh . 237. 238.El 239. 240.Ss \*qmake\*q variables 241. 242.de YorN 243Can be set to 244.Dq yes 245or 246.Dq no . 247.. 248.de DFLT 249.Pp 250.Em Default : 251.. 252.de DFLTu 253.DFLT 254Unset. 255.. 256.de DFLTy 257.DFLT 258.Dq yes 259.. 260.de DFLTn 261.DFLT 262.Dq no 263.. 264Several variables control the behavior of 265.Nx 266builds. 267Unless otherwise specified, these variables may be set in 268either the process environment or the 269.Xr make 1 270configuration file specified by 271.Sy MAKECONF . 272. 273.Bl -tag -width "MKCATPAGES" 274. 275.It Sy BUILDID 276Identifier for the build. 277The identifier will be appended to 278object directory names, and can be consulted in the 279.Xr make 1 280configuration file in order to set additional build parameters, 281such as compiler flags. 282. 283.It Sy DESTDIR 284Directory to contain the built 285.Nx 286system. 287If set, special options are passed to the compilation tools to 288prevent their default use of the host system's 289.Sy /usr/include , /usr/lib , 290and so forth. 291This pathname should 292.Em not 293end with a slash 294.Pq / 295character (for installation into the system's root directory, set 296.Sy DESTDIR 297to an empty string). 298The directory must reside on a file system which supports long file 299names and hard links. 300.DFLT 301Empty string if 302.Sy USETOOLS 303is 304.Dq yes ; 305unset otherwise. 306.Pp 307.Em Note : 308.Sy build.sh 309will provide a default of 310.Pa destdir. Ns Sy MACHINE 311(in the top-level 312.Sy .OBJDIR ) 313unless run in 314.Sq expert 315mode 316. 317.It Sy MAKECONF 318The name of the 319.Xr make 1 320configuration file. 321.Em Only settable in the process environment. 322.DFLT 323.Dq /etc/mk.conf 324. 325.It Sy MKCATPAGES 326.YorN 327Indicates whether preformatted plaintext manual pages will be created 328during a build. 329.DFLTy 330. 331.It Sy MKCRYPTO 332.YorN 333Indicates whether cryptographic code will be included in a build; 334provided for the benefit of countries that do not allow strong 335cryptography. 336Will not affect use of the standard low-security password encryption system, 337.Xr crypt 3 . 338.DFLTy 339. 340.It Sy MKDOC 341.YorN 342Indicates whether system documentation destined for 343.Sy DESTDIR Ns Pa /usr/share/doc 344will be installed during a build. 345.DFLTy 346. 347.It Sy MKHOSTOBJ 348.YorN 349If set to 350.Dq yes , 351then for programs intended to be run on the compile host, 352the name, release, and architecture of the host operating system 353will be suffixed to the name of the object directory created by 354.Dq make obj . 355(This allows multiple host systems to compile NetBSD for a single target.) 356If set to 357.Dq no , 358then programs built to be run on the compile host will use the same 359object directory names as programs built to be run on the target. 360.DFLTn 361. 362.It Sy MKINFO 363.YorN 364Indicates whether GNU Info files, used for the documentation for 365most of the compilation tools, will be created and installed during a 366build. 367.DFLTy 368. 369.It Sy MKLINT 370.YorN 371Indicates whether 372.Xr lint 1 373will be run against portions of the 374.Nx 375source code during the build, and whether lint libraries will be 376installed into 377.Sy DESTDIR Ns Pa /usr/libdata/lint . 378.DFLTy 379. 380.It Sy MKMAN 381.YorN 382Indicates whether manual pages will be installed during a build. 383.DFLTy 384. 385.It Sy MKNLS 386.YorN 387Indicates whether Native Language System locale zone files will be 388compiled and installed during a build. 389.DFLTy 390. 391.It Sy MKOBJ 392.YorN 393Indicates whether object directories will be created when running 394.Dq make obj . 395If set to 396.Dq no , 397then all built files will be located inside the regular source tree. 398.DFLTy 399. 400.It Sy MKPIC 401.YorN 402Indicates whether shared objects and libraries will be created and 403installed during a build. 404If set to 405.Dq no , 406the entire built system will be statically linked. 407.DFLT 408Platform dependent. 409As of this writing, all platforms except 410.Sy sh3 411default to 412.Dq yes . 413. 414.It Sy MKPICINSTALL 415.YorN 416Indicates whether the 417.Xr ar 1 418format libraries 419.Sy ( lib*_pic.a ) , 420used to generate shared libraries, are installed during a build. 421.DFLTy 422. 423.It Sy MKPROFILE 424.YorN 425Indicates whether profiled libraries 426.Sy ( lib*_p.a ) 427will be built and installed during a build. 428.DFLT 429.Dq yes ; 430however, some platforms turn off 431.Sy MKPROFILE 432by default at times due to toolchain problems with profiled code. 433. 434.It Sy MKSHARE 435.YorN 436Indicates whether files destined to reside in 437.Sy DESTDIR Ns Pa /usr/share 438will be built and installed during a build. 439If set to 440.Dq no , 441then all of 442.Sy MKCATPAGES , MKDOC , MKINFO , MKMAN , 443and 444.Sy MKNLS 445will be set to 446.Dq no 447unconditionally. 448.DFLTy 449. 450.It Sy MKUNPRIVED 451.YorN 452Indicates whether an unprivileged install will occur. 453The user, group, permissions, and file flags, will not be set on 454the installed item; instead the information will be appended to 455a file called 456.Pa METALOG 457in 458.Sy DESTDIR . 459The contents of 460.Pa METALOG 461is used during the generation of the distribution tar files to ensure 462that the appropriate file ownership is stored. 463.DFLTn 464. 465.It Sy MKUPDATE 466.YorN 467Indicates whether all install operations intended to write to 468.Sy DESTDIR 469will compare file timestamps before installing, and skip the install 470phase if the destination files are up-to-date. 471This also has implications on full builds (see next subsection). 472.DFLTn 473. 474.It Sy TOOLDIR 475Directory to hold the host tools, once built. 476This directory should be unique to a given host system and 477.Nx 478source tree. 479(However, multiple targets may share the same 480.Sy TOOLDIR ; 481the target-dependent files have unique names.) If unset, a default based 482on the 483.Xr uname 1 484information of the host platform will be created in the 485.Sy .OBJDIR 486of 487.Pa src . 488.DFLTu 489. 490.It Sy USETOOLS 491Indicates whether the tools specified by 492.Sy TOOLDIR 493should be used as part of a build in progress. 494Must be set to 495.Dq yes 496if cross-compiling. 497.Bl -tag -width "never" 498.It Sy yes 499Use the tools from 500.Sy TOOLDIR . 501.It Sy no 502Do not use the tools from 503.Sy TOOLDIR , 504but refuse to build native compilation tool components that are 505version-specific for that tool. 506.It Sy never 507Do not use the tools from 508.Sy TOOLDIR , 509even when building native tool components. 510This is similar to the traditional 511.Nx 512build method, but does 513.Em not 514verify that the compilation tools in use are up-to-date enough in order 515to build the tree successfully. 516This may cause build or runtime problems when building the whole 517.Nx 518source tree. 519.El 520.DFLT 521.Dq yes 522if building all or part of a whole 523.Nx 524source tree (detected automatically); 525.Dq no 526otherwise (to preserve traditional semantics of the 527.Aq bsd.*.mk 528.Xr make 1 529include files). 530. 531.El 532. 533.Ss \*qmake\*q variables for full builds 534These variables only affect the top level 535.Dq Makefile 536and do not affect manually building subtrees of the 537.Nx 538source code. 539. 540.Bl -tag -width "INSTALLWORLDDIR" 541. 542.It Sy INSTALLWORLDDIR 543Location for the 544.Dq make installworld 545target to install to. 546.DFLT 547.Dq / 548. 549.It Sy MKOBJDIRS 550.YorN 551Indicates whether object directories will be created automatically 552(via a 553.Dq make obj 554pass) at the start of a build. 555.DFLTn 556. 557.It Sy MKUPDATE 558.YorN 559If set, then in addition to the effects described for 560.Sy MKUPDATE=yes 561above, this implies the effects of 562.Sy NOCLEANDIR 563(i.e., 564.Dq make cleandir 565is avoided). 566.DFLTn 567. 568.It Sy NBUILDJOBS 569Now obsolete. 570Use the 571.Xr make 1 572option 573.Fl j , 574instead (see below) 575.DFLTu 576. 577.It Sy NOCLEANDIR 578If set, avoids the 579.Dq make cleandir 580phase of a full build. 581This has the effect of allowing only changed 582files in a source tree to be recompiled. 583This can speed up builds when updating only a few files in the tree. 584.DFLTu 585. 586.It Sy NODISTRIBDIRS 587If set, avoids the 588.Dq make distrib-dirs 589phase of a full build. 590This skips running 591.Xr mtree 8 592on 593.Sy DESTDIR , 594useful on systems where building as an unprivileged user, or where it is 595known that the system-wide mtree files have not changed. 596.DFLTu 597. 598.It Sy NOINCLUDES 599If set, avoids the 600.Dq make includes 601phase of a full build. 602This has the effect of preventing 603.Xr make 1 604from thinking that some programs are out-of-date simply because the 605system include files have changed. 606However, this option should not be used when updating the entire 607.Nx 608source tree arbitrarily; it is suggested to use 609.Sy MKUPDATE=yes 610in that case. 611.DFLTu 612. 613.It Sy RELEASEDIR 614If set, specifies the directory to which a 615.Xr release 7 616layout will be written at the end of a 617.Dq make release . 618.DFLTu 619.Pp 620.Em Note : 621.Sy build.sh 622will provide a default of 623.Pa releasedir 624(in the top-level 625.Sy .OBJDIR ) 626unless run in 627.Sq expert 628mode 629. 630.El 631. 632.Sh BUILDING 633. 634.Ss \*qmake\*q command line options 635This is only a summary of options available to 636.Xr make 1 ; 637only the options used most frequently with 638.Nx 639builds are listed here. 640. 641.Bl -tag -width "var=value" 642. 643.It Fl j Ar njob 644Run up to 645.Ar njob 646.Xr make 1 647subjobs in parallel. 648Makefiles should use .WAIT or have explicit dependancies 649as necessary to enforce build ordering. 650If you see build failures with -j, please save complete build logs 651so the failures can be analyzed. 652. 653.It Fl m Ar dir 654Specify the default directory for searching for system Makefile 655segments, mainly the 656.Aq bsd.*.mk 657files. 658When building any full 659.Nx 660source tree, this should be set to the 661.Dq share/mk 662directory in the source tree. 663(This is set automatically when building from the top level.) 664. 665.It Fl n 666Display the commands that would have been executed, but do not 667actually execute them. 668This will still cause recursion to take place. 669. 670.It Fl v Ar var 671Print 672.Xr make 1 Ns 's 673idea of the value of 674.Ar var . 675Does not build any targets. 676. 677.It Em var=value 678Set the variable 679.Em var 680to 681.Em value , 682overriding any setting specified by the process environment, the 683.Sy MAKECONF 684configuration file, or the system Makefile segments. 685. 686.El 687. 688.Ss \*qmake\*q targets 689. 690These default targets may be built by running 691.Xr make 1 692in any subtree of the 693.Nx 694source code. 695It is recommended that none of these be used from the top 696level Makefile; as a specific exception, 697.Dq make obj 698and 699.Dq make cleandir 700are useful in that context. 701. 702.Bl -tag -width "dependall" 703. 704.It Sy all 705Build programs, libraries, and preformatted documentation. 706. 707.It Sy clean 708Remove program and library object code files. 709. 710.It Sy cleandir 711Same as 712.Sy clean , 713but also remove preformatted documentation, dependency files generated 714by 715.Dq make depend , 716and any other files known to be created at build time. 717.Dq make distclean 718may be used as a synonym, for familiarity with a similar well-known 719convention. 720. 721.It Sy depend 722Create dependency files 723.Sy ( .depend ) 724containing more detailed information about the dependencies of source 725code on header files. 726Allows programs to be recompiled automatically when a dependency changes. 727. 728.It Sy dependall 729Does a 730.Dq make depend 731immediately followed by a 732.Dq make all . 733This improves cache locality of the build since both passes read the source 734files in their entirety. 735. 736.It Sy includes 737Build and install system header files. 738Typically needed before any system libraries or programs can be built. 739. 740.It Sy install 741Install programs, libraries, and documentation into 742.Sy DESTDIR . 743Few files will be installed to 744.Sy DESTDIR Ns Pa /dev , 745.Sy DESTDIR Ns Pa /etc , 746.Sy DESTDIR Ns Pa /root 747or 748.Sy DESTDIR Ns Pa /var 749in order to prevent user supplied configuration data from being overwritten. 750.It Sy lint 751Run 752.Xr lint 1 753against the C source code, where appropriate, and generate 754system-installed lint libraries. 755. 756.It Sy obj 757Create object directories to be used for built files, instead of 758building directly in the source tree. 759. 760.It Sy tags 761Create 762.Xr ctags 1 763searchable function lists usable by the 764.Xr ex 1 765and 766.Xr vi 1 767text editors. 768. 769.El 770. 771.Ss \*qmake\*q targets for the top level 772. 773Additional 774.Xr make 1 775targets are usable specifically from the top source level to facilitate 776building the entire 777.Nx 778source tree. 779. 780.Bl -tag -width "distribution" 781. 782.It Sy build 783Build the entire 784.Nx 785system. 786This orders portions of the source tree such that prerequisites 787will be built in the proper order. 788. 789.It Sy distribution 790Do a 791.Dq make build , 792and then install a full distribution into 793.Sy DESTDIR , 794including files in 795.Sy DESTDIR Ns Pa /dev , 796.Sy DESTDIR Ns Pa /etc , 797.Sy DESTDIR Ns Pa /root 798and 799.Sy DESTDIR Ns Pa /var . 800. 801.It Sy buildworld 802As per 803.Dq make distribution , 804except that it ensures that 805.Sy DESTDIR 806is not the root directory. 807. 808.It Sy installworld 809Install the distribution from 810.Sy DESTDIR 811to 812.Sy INSTALLWORLDDIR 813(which defaults to the root directory). 814Ensures that 815.Sy INSTALLWORLDDIR 816is the not root directory if cross compiling. 817.Pp 818.Em Note : 819It is highly recommended that you upgrade your kernel and reboot 820before performing this operation. 821. 822.It Sy sets 823Create distribution sets from 824.Sy DESTDIR 825into 826.Sy RELEASEDIR/MACHINE Ns Pa /binary/sets . 827Should be run after 828.Dq make distribution 829(as 830.Dq make build 831does not install all of the required files). 832. 833.It Sy sourcesets 834Create source sets of the source tree into 835.Sy RELEASEDIR Ns Pa /source/sets . 836. 837.It Sy release 838Do a 839.Dq make distribution , 840build kernels, distribution media, and install sets 841(this as per 842.Dq make sets ) , 843and 844then package the system into a standard release layout as described by 845.Xr release 7 . 846This requires that 847.Sy RELEASEDIR 848be set (see above). 849. 850.It Sy regression-tests 851Can only be run after building the regression tests in the directory 852.Dq regress . 853Runs the compiled regression tests on the local host. 854. 855.El 856. 857.Ss The \*qbuild.sh\*q script 858. 859This script file is a Bourne shell script designed to build the 860entire 861.Nx 862system on any host with a Bourne shell in 863.Sy /bin/sh , 864including many that are not POSIX compliant. 865Note that if a host system's 866.Sy /bin/sh 867is unusually old and broken, the Korn Shell 868.Sy ( /bin/ksh ) , 869if available, may be a usable alternative. 870.Pp 871All cross-compile builds, and most native builds, of the entire system 872should make use of 873.Sy build.sh 874rather than just running 875.Dq make . 876This way, the 877.Xr make 1 878program will be bootstrapped properly, in case the host system has an 879older or incompatible 880.Dq make 881program. 882.Pp 883When compiling the entire system via 884.Sy build.sh , 885many 886.Xr make 1 887variables are set for you in order to help encapsulate the build 888process. 889In the list of options below, variables that are automatically set by 890.Sy build.sh 891are noted where applicable. 892. 893.Pp 894The following operations are supported by 895.Sy build.sh : 896. 897.Bl -tag -width "distribution" 898. 899.It Sy build 900Build the system as per 901.Dq make build . 902This option implies the 903.Sy obj 904and 905.Sy tools 906operations. 907. 908.It Sy distribution 909Build a full distribution as per 910.Dq make distribution . 911This option implies the 912.Sy build 913operation. 914. 915.It Sy release 916Build a full release as per 917.Dq make release . 918This option implies the 919.Sy distribution 920operation. 921. 922.It Sy makewrapper 923Create the 924.Sy \*[toolprefix]make-MACHINE 925wrapper. 926This operation is automatically performed for any of the other 927operations. 928. 929.It Sy obj 930Perform 931.Dq make obj . 932. 933.It Sy tools 934Build and install the host tools from 935.Pa src/tools . 936. 937.It Sy install Ns = Ns Ar idir 938Install the contents of 939.Sy DESTDIR 940to 941.Ar idir , 942using 943.Dq make installworld . 944. 945.It Sy kernel Ns = Ns Ar kconf 946Build a new kernel. 947The 948.Ar kconf 949argument is the name of a configuration file suitable 950for use by 951.Xr config 8 . 952If 953.Ar kconf 954does not contain any 955.Sq / 956characters, the configuration file is expected to be found in the 957.Sy KERNCONFDIR 958directory, which is typically 959.Sy sys/arch/MACHINE/conf . 960The new kernel will be built in a subdirectory of 961.Sy KERNOBJDIR , 962which is typically 963.Sy sys/arch/MACHINE/compile 964or an associated object directory. 965In order to ensure that the kernel is built using up-to-date tools, 966it is strongly recommended that the tools be rebuilt (using the 967.Sy tools 968operation). 969. 970.It Sy releasekernel Ns = Ns Ar kconf 971Install a 972.Xr gzip 1 Ns ed 973copy of the kernel built by 974.Sy kernel Ns = Ns Ar kconf 975into 976.Sy RELEASEDIR/MACHINE Ns Pa /binary/kernel , 977usually as 978.Pa netbsd- Ns Ar kconf Ns Pa .gz , 979although the 980.Dq Pa netbsd 981prefix is determined from the 982.Dq Sy config 983directives in 984.Ar kconf . 985. 986.It Sy sets 987Perform 988.Dq make sets . 989. 990.It Sy sourcesets 991Perform 992.Dq make sourcesets . 993. 994.El 995. 996.Pp 997The following command line options alter the behaviour of the above 998operations: 999The following command line options alter the behaviour of the 1000.Sy build.sh 1001operations described above: 1002. 1003.Bl -tag -width "-T tools" 1004. 1005.It Fl a Ar arch 1006Set the value of 1007.Sy MACHINE_ARCH 1008to 1009.Ar arch . 1010. 1011.It Fl B Ar buildid 1012Set the value of 1013.Sy BUILDID 1014to 1015.Ar buildid . 1016This will also append the build idenfitier to the name of the 1017.Dq make 1018wrapper script so that the resulting name is of the form 1019.Dq Sy \*[toolprefix]make-MACHINE-BUILDID . 1020. 1021.It Fl D Ar dest 1022Set the value of 1023.Sy DESTDIR 1024to 1025.Ar dest . 1026. 1027.It Fl E 1028Set 1029.Sq expert 1030mode. 1031This overrides various sanity checks, and allows: 1032.Sy DESTDIR 1033does not have to be set to a non-root path for builds, 1034and 1035.Sy MKUNPRIVED=yes 1036does not have to be set when building as a non-root user. 1037.Pp 1038.Em Note : 1039It is highly recommended that you know what you are doing when 1040you use this option. 1041. 1042.It Fl j Ar njob 1043Passed through to 1044.Xr make 1 . 1045Makefiles should use .WAIT or have explicit dependancies 1046as necessary to enforce build ordering. 1047If you see build failures with -j, please save complete build logs 1048so the failures can be analyzed. 1049. 1050.It Fl M Ar obj 1051Set 1052.Sy MAKEOBJDIRPREFIX 1053to 1054.Ar obj . 1055Unsets 1056.Sy MAKEOBJDIR . 1057. 1058.It Fl m Ar mach 1059Set the value of 1060.Sy MACHINE 1061to 1062.Ar mach . 1063This will also override any value of 1064.Sy MACHINE_ARCH 1065in the process environment with a value deduced from 1066.Ar mach , 1067unless 1068.Fl a 1069is specified, or 1070.Ar mach 1071is a special case listed below. 1072All cross builds require 1073.Fl m , 1074but if unset on a NetBSD host, the host's value of MACHINE will be 1075detected and used automatically. 1076.Pp 1077Some machines support multiple values for 1078.Sy MACHINE_ARCH . 1079For a given value of 1080.Ar mach , 1081the following 1082.Sy MACHINE 1083and 1084.Sy MACHINE_ARCH 1085values will result: 1086.Bl -column "evbmips-el" "MACHINE" "MACHINE_ARCH" -offset indent 1087.It Sy mach Ta Sy "MACHINE" Ta Sy "MACHINE_ARCH" 1088.It evbmips Ta evbmips Ta (not set) 1089.It evbmips-eb Ta evbmips Ta mipseb 1090.It evbmips-el Ta evbmips Ta mipsel 1091.It evbsh3 Ta evbsh3 Ta (not set) 1092.It evbsh3-eb Ta evbsh3 Ta sh3eb 1093.It evbsh3-el Ta evbsh3 Ta sh3el 1094.It sbmips Ta sbmips Ta (not set) 1095.It sbmips-eb Ta sbmips Ta mipseb 1096.It sbmips-el Ta sbmips Ta mipsel 1097.El 1098. 1099.It Fl n 1100Show the commands that would be executed by 1101.Sy build.sh , 1102but do not make any changes. 1103This is similar in concept to 1104.Dq make -n . 1105. 1106.It Fl O Ar obj 1107Create an appropriate transform macro for 1108.Sy MAKEOBJDIR 1109that will place the built object files under 1110.Ar obj . 1111For instance, a setting of 1112.Sy /usr/obj 1113will place build-time files under 1114.Sy /usr/obj/bin , 1115.Sy /usr/obj/lib , 1116.Sy /usr/obj/usr.bin , 1117and so forth. 1118Unsets 1119.Sy MAKEOBJDIRPREFIX . 1120. 1121.It Fl o 1122Set the value of 1123.Sy MKOBJDIRS 1124to 1125.Dq no . 1126Otherwise, it will be automatically set to 1127.Dq yes 1128(which is opposite to the default behaviour). 1129. 1130.It Fl R Ar rel 1131Set the value of 1132.Sy RELEASEDIR 1133to 1134.Ar rel . 1135. 1136.It Fl r 1137Remove the contents of 1138.Sy DESTDIR 1139and 1140.Sy TOOLDIR 1141before building (provides a clean starting point). 1142This will skip deleting 1143.Sy DESTDIR 1144if building on a native system to the root directory. 1145. 1146.It Fl T Ar tools 1147Set the value of 1148.Sy TOOLDIR 1149to 1150.Ar tools . 1151If set, the bootstrap 1152.Dq make 1153will only be rebuilt as needed (when the source files for 1154.Xr make 1 1155change). 1156. 1157.It Fl U 1158Set 1159.Sy MKUNPRIVED=yes . 1160. 1161.It Fl u 1162Set 1163.Sy MKUPDATE=yes . 1164. 1165.It Xo 1166.Fl V 1167.Sm off 1168.Ar var 1169.Li = 1170.Op Ar value 1171.Sm on 1172.Xc 1173Set the environment variable 1174.Ar var 1175to an optional 1176.Ar value . 1177This is propagated to the 1178.Sy \*[toolprefix]make 1179wrapper. 1180. 1181.It Fl w Ar wrapper 1182Create the 1183.Sy \*[toolprefix]make 1184wrapper script (see below) in a custom location, 1185specified by 1186.Ar wrapper . 1187This allows, for instance, to place the wrapper in 1188.Sy PATH 1189automatically. 1190Note that 1191.Ar wrapper 1192is the full name of the file, not just a directory name. 1193. 1194.It Fl Z Ar var 1195Unset ("zap") the environment variable 1196.Ar var . 1197This is propagated to the 1198.Sy \*[toolprefix]make 1199wrapper. 1200. 1201.El 1202. 1203.Ss The \*q\*[toolprefix]make-MACHINE\*q wrapper script 1204. 1205If using the 1206.Sy build.sh 1207script to build 1208.Nx , 1209a 1210.Sy \*[toolprefix]make-MACHINE 1211script will be created in 1212.Sy TOOLDIR/bin 1213upon the first build to assist in building subtrees on a cross-compile 1214host. 1215.Pp 1216.Sy \*[toolprefix]make-MACHINE 1217can be invoked in lieu of 1218.Xr make 1 , 1219and will instead call the up-to-date version of 1220.Dq \*[toolprefix]make 1221installed into 1222.Sy TOOLDIR/bin 1223with several key variables pre-set, including 1224.Sy MACHINE , MACHINE_ARCH , 1225and 1226.Sy TOOLDIR . 1227.Sy build.sh 1228will also set variables specified with 1229.Fl V , 1230and unset variables specified with 1231.Fl Z . 1232.Pp 1233This script can be symlinked into a directory listed in 1234.Sy PATH , 1235or called with an absolute path. 1236. 1237.Sh EXAMPLES 1238. 1239.Bl -enum 1240. 1241.It 1242.Li "./build.sh tools kernel=GENERIC" 1243.Pp 1244Build a new toolchain, and use the new toolchain to 1245configure and build a new GENERIC kernel. 1246. 1247.It 1248.Li "./build.sh -U distribution" 1249.Pp 1250Using unprivileged mode, 1251build a complete distribution to a 1252.Sy DESTDIR 1253directory that 1254.Sy build.sh 1255selects (and will display). 1256. 1257.It 1258.Li "# ./build.sh -U install=/" 1259.Pp 1260As root, install to 1261.Pa / 1262the distribution that was built 1263by example 2. 1264Even though this is run as root, 1265.Fl U 1266is required so that the permissions stored in 1267.Sy DESTDIR Ns Pa /METALOG 1268are correctly applied to the files as they're copied to 1269.Pa / . 1270. 1271.It 1272.Li "./build.sh -U -u release" 1273.Pp 1274Using unprivileged mode, 1275build a complete release to 1276.Sy DESTDIR 1277and 1278.Sy RELEASEDIR 1279directories that 1280.Sy build.sh 1281selects (and will display). 1282.Sy MKUPDATE=yes 1283.Pq Fl u 1284is set to prevent the 1285.Dq make cleandir , 1286so that if this is run after example 2, it doesn't need to redo that 1287portion of the release build. 1288.El 1289. 1290.Sh OBSOLETE VARIABLES 1291. 1292.Bl -tag -width "NBUILDJOBS" 1293. 1294.It Sy NBUILDJOBS 1295Use the 1296.Xr make 1 1297option 1298.Fl j , 1299instead. 1300. 1301.It Sy USE_NEW_TOOLCHAIN 1302The new toolchain is now the default. 1303To disable, use 1304.Sy TOOLCHAIN_MISSING=yes . 1305.El 1306.Sh SEE ALSO 1307.Xr make 1 , 1308.Xr hier 7 , 1309.Xr release 7 1310. 1311.Sh HISTORY 1312. 1313The 1314.Nm build.sh 1315based build scheme was introduced for 1316.Nx 1.6 1317as 1318.Sy USE_NEW_TOOLCHAIN , 1319and re-worked to 1320.Sy TOOLCHAIN_MISSING 1321after that. 1322. 1323.Sh BUGS 1324. 1325A few platforms are not yet using this build system. 1326