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