1.\" $NetBSD: BUILDING.mdoc,v 1.149 2023/07/22 18:50:04 lukem Exp $ 2.\" 3.\" Copyright (c) 2001-2023 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.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.\" NOTE: After changing this file, run "make regen" in the src/doc 31.\" directory, and check in both src/BUILDING and src/doc/BUILDING.mdoc. 32.\" 33.\" Toolchain prefix for commands 34.ds toolprefix nb 35. 36.Dd July 21, 2023 37.Dt BUILDING 8 38.Os NetBSD 39.\" turn off hyphenation 40.hym 999 41. 42.\" if this file is processed with real roff (doc.tmac) 43.\" now that the tmac files have been lazily read, 44.\" we can override ``quotes'' with "quotes" for ascii output 45.ie '\*[Lq]'``' \{\ 46.ds Lq \*q 47.ds Rq \*q 48.\} 49.\" and disable hyphenation 50.nr hyphen-flags 0 51. 52.Sh NAME 53. 54.Nm BUILDING 55.Nd Procedure for building 56.Nx 57from source code 58. 59.Sh REQUIREMENTS 60. 61.Nx 62is designed to be buildable on most POSIX-compliant host systems. 63The basic build procedure is the same whether compiling 64.Em natively 65(on the same 66.Nx 67architecture) or 68.Em cross compiling 69(on another architecture or OS). 70.Pp 71This source tree contains the 72.Sy build.sh 73shell script which supports both native and cross builds of 74.Nx . 75.Pp 76This source tree contains a special subtree, 77.Dq tools , 78which uses the host system to create a build toolchain for the target 79architecture. 80The host system must have at least C and C++ 81compilers in order to create the toolchain 82.Xr ( make 1 83is not required); all other tools 84(including 85.Xr make 1 86as 87.Sy \*[toolprefix]make ) 88are created as part of the 89.Nx 90build process. 91(See the 92.Sx Environment variables 93section below if you need 94to override or manually select your compilers.) 95.Pp 96.Em Note : 97Within this document, cross-references to manual pages are to the 98.Nx 99manual pages, not the host system manual pages. 100The 101.Xr mdoc 7 102source 103to the 104.Nx 105manual pages can be found within the source tree, 106and these and can be formatted with 107.Xr mandoc 1 108or 109.Xr nroff 1 110if those are available on the host system. 111The 112.Nx 113manual pages are also available at 114.Lk https://man.netbsd.org 115. 116.Sh FILES 117. 118.Ss Source tree layout 119. 120.Bl -tag -width "BUILDING.mdoc" 121. 122.It Pa BUILDING 123This document (in plaintext). 124Generated from 125.Pa doc/BUILDING.mdoc . 126. 127.It Pa Makefile 128The main Makefile for 129.Nx ; 130should only be run for native builds with an appropriately up-to-date 131version of 132.Nx 133.Xr make 1 . 134Intended for expert use with knowledge of its shortcomings, 135it has been superseded by the 136.Sy build.sh 137shell script as the recommended means for building 138.Nx . 139. 140.It Pa UPDATING 141Special notes for updating from an earlier revision of 142.Nx . 143It is important to read this file before every build of an updated 144source tree. 145. 146.It Pa build.sh 147Bourne-compatible shell script used for building the host build tools 148and the 149.Nx 150system from scratch. 151Can be used for both native and cross builds, and should be used instead of 152.Xr make 1 153as it performs additional checks to prevent common issues going undetected, such 154as building with an outdated version of 155.Xr make 1 . 156. 157.It Pa crypto/dist/ , dist/ , gnu/dist/ 158Sources imported verbatim from third parties, without mangling the 159existing build structure. 160Other source trees in 161.Pa bin 162through 163.Pa usr.sbin 164use the 165.Nx 166.Xr make 1 167.Dq reachover 168Makefile semantics when building these programs for a native host. 169. 170.It Pa distrib/ , etc/ 171Sources for items used when making a full release snapshot, such as 172files installed in 173.Sy DESTDIR Ns Pa /etc 174on the destination system, boot media, and release notes. 175. 176.It Pa doc/BUILDING.mdoc 177The source to this document, in 178.Xr mdoc 7 179format. 180Used to generate 181.Pa BUILDING . 182. 183.It Pa external/ , sys/external/ 184Sources and build infrastructure for components imported (mostly) unchanged 185from upstream maintainers, sorted by applicable license. 186This is (slowly) replacing the 187.Pa crypto/dist , 188.Pa dist , 189and 190.Pa gnu/dist 191directories. 192. 193.It Pa external/mit/xorg/ 194.Dq Reachover 195build structure for modular Xorg; the source is in 196.Sy X11SRCDIR . 197. 198.It Pa mk.conf 199Optional source tree specific 200.Xr mk.conf 5 , 201used (if present) instead of 202.Pa /etc/mk.conf 203unless 204.Sy MAKECONF 205is defined. 206.Pp 207.Em Note : 208Not part of the 209.Nx 210source repository. 211. 212.It Pa regress/ , tests/ 213Regression test harness. 214Can be cross-compiled, but only run natively. 215.Pa tests/ 216uses the 217.Xr atf 7 218test framework; 219.Pa regress/ 220contains older tests that have not yet been migrated to 221.Xr atf 7 . 222. 223.It Pa sys/ 224.Nx 225kernel sources. 226. 227.It Pa tools/ 228.Dq Reachover 229build structure for the host build tools. 230This has a special method of determining out-of-date status. 231. 232.It Pa tools/compat/README 233Special notes for cross-hosting a NetBSD build on non-NetBSD platforms. 234. 235.It Other directories including Pa bin/ ... usr.sbin/ 236Sources to the 237.Nx 238userland (non-kernel) programs. 239If any of these directories are missing, they will be skipped during the build. 240. 241.El 242. 243.Ss Build tree layout 244. 245The 246.Nx 247build tree is described in 248.Xr hier 7 249(whose 250.Xr mdoc 7 251source is in 252.Pa share/man/man7/hier.7 ) , 253and the release layout is described in 254.Xr release 7 255(whose 256.Xr mdoc 7 257source is in 258.Pa share/man/man7/release.7 ) . 259. 260.Sh CONFIGURATION 261. 262.Ss Environment variables 263. 264.de DFLT 265.Pp 266.Em Default : 267.. 268.de DFLTn 269.DFLT 270.Dq no . 271.. 272.de DFLTu 273.DFLT 274Unset. 275.. 276.de DFLTy 277.DFLT 278.Dq yes . 279.. 280.de NODEF 281.Pp 282Forced to 283.Dq no 284if 285.Sy \\$* 286is defined, 287usually in the Makefile before any 288.Xr make 1 289.Cm \&.include 290directives. 291.. 292.de NOVAR 293.Pp 294Forced to 295.Dq no 296if 297.Sy \\$* . 298.. 299.de YorN 300Can be set to 301.Dq yes 302or 303.Dq no . 304.. 305. 306Several environment variables control the behaviour of 307.Nx 308builds. 309. 310.Bl -tag -width 14n 311. 312.\" These entries are sorted alphabetically. 313. 314.It Sy HOST_CC 315Path name to C compiler used to create the toolchain. 316.DFLT 317.Dq cc . 318. 319.It Sy HOST_CFLAGS 320Flags passed to the host C compiler. 321.DFLT 322.Dq \&-O . 323. 324.It Sy HOST_CPPFLAGS 325Flags passed to the host C/C++ pre-processor. 326.DFLTu 327. 328.It Sy HOST_CXX 329Path name to C++ compiler used to create the toolchain. 330.DFLT 331Unset, but defaults to 332.Dq c++ 333where required. 334. 335.It Sy HOST_CXXFLAGS 336Flags passed to the host C++ compiler. 337.DFLTu 338. 339.It Sy HOST_SH 340Path name to a shell available on the host system 341and suitable for use during the build. 342The 343.Nx 344build system requires a modern Bourne-like shell 345with POSIX-compliant features, 346and also requires support for the 347.Dq local 348keyword to declare local variables in shell functions 349(which is a widely-implemented but non-standardised feature). 350.Pp 351Depending on the host system, a suitable shell may be 352.Pa /bin/sh , 353.Pa /usr/xpg4/bin/sh , 354.Pa /bin/ksh 355(provided it is a variant of ksh that supports the 356.Dq local 357keyword, 358such as ksh88, but not ksh93), 359or 360.Pa /usr/local/bin/bash . 361.Pp 362Most parts of the build require 363.Sy HOST_SH 364to be an absolute path; however, 365.Sy build.sh 366allows it to be a simple command name, which will be converted 367to an absolute path by searching the 368.Ev PATH . 369.DFLT 370.Dq sh . 371. 372.It Sy INSTALLBOOT_UBOOT_PATHS 373A colon-separated list of search paths used by 374.Xr installboot 8 375to find U-Boot packages. 376.DFLTu 377. 378.It Sy MACHINE 379Machine type, e.g., 380.Dq macppc . 381.DFLTu 382. 383.It Sy MACHINE_ARCH 384Machine architecture, e.g., 385.Dq powerpc . 386.DFLTu 387. 388.It Sy MAKE 389Path name to invoke 390.Xr make 1 391as. 392.DFLT 393.Dq make . 394. 395.It Sy MAKECONF 396The name of the 397.Xr make 1 398configuration file. 399See 400.Sx make variables 401and 402.Xr mk.conf 5 . 403.Pp 404.Em Note : 405Only settable in the process environment. 406.DFLT 407.Dq Pa /etc/mk.conf , 408although 409.Sy build.sh 410will set the default to the full path to 411.Pa mk.conf 412if the latter is present in the same directory as 413.Sy build.sh . 414. 415.It Sy MAKEFLAGS 416Flags to invoke 417.Xr make 1 418with. 419.Pp 420.Em Note : 421.Sy build.sh 422ignores the value of 423.Sy MAKEFLAGS 424passed in the environment, but allows 425.Sy MAKEFLAGS 426to be set via the 427.Fl V 428option. 429.DFLT 430.Dq \&-X 431on systems with a small 432.Dv ARG_MAX 433(Cygwin, Darwin, FreeBSD); 434otherwise unset. 435. 436.It Sy MAKEOBJDIR 437Directory to use as the 438.Sy .OBJDIR 439for the current directory. 440The value is subjected to variable expansion by 441.Xr make 1 . 442Typical usage is to set this variable to a value involving the use of 443.Sq ${.CURDIR:S...} 444or 445.Sq ${.CURDIR:C...} , 446to derive the value of 447.Sy .OBJDIR 448from the value of 449.Sy .CURDIR . 450Used only if 451.Sy MAKEOBJDIRPREFIX 452is not defined. 453.Pp 454.Em Note : 455.Sy MAKEOBJDIR 456can be provided only in the environment or via the 457.Fl O 458flag of 459.Sy build.sh ; 460it cannot usefully be set inside a Makefile, including in 461.Xr mk.conf 5 462or 463.Sy MAKECONF . 464.DFLTu 465. 466.It Sy MAKEOBJDIRPREFIX 467Top level directory of the object directory tree. 468The value is subjected to variable expansion by 469.Xr make 1 . 470.Sy build.sh 471will create the 472${MAKEOBJDIRPREFIX} 473directory if necessary, but if 474.Xr make 1 475is used without 476.Sy build.sh , 477then rules in 478.Aq bsd.obj.mk 479will abort the build if the 480${MAKEOBJDIRPREFIX} 481directory does not exist. 482If the value is defined and valid, then 483${MAKEOBJDIRPREFIX}/${.CURDIR} 484is used as the 485.Sy .OBJDIR 486for the current directory. 487The current directory may be read only. 488.Pp 489.Em Note : 490.Sy MAKEOBJDIRPREFIX 491can be provided only in the environment or via the 492.Fl M 493flag of 494.Sy build.sh ; 495it cannot usefully be set inside a Makefile, including in 496.Xr mk.conf 5 497or 498.Sy MAKECONF . 499.DFLTu 500. 501.It Ev TMPDIR 502Top-level directory to store temporary directories used by 503.Sy build.sh 504before paths to other directories such as 505.Sy .OBJDIR 506can be determined. 507.Pp 508.Em Note : 509Must support execution of binaries. 510I.e., without 511.Xr mount 8 Ns 's 512.Fl o 513.Cm noexec 514option. 515.DFLT 516.Dq Pa /tmp . 517. 518.El 519. 520.Ss make variables 521. 522Variables that control the behavior of 523.Nx 524builds are documented in 525.Xr mk.conf 5 526(whose 527.Xr mdoc 7 528source is in 529.Pa share/man/man5/mk.conf.5 ) . 530.Pp 531Unless otherwise specified, these variables may be set in 532either the process environment or the 533.Xr make 1 534configuration file 535.Xr mk.conf 5 536specified by 537.Sy MAKECONF . 538.Pp 539.Em Note : 540Variables set in the environment, either directly or via 541.Sy build.sh 542options to set specific values in the 543.Sy \*[toolprefix]make- Ns Sy MACHINE 544wrapper script do not override variables set in the 545.Xr mk.conf 5 546file. 547To allow variables in 548.Xr mk.conf 5 549to be overridden by the environment or 550.Sy build.sh 551options, define the variables using the 552.Dq Li ?= 553.Xr make 1 554variable assignment operator. 555For example, 556.Bd -unfilled -offset indent 557.Li MAKEVERBOSE?=1 558.Ed 559.Pp 560The supported 561.Xr mk.conf 5 562make variables are: 563.\" Keep in sync with share/man/man5/mk.conf.5 section NETBSD SYSTEM VARIABLES 564.Bd -ragged -offset indent 565.Sy BSDOBJDIR , 566.Sy BSDSRCDIR , 567.Sy BUILD , 568.Sy BUILDID , 569.Sy BUILDINFO , 570.Sy BUILDSEED , 571.Sy CDEXTRA , 572.Sy CONFIGOPTS , 573.Sy COPTS , 574.Sy CPUFLAGS , 575.Sy DESTDIR , 576.Sy EXTERNAL_TOOLCHAIN , 577.Sy INSTALLBOOT_BOARDS , 578.Sy INSTALLWORLDDIR , 579.Sy KERNARCHDIR , 580.Sy KERNCONFDIR , 581.Sy KERNEL_DIR , 582.Sy KERNOBJDIR , 583.Sy KERNSRCDIR , 584.Sy LOCALTIME , 585.Sy MAKEVERBOSE , 586.Sy MKAMDGPUFIRMWARE , 587.Sy MKARGON2 , 588.Sy MKARZERO , 589.Sy MKATF , 590.Sy MKBINUTILS , 591.Sy MKBSDGREP , 592.Sy MKBSDTAR , 593.Sy MKCATPAGES , 594.Sy MKCLEANSRC , 595.Sy MKCLEANVERIFY , 596.Sy MKCOMPAT , 597.Sy MKCOMPATMODULES , 598.Sy MKCOMPATTESTS , 599.Sy MKCOMPATX11 , 600.Sy MKCOMPLEX , 601.Sy MKCROSSGDB , 602.Sy MKCTF , 603.Sy MKCVS , 604.Sy MKCXX , 605.Sy MKDEBUG , 606.Sy MKDEBUGKERNEL , 607.Sy MKDEBUGLIB , 608.Sy MKDEBUGTOOLS , 609.Sy MKDEPINCLUDES , 610.Sy MKDOC , 611.Sy MKDTB , 612.Sy MKDTC , 613.Sy MKDTRACE , 614.Sy MKDYNAMICROOT , 615.Sy MKFIRMWARE , 616.Sy MKGCC , 617.Sy MKGCCCMDS , 618.Sy MKGDB , 619.Sy MKGROFF , 620.Sy MKGROFFHTMLDOC , 621.Sy MKHESIOD , 622.Sy MKHOSTOBJ , 623.Sy MKHTML , 624.Sy MKIEEEFP , 625.Sy MKINET6 , 626.Sy MKINFO , 627.Sy MKIPFILTER , 628.Sy MKISCSI , 629.Sy MKKERBEROS , 630.Sy MKKMOD , 631.Sy MKKYUA , 632.Sy MKLDAP , 633.Sy MKLIBCSANITIZER , 634.Sy MKLIBCXX , 635.Sy MKLIBSTDCXX , 636.Sy MKLINKLIB , 637.Sy MKLINT , 638.Sy MKLLVM , 639.Sy MKLLVMRT , 640.Sy MKLVM , 641.Sy MKMAKEMANDB , 642.Sy MKMAN , 643.Sy MKMANDOC , 644.Sy MKMANZ , 645.Sy MKMDNS , 646.Sy MKNLS , 647.Sy MKNOUVEAUFIRMWARE , 648.Sy MKNPF , 649.Sy MKNSD , 650.Sy MKOBJ , 651.Sy MKOBJDIRS , 652.Sy MKPAM , 653.Sy MKPCC , 654.Sy MKPF , 655.Sy MKPIC , 656.Sy MKPICINSTALL , 657.Sy MKPICLIB , 658.Sy MKPIE , 659.Sy MKPIGZGZIP , 660.Sy MKPOSTFIX , 661.Sy MKPROFILE , 662.Sy MKRADEONFIRMWARE , 663.Sy MKRELRO , 664.Sy MKREPRO , 665.Sy MKREPRO_TIMESTAMP , 666.Sy MKRUMP , 667.Sy MKSANITIZER , 668.Sy MKSHARE , 669.Sy MKSKEY , 670.Sy MKSLJIT , 671.Sy MKSOFTFLOAT , 672.Sy MKSTATICLIB , 673.Sy MKSTATICPIE , 674.Sy MKSTRIPIDENT , 675.Sy MKSTRIPSYM , 676.Sy MKTEGRAFIRMWARE , 677.Sy MKTPM , 678.Sy MKUNBOUND , 679.Sy MKUNPRIVED , 680.Sy MKUPDATE , 681.Sy MKX11 , 682.Sy MKX11FONTS , 683.Sy MKX11MOTIF , 684.Sy MKXORG_SERVER , 685.Sy MKYP , 686.Sy MKZFS , 687.Sy NETBSDSRCDIR , 688.Sy NETBSD_OFFICIAL_RELEASE , 689.Sy NOCLEANDIR , 690.Sy NODISTRIBDIRS , 691.Sy NOINCLUDES , 692.Sy OBJMACHINE , 693.Sy RELEASEDIR , 694.Sy RUMPUSER_THREADS , 695.Sy RUMP_CURLWP , 696.Sy RUMP_DEBUG , 697.Sy RUMP_DIAGNOSTIC , 698.Sy RUMP_KTRACE , 699.Sy RUMP_LOCKDEBUG , 700.Sy RUMP_LOCKS_UP , 701.Sy RUMP_NBCOMPAT , 702.Sy RUMP_VIRTIF , 703.Sy RUMP_VNODE_LOCKDEBUG , 704.Sy TOOLCHAIN_MISSING , 705.Sy TOOLDIR , 706.Sy USETOOLS , 707.Sy USE_FORT , 708.Sy USE_HESIOD , 709.Sy USE_INET6 , 710.Sy USE_JEMALLOC , 711.Sy USE_KERBEROS , 712.Sy USE_LDAP , 713.Sy USE_LIBCSANITIZER , 714.Sy USE_PAM , 715.Sy USE_PIGZGZIP , 716.Sy USE_SANITIZER , 717.Sy USE_SKEY , 718.Sy USE_SSP , 719.Sy USE_XZ_SETS , 720.Sy USE_YP , 721.Sy X11MOTIFPATH , 722.Sy X11SRCDIR . 723.Ed 724.Pp 725The obsolete 726.Xr mk.conf 5 727make variables are: 728.\" Keep in sync with share/man/man5/mk.conf.5 section OBSOLETE VARIABLES 729.Bd -ragged -offset indent 730.Sy EXTSRCSRCDIR , 731.Sy MKBFD , 732.Sy MKCRYPTO , 733.Sy MKEXTSRC , 734.Sy MKKDEBUG , 735.Sy MKKERBEROS4 , 736.Sy MKLLD , 737.Sy MKLLDB , 738.Sy MKMCLINKER , 739.Sy MKPERFUSE , 740.Sy MKTOOLSDEBUG , 741.Sy NBUILDJOBS , 742.Sy SHAREDSTRINGS , 743.Sy USE_COMBINE , 744.Sy USE_NEW_TOOLCHAIN . 745.Ed 746. 747.Sh BUILDING 748. 749.Ss make command line options 750This is not a summary of all the options available to 751.Xr make 1 ; 752only the options used most frequently with 753.Nx 754builds are listed here. 755. 756.Bl -tag -width "var=value" 757. 758.It Fl j Ar njob 759Run up to 760.Ar njob 761.Xr make 1 762subjobs in parallel. 763Makefiles should use .WAIT or have explicit dependencies 764as necessary to enforce build ordering. 765. 766.It Fl m Ar dir 767Specify the default directory for searching for system Makefile 768segments, mainly the 769.Aq bsd.*.mk 770files. 771When building any full 772.Nx 773source tree, this should be set to the 774.Dq Pa share/mk 775directory in the source tree. 776This is set automatically when building from the top level, or when using 777.Sy build.sh . 778. 779.It Fl n 780Show the commands that would have been executed, but do not 781actually execute them. 782This will still cause recursion to take place. 783. 784.It Fl V Ar var 785Show 786.Xr make 1 Ns 's 787idea of the value of 788.Ar var . 789Does not build any targets. 790. 791.It Ar var Ns Sy = Ns Ar value 792Set the variable 793.Ar var 794to 795.Ar value , 796overriding any setting specified by the process environment, the 797.Sy MAKECONF 798configuration file, or the system Makefile segments. 799. 800.El 801. 802.Ss make targets 803. 804These default targets may be built by running 805.Xr make 1 806in any subtree of the 807.Nx 808source code. 809It is recommended that none of these be used from the top 810level Makefile; as a specific exception, 811.Dq make obj 812and 813.Dq make cleandir 814are useful in that context. 815. 816.Bl -tag -width "dependall" 817. 818.It Sy all 819Build programs, libraries, and preformatted documentation. 820. 821.It Sy clean 822Remove program and library object code files. 823. 824.It Sy cleandir 825Same as 826.Sy clean , 827but also remove preformatted documentation, dependency files generated 828by 829.Dq make depend , 830and any other files known to be created at build time. 831. 832.It Sy depend 833Create dependency files 834.Pa ( .depend ) 835containing more detailed information about the dependencies of source 836code on header files. 837Allows programs to be recompiled automatically when a dependency changes. 838. 839.It Sy dependall 840Does a 841.Dq make depend 842immediately followed by a 843.Dq make all . 844This improves cache locality of the build since both passes read the source 845files in their entirety. 846. 847.It Sy distclean 848Synonym for 849.Sy cleandir . 850. 851.It Sy includes 852Build and install system header files. 853Typically needed before any system libraries or programs can be built. 854. 855.It Sy install 856Install programs, libraries, and documentation into 857.Sy DESTDIR . 858Few files will be installed to 859.Sy DESTDIR Ns Pa /dev , 860.Sy DESTDIR Ns Pa /etc , 861.Sy DESTDIR Ns Pa /root 862or 863.Sy DESTDIR Ns Pa /var 864in order to prevent user supplied configuration data from being overwritten. 865.It Sy lint 866Run 867.Xr lint 1 868against the C source code, where appropriate, and generate 869system-installed lint libraries. 870. 871.It Sy obj 872Create object directories to be used for built files, instead of 873building directly in the source tree. 874. 875.It Sy tags 876Create 877.Xr ctags 1 878searchable function lists usable by the 879.Xr ex 1 880and 881.Xr vi 1 882text editors. 883. 884.El 885. 886.Ss make targets for the top level 887. 888Additional 889.Xr make 1 890targets are usable specifically from the top source level to facilitate 891building the entire 892.Nx 893source tree. 894. 895.Bl -tag -width "distribution" 896. 897.It Sy build 898Build the entire 899.Nx 900system (except the kernel). 901This orders portions of the source tree such that prerequisites 902will be built in the proper order. 903. 904.It Sy distribution 905Do a 906.Dq make build , 907and then install a full distribution (which does not include a kernel) into 908.Sy DESTDIR , 909including files in 910.Sy DESTDIR Ns Pa /dev , 911.Sy DESTDIR Ns Pa /etc , 912.Sy DESTDIR Ns Pa /root 913and 914.Sy DESTDIR Ns Pa /var . 915. 916.It Sy buildworld 917As per 918.Dq make distribution , 919except that it ensures that 920.Sy DESTDIR 921is not the root directory. 922. 923.It Sy installworld 924Install the distribution from 925.Sy DESTDIR 926to 927.Sy INSTALLWORLDDIR , 928which defaults to the root directory. 929Ensures that 930.Sy INSTALLWORLDDIR 931is not the root directory if cross compiling. 932.Pp 933The 934.Sy INSTALLSETS 935environment variable may be set to a space-separated list of 936distribution sets to be installed. 937By default, all sets except 938.Dq etc 939and 940.Dq xetc 941are installed, so most files in 942.Sy INSTALLWORLDDIR Ns Pa /etc 943will not be installed or modified. 944.Pp 945.Em Note : 946Before performing this operation with 947.Sy INSTALLWORLDDIR Ns = Ns Pa / , 948it is highly recommended that you upgrade your kernel and reboot. 949After performing this operation, 950it is recommended that you use 951.Xr etcupdate 8 952to update files in 953.Sy INSTALLWORLDDIR Ns Pa /etc , 954and 955.Xr postinstall 8 956to check for or fix inconsistencies. 957.It Sy sets 958Create distribution sets from 959.Sy DESTDIR 960into 961.Sy RELEASEDIR/RELEASEMACHINEDIR Ns Pa /binary/sets . 962Should be run after 963.Dq make distribution , 964as 965.Dq make build 966alone does not install all of the required files. 967. 968.It Sy sourcesets 969Create source sets of the source tree into 970.Sy RELEASEDIR Ns Pa /source/sets . 971. 972.It Sy syspkgs 973Create syspkgs from 974.Sy DESTDIR 975into 976.Sy RELEASEDIR/RELEASEMACHINEDIR Ns Pa /binary/syspkgs . 977Should be run after 978.Dq make distribution , 979as 980.Dq make build 981alone does not install all of the required files. 982. 983.It Sy release 984Do a 985.Dq make distribution , 986build kernels, distribution media, and install sets 987(this as per 988.Dq make sets ) , 989and 990then package the system into a standard release layout as described by 991.Xr release 7 . 992This requires that 993.Sy RELEASEDIR 994be set (see above). 995. 996.It Sy iso-image 997Create a 998.Nx 999installation CD-ROM image in the 1000.Sy RELEASEDIR Ns Pa /images 1001directory. 1002The CD-ROM file system will have a layout as described in 1003.Xr release 7 . 1004.Pp 1005For most machine types, the CD-ROM will be bootable, and will automatically 1006run the 1007.Xr sysinst 8 1008menu-based installation program, which can be used to install or upgrade a 1009.Nx 1010system. 1011Bootable CD-ROMs also contain tools that may be useful in 1012repairing a damaged 1013.Nx 1014installation. 1015.Pp 1016Before 1017.Dq make iso-image 1018is attempted, RELEASEDIR must be populated by 1019.Dq make release 1020or equivalent. 1021.Pp 1022.Em Note : 1023Other, smaller, CD-ROM images may be created in the 1024.Sy RELEASEDIR/RELEASEMACHINEDIR Ns Pa /installation/cdrom 1025directory by 1026.Dq "make release" . 1027These smaller images usually contain the same tools as the larger images in 1028.Sy RELEASEDIR Ns Pa /images , 1029but do not contain additional content such as the distribution sets. 1030.Pp 1031.Em Note : 1032The mac68k port still uses an older method of creating 1033CD-ROM images. 1034This requires the 1035.Xr mkisofs 1 1036utility, which is not part of 1037.Nx , 1038but which can be installed from 1039.Pa pkgsrc/sysutils/cdrtools . 1040. 1041.It Sy iso-image-source 1042Create a 1043.Nx 1044installation CD-ROM image in the 1045.Sy RELEASEDIR Ns Pa /images 1046directory. 1047The CD-ROM file system will have a layout as described in 1048.Xr release 7 . 1049It will have top level directories for the machine type and source. 1050.Pp 1051For most machine types, the CD-ROM will be bootable, and will automatically 1052run the 1053.Xr sysinst 8 1054menu-based installation program, which can be used to install or upgrade a 1055.Nx 1056system. 1057Bootable CD-ROMs also contain tools that may be useful in 1058repairing a damaged 1059.Nx 1060installation. 1061.Pp 1062Before 1063.Dq make iso-image-source 1064is attempted, RELEASEDIR must be populated by 1065.Dq make sourcesets release 1066or equivalent. 1067.Pp 1068.Em Note : 1069Other, smaller, CD-ROM images may be created in the 1070.Sy RELEASEDIR/RELEASEMACHINEDIR Ns Pa /installation/cdrom 1071directory by 1072.Dq make release . 1073These smaller images usually contain the same tools as the larger images in 1074.Sy RELEASEDIR Ns Pa /images , 1075but do not contain additional content such as the distribution sets. 1076.Pp 1077.Em Note : 1078The mac68k port still uses an older method of creating 1079CD-ROM images. 1080This requires the 1081.Xr mkisofs 1 1082utility, which is not part of 1083.Nx , 1084but which can be installed from 1085.Pa pkgsrc/sysutils/cdrtools . 1086. 1087.It Sy install-image 1088Create a bootable 1089.Nx 1090installation disk image in the 1091.Sy RELEASEDIR Ns Pa /images 1092directory. 1093The installation disk image is suitable for copying to 1094bootable USB flash memory sticks, etc., for machines which 1095are able to boot from such devices. 1096The file system in the bootable disk image will have a layout 1097as described in 1098.Xr release 7 . 1099.Pp 1100The installation image is bootable, and will automatically 1101run the 1102.Xr sysinst 8 1103menu-based installation program, which can be used to install or upgrade a 1104.Nx 1105system. 1106The image also contains tools that may be 1107useful in repairing a damaged 1108.Nx 1109installation. 1110.Pp 1111Before 1112.Dq make install-image 1113is attempted, 1114.Sy RELEASEDIR 1115must be populated by 1116.Dq make release 1117or equivalent. 1118The build must have been performed with 1119.Sy MKUNPRIVED=yes 1120because 1121.Dq make install-image 1122relies on information in 1123.Sy DESTDIR Ns Pa /METALOG . 1124. 1125.It Sy live-image 1126Create 1127.Nx 1128live images in the 1129.Sy RELEASEDIR/images 1130directory. 1131The live image contains all necessary files 1132to boot 1133.Nx 1134up to multi-user mode, including all files 1135which should be extracted during installation, 1136.Nx 1137disklabel, bootloaders, etc. 1138.Pp 1139The live image is suitable for use as a disk image in 1140virtual machine environments such as QEMU, 1141and also useful to boot 1142.Nx 1143from a USB flash memory stick 1144on a real machine, without the need for installation. 1145.Pp 1146Before 1147.Dq make live-image 1148is attempted, RELEASEDIR must be populated by 1149.Dq make release 1150or equivalent. 1151The build must have been performed with 1152.Sy MKUNPRIVED=yes 1153because 1154.Dq make install-image 1155relies on information in 1156.Sy DESTDIR Ns Pa /METALOG . 1157. 1158.It Sy regression-tests 1159Can only be run after building the regression tests in the directory 1160.Dq regress . 1161Runs those compiled regression tests on the local host. 1162.Pp 1163.Em Note : 1164Most tests are now managed instead using 1165.Xr atf 7 ; 1166this target should probably run those as well but currently does not. 1167. 1168.El 1169. 1170.Ss The build.sh script 1171. 1172This script file is a shell script designed to build the 1173entire 1174.Nx 1175system on any host with a suitable modern shell and some common 1176utilities. 1177The required shell features are described under the 1178.Sy HOST_SH 1179variable. 1180.Pp 1181If a host system's default shell does support the required 1182features, then we suggest that you explicitly specify 1183a suitable shell using a command like 1184.Bd -unfilled -offset indent 1185.Li /path/to/suitable/shell build.sh Op Ar options 1186.Ed 1187.Pp 1188The above command will usually enable 1189.Sy build.sh 1190to automatically set 1191.Sy HOST_SH Ns Cm = Ns Pa /path/to/suitable/shell , 1192but if that fails, then the following set of commands may be used instead: 1193.Bd -unfilled -offset indent 1194.Li HOST_SH= Ns Va /path/to/suitable/shell 1195.Li export HOST_SH 1196.Li ${HOST_SH} build.sh Op Ar options 1197.Ed 1198.Pp 1199If 1200.Sy build.sh 1201detects that it is being executed under an unsuitable shell, it attempts 1202to exec a suitable shell instead, or shows an error message. 1203If 1204.Sy HOST_SH 1205is not set explicitly, then 1206.Sy build.sh 1207sets a default using heuristics dependent on the host platform, 1208or from the shell under which 1209.Sy build.sh 1210is executed (if that can be determined), 1211or using the first copy of 1212.Pa sh 1213found in 1214.Ev PATH . 1215.Pp 1216All cross-compile builds, and most native builds, of the entire system 1217should make use of 1218.Sy build.sh 1219rather than just running 1220.Dq make . 1221This way, the 1222.Xr make 1 1223program will be bootstrapped properly, in case the host system has an 1224older or incompatible 1225.Dq make 1226program. 1227.Pp 1228When compiling the entire system via 1229.Sy build.sh , 1230many 1231.Xr make 1 1232variables are set for you in order to help encapsulate the build 1233process. 1234In the list of options below, variables that are automatically set by 1235.Sy build.sh 1236are noted where applicable. 1237. 1238.Pp 1239The following operations are supported by 1240.Sy build.sh : 1241. 1242.Bl -tag -width "distribution" 1243. 1244.It Sy build 1245Build the system as per 1246.Dq make build . 1247Before the main part of the build commences, this command runs the 1248.Sy obj 1249operation (unless the 1250.Fl o 1251option is given), 1252.Dq make cleandir 1253(unless the 1254.Fl u 1255option is given), 1256and the 1257.Sy tools 1258operation. 1259. 1260.It Sy distribution 1261Build a full distribution as per 1262.Dq make distribution . 1263This command first runs the 1264.Sy build 1265operation. 1266. 1267.It Sy release 1268Build a full release as per 1269.Dq make release . 1270This command first runs the 1271.Sy distribution 1272operation. 1273. 1274.It Sy help 1275Show a help message, and exit. 1276. 1277.It Sy makewrapper 1278Create the 1279.Sy \*[toolprefix]make- Ns Sy MACHINE 1280wrapper script. 1281This operation is automatically performed for any of the other 1282operations. 1283. 1284.It Sy cleandir 1285Perform 1286.Dq make cleandir . 1287. 1288.It Sy obj 1289Perform 1290.Dq make obj . 1291. 1292.It Sy tools 1293Build and install the host tools from 1294.Pa src/tools . 1295This command will first run 1296.Dq make obj 1297and 1298.Dq make cleandir 1299in the 1300.Pa tools 1301subdirectory unless the 1302.Fl o 1303or 1304.Fl u 1305options (respectively) are given. 1306. 1307.It Sy install Ns = Ns Ar idir 1308Install the contents of 1309.Sy DESTDIR 1310to 1311.Ar idir , 1312using 1313.Dq make installworld . 1314.Pp 1315.Em Note : 1316Files that are part of the 1317.Dq etc 1318or 1319.Dq xetc 1320sets will not be installed, unless overridden by 1321the INSTALLSETS environment variable. 1322. 1323.It Sy kernel Ns = Ns Ar kconf 1324Build a new kernel. 1325The 1326.Ar kconf 1327argument is the name of a configuration file suitable 1328for use by 1329.Xr config 1 . 1330If 1331.Ar kconf 1332does not contain any 1333.Sq / 1334characters, the configuration file is expected to be found in the 1335.Sy KERNCONFDIR 1336directory, which is typically 1337.Pa sys/arch/MACHINE/conf . 1338The new kernel will be built in a subdirectory of 1339.Sy KERNOBJDIR , 1340which is typically 1341.Pa sys/arch/ Ns Sy MACHINE Ns Pa /compile 1342or an associated object directory. 1343.Pp 1344This command does 1345.Em not 1346imply the 1347.Sy tools 1348command; run the 1349.Sy tools 1350command first unless it is 1351.Em certain 1352that the tools already exist and are up to date. 1353.Pp 1354This command will run 1355.Dq make cleandir 1356on the kernel in question first unless the 1357.Fl u 1358option is given. 1359. 1360.It Sy kernel.gdb Ns = Ns Ar kconf 1361Build a new kernel with debug information. 1362Similar to the above 1363.Sy kernel Ns = Ns Ar kconf 1364operation, but creates a 1365.Pa netbsd.gdb 1366file alongside of the kernel 1367.Pa netbsd , 1368which contains a full symbol table and can be used for debugging 1369(for example with a cross-gdb built by 1370.Sy MKCROSSGDB ) . 1371.It Sy kernels 1372This command will build all kernels defined in port specific release build 1373procedure. 1374.Pp 1375This command internally calls the 1376.Sy kernel Ns = Ns Ar kconf 1377operation for each found kernel configuration file. 1378.It Sy modules 1379This command will build kernel modules and install them into 1380.Sy DESTDIR . 1381. 1382.It Sy releasekernel Ns = Ns Ar kconf 1383Install a 1384.Xr gzip 1 Ns ed 1385copy of the kernel previously built by 1386.Sy kernel Ns = Ns Ar kconf 1387into 1388.Sy RELEASEDIR Ns Pa / Ns Sy RELEASEMACHINEDIR Ns Pa /binary/kernel , 1389usually as 1390.Pa netbsd- Ns Ar kconf Ns Pa .gz , 1391although the 1392.Dq Pa netbsd 1393prefix is determined from the 1394.Dq Sy config 1395directives in 1396.Ar kconf . 1397. 1398.It Sy sets 1399Perform 1400.Dq make sets . 1401. 1402.It Sy sourcesets 1403Perform 1404.Dq make sourcesets . 1405. 1406.It Sy syspkgs 1407Perform 1408.Dq make syspkgs . 1409. 1410.It Sy iso-image 1411Perform 1412.Dq make iso-image . 1413. 1414.It Sy iso-image-source 1415Perform 1416.Dq make iso-image-source . 1417. 1418.It Sy install-image 1419Perform 1420.Dq make install-image . 1421. 1422.It Sy live-image 1423Perform 1424.Dq make live-image . 1425. 1426.It Sy list-arch 1427Show a list of valid 1428.Sy MACHINE 1429and 1430.Sy MACHINE_ARCH 1431settings, the default 1432.Sy MACHINE_ARCH 1433for each 1434.Sy MACHINE , 1435and aliases for 1436.Sy MACHINE Ns No / Ns Sy MACHINE_ARCH 1437pairs, and then exits. 1438The 1439.Fl m 1440or 1441.Fl a 1442options (or both) may be used to specify glob patterns 1443that will be used to narrow the list of results; 1444for example, 1445.Dq Li build.sh -m 'evb*' -a '*arm*' list-arch 1446will list all known 1447.Sy MACHINE Ns No / Ns Sy MACHINE_ARCH 1448values in which either 1449.Sy MACHINE 1450or 1451.Sy ALIAS 1452matches the pattern 1453.Ql evb* , 1454and 1455.Sy MACHINE_ARCH 1456matches the pattern 1457.Ql *arm* . 1458. 1459.El 1460. 1461.Pp 1462The following command line options alter the behaviour of the 1463.Sy build.sh 1464operations described above: 1465. 1466.Bl -tag -width "-T tools" 1467. 1468.It Fl a Ar arch 1469Set the value of 1470.Sy MACHINE_ARCH 1471to 1472.Ar arch . 1473See the 1474.Fl m 1475option for more information. 1476. 1477.It Fl B Ar buildid 1478Set the value of 1479.Sy BUILDID 1480to 1481.Ar buildid . 1482This will also append the build identifier to the name of the 1483.Sy \*[toolprefix]make- Ns Sy MACHINE 1484wrapper script so that the resulting name is of the form 1485.Dq Sy \*[toolprefix]make- Ns Sy MACHINE Ns Sy -BUILDID . 1486. 1487.It Fl C Ar cdextras 1488Append 1489.Ar cdextras 1490to the 1491.Sy CDEXTRA 1492variable, 1493which is a space-separated list of files or directories that will be 1494added to the CD-ROM image that may be create by the 1495.Dq iso-image 1496or 1497.Dq iso-image-source 1498operations. 1499Files will be added to the root of the CD-ROM image, whereas directories 1500will be copied recursively. 1501If relative paths are specified, they will be converted to 1502absolute paths before being used. 1503Multiple paths may be specified via multiple 1504.Fl C 1505options, or via a single option whose argument contains multiple 1506space-separated paths. 1507. 1508.It Fl c Ar compiler 1509Select the compiler for the toolchain to build 1510.Nx 1511and for inclusion in the 1512.Nx 1513distribution. 1514Supported choices: 1515.Bl -inset -offset indent 1516.It clang 1517.It gcc 1518[default] 1519.El 1520.Pp 1521The compiler used to build the toolchain can be different; see 1522.Sy HOST_CC 1523and 1524.Sy HOST_CXX . 1525.It Fl D Ar dest 1526Set the value of 1527.Sy DESTDIR 1528to 1529.Ar dest . 1530If a relative path is specified, it will be converted to an 1531absolute path before being used. 1532. 1533.It Fl E 1534Set 1535.Sq expert 1536mode. 1537This overrides various sanity checks, and allows: 1538.Sy DESTDIR 1539does not have to be set to a non-root path for builds, 1540and 1541.Sy MKUNPRIVED=yes 1542does not have to be set when building as a non-root user. 1543.Pp 1544.Em Note : 1545It is highly recommended that you know what you are doing when 1546you use this option. 1547. 1548.It Fl h 1549Show a help message, and exit. 1550. 1551.It Fl j Ar njob 1552Run up to 1553.Ar njob 1554.Xr make 1 1555subjobs in parallel; 1556passed through to 1557.Xr make 1 . 1558If you see failures for reasons other than running out of memory 1559while using 1560.Sy build.sh 1561with 1562.Fl j , 1563please save complete build logs 1564so the failures can be analyzed. 1565.Pp 1566To achieve the fastest builds, 1567.Fl j 1568values between (1 + the number of CPUs) and (2 * the number of CPUs) 1569are recommended. 1570Use lower values on machines with limited memory or I/O bandwidth. 1571. 1572.It Fl M Ar obj 1573Set 1574.Sy MAKEOBJDIRPREFIX 1575to 1576.Ar obj . 1577Unsets 1578.Sy MAKEOBJDIR . 1579See 1580.Dq Fl O Ar obj 1581for more information. 1582.Pp 1583For instance, if the source directory is 1584.Pa /usr/src , 1585a setting of 1586.Dq Fl M Pa /usr/obj 1587will place build-time files under 1588.Pa /usr/obj/usr/src/bin , 1589.Pa /usr/obj/usr/src/lib , 1590.Pa /usr/obj/usr/src/usr.bin , 1591and so forth. 1592.Pp 1593If a relative path is specified, it will be converted to an 1594absolute path before being used. 1595.Sy build.sh 1596imposes the restriction that the argument to the 1597.Fl M 1598option must not begin with a 1599.Dq \&$ 1600(dollar sign) 1601character; otherwise it would be too difficult 1602to determine whether the value is an absolute or a relative path. 1603If the directory does not already exist, 1604.Sy build.sh 1605will create it. 1606. 1607.It Fl m Ar mach 1608Set the value of 1609.Sy MACHINE 1610to 1611.Ar mach , 1612unless the 1613.Ar mach 1614argument is an alias that refers to a 1615.Sy MACHINE Ns No / Ns Sy MACHINE_ARCH 1616pair, in which case both 1617.Sy MACHINE 1618and 1619.Sy MACHINE_ARCH 1620are set from the alias. 1621Such aliases are interpreted entirely by 1622.Sy build.sh ; 1623they are not used by any other part of the build system. 1624The 1625.Sy MACHINE_ARCH 1626setting implied by 1627.Ar mach 1628will override any value of 1629.Sy MACHINE_ARCH 1630in the process environment, but will not override a value set by the 1631.Fl a 1632option. 1633All cross builds require 1634.Fl m , 1635but if unset on a NetBSD host, the host's value of MACHINE will be 1636detected and used automatically. 1637.Pp 1638See the 1639.Cm list-arch 1640operation for a way to get a list of valid 1641.Sy MACHINE 1642and 1643.Sy MACHINE_ARCH 1644settings. 1645. 1646.It Fl N Ar noiselevel 1647Set the 1648.Dq noisyness 1649level of the build, by setting 1650.Sy MAKEVERBOSE 1651to 1652.Ar noiselevel . 1653. 1654.It Fl n 1655Show the commands that would be executed by 1656.Sy build.sh , 1657but do not make any changes. 1658This is similar in concept to 1659.Dq make -n . 1660. 1661.It Fl O Ar obj 1662Create an appropriate transform macro for 1663.Sy MAKEOBJDIR 1664that will place the built object files under 1665.Ar obj . 1666Unsets 1667.Sy MAKEOBJDIRPREFIX . 1668.Pp 1669For instance, a setting of 1670.Dq Fl O Pa /usr/obj 1671will place build-time files under 1672.Pa /usr/obj/bin , 1673.Pa /usr/obj/lib , 1674.Pa /usr/obj/usr.bin , 1675and so forth. 1676.Pp 1677If a relative path is specified, it will be converted to an 1678absolute path before being used. 1679.Sy build.sh 1680imposes the restriction that the argument to the 1681.Fl O 1682option must not contain a 1683.Dq \&$ 1684(dollar sign) 1685character. 1686If the directory does not already exist, 1687.Sy build.sh 1688will create it. 1689.Pp 1690In normal use, exactly one of the 1691.Fl M 1692or 1693.Fl O 1694options should be specified. 1695If neither 1696.Fl M 1697nor 1698.Fl O 1699is specified, then a default object directory will be chosen 1700according to rules in 1701.Aq bsd.obj.mk . 1702Relying on this default is not recommended because 1703it is determined by complex rules that are influenced 1704by the values of several variables and 1705by the location of the source directory. 1706.Pp 1707.Em Note : 1708Placing the 1709.Ar obj 1710directory location outside of the default source tree hierarchy makes 1711it easier to manually clear out old files in the event the 1712.Dq make cleandir 1713operation is unable to do so. 1714(See 1715.Sx CAVEATS 1716below.) 1717.Pp 1718.Em Note : 1719The use of one of 1720.Fl M 1721or 1722.Fl O 1723is the only means of building multiple machine architecture userlands 1724from the same source tree without cleaning between builds (in which 1725case, one would specify distinct 1726.Ar obj 1727locations for each). 1728. 1729.It Fl o 1730Set the value of 1731.Sy MKOBJDIRS 1732to 1733.Dq no . 1734Otherwise, it will be automatically set to 1735.Dq yes . 1736This default is opposite to the behaviour when not using 1737.Sy build.sh . 1738. 1739.It Fl P 1740Set the value of 1741.Sy MKREPRO 1742and 1743.Sy MKREPRO_TIMESTAMP 1744to the latest source CVS timestamp for reproducible builds. 1745. 1746.It Fl R Ar rel 1747Set the value of 1748.Sy RELEASEDIR 1749to 1750.Ar rel . 1751If a relative path is specified, it will be converted to an 1752absolute path before being used. 1753. 1754.It Fl r 1755Remove the contents of 1756.Sy DESTDIR 1757and 1758.Sy TOOLDIR 1759before building (provides a clean starting point). 1760This will skip deleting 1761.Sy DESTDIR 1762if building on a native system to the root directory. 1763. 1764.It Fl S Ar seed 1765Change the value of 1766.Sy BUILDSEED 1767to 1768.Ar seed . 1769This should rarely be necessary. 1770. 1771.It Fl T Ar tools 1772Set the value of 1773.Sy TOOLDIR 1774to 1775.Ar tools . 1776If a relative path is specified, it will be converted to an 1777absolute path before being used. 1778If set, the bootstrap 1779.Dq make 1780will only be rebuilt if the source files for 1781.Xr make 1 1782have changed. 1783. 1784.It Fl U 1785Set 1786.Sy MKUNPRIVED=yes . 1787. 1788.It Fl u 1789Set 1790.Sy MKUPDATE=yes . 1791. 1792.It Xo 1793.Fl V 1794.Sm off 1795.Ar var 1796.Li = 1797.Op Ar value 1798.Sm on 1799.Xc 1800Set the environment variable 1801.Ar var 1802to an optional 1803.Ar value . 1804This is propagated to the 1805.Sy \*[toolprefix]make- Ns Sy MACHINE 1806wrapper script. 1807. 1808.It Fl w Ar wrapper 1809Create the 1810.Sy \*[toolprefix]make- Ns Sy MACHINE 1811wrapper script (see below) in a custom location, 1812specified by 1813.Ar wrapper . 1814This allows, for instance, to place the wrapper script in 1815.Ev PATH 1816automatically. 1817.Pp 1818.Em Note : 1819.Ar wrapper 1820is the full name of the file, not just a directory name. 1821If a relative path is specified, it will be converted to an 1822absolute path before being used. 1823. 1824.It Fl X Ar x11src 1825Set the value of 1826.Sy X11SRCDIR 1827to 1828.Ar x11src . 1829If a relative path is specified, it will be converted to an 1830absolute path before being used. 1831. 1832.It Fl x 1833Set 1834.Sy MKX11=yes . 1835. 1836.It Fl Z Ar var 1837Unset ("zap") the environment variable 1838.Ar var . 1839This is propagated to the 1840.Sy \*[toolprefix]make- Ns Sy MACHINE 1841wrapper script. 1842. 1843.It Fl ? 1844Show a help message, and exit. 1845. 1846.El 1847. 1848.Ss The \*[toolprefix]make-MACHINE wrapper script 1849. 1850If using the 1851.Sy build.sh 1852script to build 1853.Nx , 1854a 1855.Sy \*[toolprefix]make-MACHINE 1856wrapper script will be created in 1857.Sy TOOLDIR Ns Pa /bin 1858upon the first build to assist in building subtrees on a cross-compile 1859host. 1860.Pp 1861The 1862.Sy \*[toolprefix]make-MACHINE 1863wrapper script can be invoked in lieu of 1864.Xr make 1 , 1865and will instead call the up-to-date version of 1866.Dq \*[toolprefix]make 1867installed into 1868.Sy TOOLDIR Ns Pa /bin 1869with several key variables pre-set, including 1870.Sy MACHINE , MACHINE_ARCH , 1871and 1872.Sy TOOLDIR . 1873.Sy \*[toolprefix]make-MACHINE 1874will also set variables specified with 1875.Fl V , 1876and unset variables specified with 1877.Fl Z . 1878Note that by default these variables will not override 1879.Xr mk.conf 5 ; 1880see 1881.Sx make variables 1882for more details. 1883.Pp 1884This wrapper script can be symlinked into a directory listed in 1885.Ev PATH , 1886or called with an absolute path. 1887. 1888.Sh EXAMPLES 1889. 1890.Bl -enum 1891. 1892.It 1893.Li "% ./build.sh [OPTIONS] tools kernel=GENERIC" 1894.Pp 1895Build a new toolchain, and use the new toolchain to 1896configure and build a new GENERIC kernel. 1897. 1898.It 1899.Li "% ./build.sh [OPTIONS] -U distribution" 1900.Pp 1901Using unprivileged mode, 1902build a complete distribution to a 1903.Sy DESTDIR 1904directory that 1905.Sy build.sh 1906selects (and will show). 1907. 1908.It 1909.Li "# ./build.sh [OPTIONS] -U install=/" 1910.Pp 1911As root, install to 1912.Pa / 1913the distribution that was built 1914by example 2. 1915Even though this is run as root, 1916.Fl U 1917is required so that the permissions stored in 1918.Sy DESTDIR Ns Pa /METALOG 1919are correctly applied to the files as they're copied to 1920.Pa / . 1921. 1922.It 1923.Li "% ./build.sh [OPTIONS] -U -u release" 1924.Pp 1925Using unprivileged mode, 1926build a complete release to 1927.Sy DESTDIR 1928and 1929.Sy RELEASEDIR 1930directories that 1931.Sy build.sh 1932selects (and will show). 1933.Sy MKUPDATE=yes 1934.Pq Fl u 1935is set to prevent the 1936.Dq make cleandir , 1937so that if this is run after example 2, it doesn't need to redo that 1938portion of the release build. 1939.El 1940. 1941.Sh SEE ALSO 1942.Xr config 1 , 1943.Xr ctags 1 , 1944.Xr ex 1 , 1945.Xr gzip 1 , 1946.Xr lint 1 , 1947.Xr make 1 , 1948.Xr mandoc 1 , 1949.Xr mkisofs 1 , 1950.Xr nroff 1 , 1951.Xr vi 1 , 1952.Xr mk.conf 5 , 1953.Xr atf 7 , 1954.Xr hier 7 , 1955.Xr mdoc 7 , 1956.Xr release 7 , 1957.Xr etcupdate 8 , 1958.Xr installboot 8 , 1959.Xr mount 8 , 1960.Xr postinstall 8 , 1961.Xr sysinst 8 , 1962.Pa pkgsrc/sysutils/cdrtools 1963.Pp 1964.Em Note : 1965The 1966.Nx 1967manual pages are also available at 1968.Lk https://man.netbsd.org 1969. 1970.Sh HISTORY 1971. 1972The 1973.Sy build.sh 1974based build scheme was introduced for 1975.Nx 1.6 1976as 1977.Sy USE_NEW_TOOLCHAIN , 1978and re-worked to 1979.Sy TOOLCHAIN_MISSING 1980after that. 1981. 1982.Sh CAVEATS 1983. 1984After significant updates to third-party components in the source 1985tree, the 1986.Dq make cleandir 1987operation may be insufficient to clean out old files in object 1988directories. 1989Instead, one may have to manually remove the files. 1990Consult the 1991.Pa UPDATING 1992file for notices concerning this. 1993