1.\" $NetBSD: BUILDING.mdoc,v 1.122 2017/10/21 22:03:01 sevan 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.DFLTy 616. 617.It Sy MKPICINSTALL 618.YorN 619Indicates whether the 620.Xr ar 1 621format libraries 622.Sy ( lib*_pic.a ) , 623used to generate shared libraries, are installed during a build. 624.DFLTy 625. 626.It Sy MKPROFILE 627.YorN 628Indicates whether profiled libraries 629.Sy ( lib*_p.a ) 630will be built and installed during a build. 631.DFLT 632.Dq yes ; 633however, some platforms turn off 634.Sy MKPROFILE 635by default at times due to toolchain problems with profiled code. 636. 637.It Sy MKREPRO 638.YorN 639Create reproducible builds. 640This enables different switches to make two builds from the same 641source tree result in the same build results. 642.DFLTn 643This may be set to 644.Dq yes 645by giving 646.Sy build.sh 647the 648.Fl P 649option. 650. 651.It Sy MKREPRO_TIMESTAMP 652Unix timestamp. 653When 654.Sy MKREPRO 655is set, the timestamp of all files in the sets will be set 656to this value. 657.DFLTu 658This may be set automatically to the latest source tree timestamp 659using 660.Xr cvslatest 1 661by giving 662.Sy build.sh 663the 664.Fl P 665option. 666. 667.It Sy MKSHARE 668.YorN 669Indicates whether files destined to reside in 670.Sy DESTDIR Ns Pa /usr/share 671will be built and installed during a build. 672If set to 673.Dq no , 674then all of 675.Sy MKCATPAGES , MKDOC , MKINFO , MKMAN , 676and 677.Sy MKNLS 678will be set to 679.Dq no 680unconditionally. 681.DFLTy 682. 683.It Sy MKSTRIPIDENT 684.YorN 685Indicates whether RCS IDs, for use with 686.Xr ident 1 , 687should be stripped from program binaries and shared libraries. 688.DFLTn 689. 690.It Sy MKSTRIPSYM 691.YorN 692Indicates whether all local symbols should be stripped from shared libraries. 693If 694.Dq yes , 695strip all local symbols from shared libraries; 696the affect is equivalent to the 697.Fl x 698option of 699.Xr ld 1 . 700If 701.Dq no , 702strip only temporary local symbols; the affect is equivalent 703to the 704.Fl X 705option of 706.Xr ld 1 . 707Keeping non-temporary local symbols 708such as static function names is useful on using DTrace for 709userland libraries and getting a backtrace from a rump kernel 710loading shared libraries. 711.DFLTy 712. 713.It Sy MKUNPRIVED 714.YorN 715Indicates whether an unprivileged install will occur. 716The user, group, permissions, and file flags, will not be set on 717the installed items; instead the information will be appended to 718a file called 719.Pa METALOG 720in 721.Sy DESTDIR . 722The contents of 723.Pa METALOG 724are used during the generation of the distribution tar files to ensure 725that the appropriate file ownership is stored. 726.DFLTn 727. 728.It Sy MKUPDATE 729.YorN 730Indicates whether all install operations intended to write to 731.Sy DESTDIR 732will compare file timestamps before installing, and skip the install 733phase if the destination files are up-to-date. 734This also has implications on full builds (see next subsection). 735.DFLTn 736. 737.It Sy MKX11 738.YorN 739Indicates whether X11 is built from 740.Sy X11SRCDIR . 741.DFLTn 742. 743.It Sy TOOLDIR 744Directory to hold the host tools, once built. 745If specified, must be an absolute path. 746This directory should be unique to a given host system and 747.Nx 748source tree. 749(However, multiple targets may share the same 750.Sy TOOLDIR ; 751the target-dependent files have unique names.) If unset, a default based 752on the 753.Xr uname 1 754information of the host platform will be created in the 755.Sy .OBJDIR 756of 757.Pa src . 758.DFLTu 759. 760.It Sy USETOOLS 761Indicates whether the tools specified by 762.Sy TOOLDIR 763should be used as part of a build in progress. 764Must be set to 765.Dq yes 766if cross-compiling. 767.Bl -tag -width "never" 768.It Sy yes 769Use the tools from 770.Sy TOOLDIR . 771.It Sy no 772Do not use the tools from 773.Sy TOOLDIR , 774but refuse to build native compilation tool components that are 775version-specific for that tool. 776.It Sy never 777Do not use the tools from 778.Sy TOOLDIR , 779even when building native tool components. 780This is similar to the traditional 781.Nx 782build method, but does 783.Em not 784verify that the compilation tools in use are up-to-date enough in order 785to build the tree successfully. 786This may cause build or runtime problems when building the whole 787.Nx 788source tree. 789.El 790.DFLT 791.Dq yes , 792unless 793.Sy TOOLCHAIN_MISSING 794is set to 795.Dq yes . 796.Pp 797.Sy USETOOLS 798is also set to 799.Dq no 800when using 801.Aq bsd.*.mk 802outside the 803.Nx 804source tree. 805. 806.It Sy X11SRCDIR 807Directory containing the modular Xorg source. 808If specified, must be an absolute path. 809The main modular Xorg source is found in 810.Sy X11SRCDIR Ns Pa /external/mit . 811.DFLT 812.Sy NETBSDRCDIR Ns Pa /../xsrc , 813if that exists; otherwise 814.Pa /usr/xsrc . 815. 816.El 817. 818.Ss \*qmake\*q variables for full builds 819These variables only affect the top level 820.Dq Makefile 821and do not affect manually building subtrees of the 822.Nx 823source code. 824. 825.Bl -tag -width "INSTALLWORLDDIR" 826. 827.It Sy INSTALLWORLDDIR 828Location for the 829.Dq make installworld 830target to install to. 831If specified, must be an absolute path. 832.DFLT 833.Dq / 834. 835.It Sy MKOBJDIRS 836.YorN 837Indicates whether object directories will be created automatically 838(via a 839.Dq make obj 840pass) at the start of a build. 841.DFLTn 842.Pp 843If using 844.Sy build.sh , 845the default is 846.Dq yes . 847This may be set back to 848.Dq no 849by giving 850.Sy build.sh 851the 852.Fl o 853option. 854. 855.It Sy MKUPDATE 856.YorN 857If set, then in addition to the effects described for 858.Sy MKUPDATE=yes 859above, this implies the effects of 860.Sy NOCLEANDIR 861(i.e., 862.Dq make cleandir 863is avoided). 864.DFLTn 865.Pp 866If using 867.Sy build.sh , 868this may be set by giving the 869.Fl u 870option. 871. 872.It Sy NBUILDJOBS 873Now obsolete. 874Use the 875.Xr make 1 876option 877.Fl j , 878instead. 879See below. 880.DFLTu 881. 882.It Sy NOCLEANDIR 883If set, avoids the 884.Dq make cleandir 885phase of a full build. 886This has the effect of allowing only changed 887files in a source tree to be recompiled. 888This can speed up builds when updating only a few files in the tree. 889.DFLTu 890.Pp 891See also 892.Sy MKUPDATE . 893. 894.It Sy NODISTRIBDIRS 895If set, avoids the 896.Dq make distrib-dirs 897phase of a full build. 898This skips running 899.Xr mtree 8 900on 901.Sy DESTDIR , 902useful on systems where building as an unprivileged user, or where it is 903known that the system-wide mtree files have not changed. 904.DFLTu 905. 906.It Sy NOINCLUDES 907If set, avoids the 908.Dq make includes 909phase of a full build. 910This has the effect of preventing 911.Xr make 1 912from thinking that some programs are out-of-date simply because the 913system include files have changed. 914However, this option should not be used when updating the entire 915.Nx 916source tree arbitrarily; it is suggested to use 917.Sy MKUPDATE=yes 918instead in that case. 919.DFLTu 920. 921.It Sy RELEASEDIR 922If set, specifies the directory to which a 923.Xr release 7 924layout will be written at the end of a 925.Dq make release . 926If specified, must be an absolute path. 927.DFLTu 928.Pp 929.Em Note : 930.Sy build.sh 931will provide a default of 932.Pa releasedir 933(in the top-level 934.Sy .OBJDIR ) 935unless run in 936.Sq expert 937mode. 938. 939.El 940. 941.Sh BUILDING 942. 943.Ss \*qmake\*q command line options 944This is not a summary of all the options available to 945.Xr make 1 ; 946only the options used most frequently with 947.Nx 948builds are listed here. 949. 950.Bl -tag -width "var=value" 951. 952.It Fl j Ar njob 953Run up to 954.Ar njob 955.Xr make 1 956subjobs in parallel. 957Makefiles should use .WAIT or have explicit dependencies 958as necessary to enforce build ordering. 959. 960.It Fl m Ar dir 961Specify the default directory for searching for system Makefile 962segments, mainly the 963.Aq bsd.*.mk 964files. 965When building any full 966.Nx 967source tree, this should be set to the 968.Dq Pa share/mk 969directory in the source tree. 970This is set automatically when building from the top level, or when using 971.Sy build.sh . 972. 973.It Fl n 974Display the commands that would have been executed, but do not 975actually execute them. 976This will still cause recursion to take place. 977. 978.It Fl V Ar var 979Print 980.Xr make 1 Ns 's 981idea of the value of 982.Ar var . 983Does not build any targets. 984. 985.It Em var=value 986Set the variable 987.Em var 988to 989.Em value , 990overriding any setting specified by the process environment, the 991.Sy MAKECONF 992configuration file, or the system Makefile segments. 993. 994.El 995. 996.Ss \*qmake\*q targets 997. 998These default targets may be built by running 999.Xr make 1 1000in any subtree of the 1001.Nx 1002source code. 1003It is recommended that none of these be used from the top 1004level Makefile; as a specific exception, 1005.Dq make obj 1006and 1007.Dq make cleandir 1008are useful in that context. 1009. 1010.Bl -tag -width "dependall" 1011. 1012.It Sy all 1013Build programs, libraries, and preformatted documentation. 1014. 1015.It Sy clean 1016Remove program and library object code files. 1017. 1018.It Sy cleandir 1019Same as 1020.Sy clean , 1021but also remove preformatted documentation, dependency files generated 1022by 1023.Dq make depend , 1024and any other files known to be created at build time. 1025. 1026.It Sy depend 1027Create dependency files 1028.Sy ( .depend ) 1029containing more detailed information about the dependencies of source 1030code on header files. 1031Allows programs to be recompiled automatically when a dependency changes. 1032. 1033.It Sy dependall 1034Does a 1035.Dq make depend 1036immediately followed by a 1037.Dq make all . 1038This improves cache locality of the build since both passes read the source 1039files in their entirety. 1040. 1041.It Sy distclean 1042Synonym for 1043.Sy cleandir . 1044. 1045.It Sy includes 1046Build and install system header files. 1047Typically needed before any system libraries or programs can be built. 1048. 1049.It Sy install 1050Install programs, libraries, and documentation into 1051.Sy DESTDIR . 1052Few files will be installed to 1053.Sy DESTDIR Ns Pa /dev , 1054.Sy DESTDIR Ns Pa /etc , 1055.Sy DESTDIR Ns Pa /root 1056or 1057.Sy DESTDIR Ns Pa /var 1058in order to prevent user supplied configuration data from being overwritten. 1059.It Sy lint 1060Run 1061.Xr lint 1 1062against the C source code, where appropriate, and generate 1063system-installed lint libraries. 1064. 1065.It Sy obj 1066Create object directories to be used for built files, instead of 1067building directly in the source tree. 1068. 1069.It Sy tags 1070Create 1071.Xr ctags 1 1072searchable function lists usable by the 1073.Xr ex 1 1074and 1075.Xr vi 1 1076text editors. 1077. 1078.El 1079. 1080.Ss \*qmake\*q targets for the top level 1081. 1082Additional 1083.Xr make 1 1084targets are usable specifically from the top source level to facilitate 1085building the entire 1086.Nx 1087source tree. 1088. 1089.Bl -tag -width "distribution" 1090. 1091.It Sy build 1092Build the entire 1093.Nx 1094system (except the kernel). 1095This orders portions of the source tree such that prerequisites 1096will be built in the proper order. 1097. 1098.It Sy distribution 1099Do a 1100.Dq make build , 1101and then install a full distribution (which does not include a kernel) into 1102.Sy DESTDIR , 1103including files in 1104.Sy DESTDIR Ns Pa /dev , 1105.Sy DESTDIR Ns Pa /etc , 1106.Sy DESTDIR Ns Pa /root 1107and 1108.Sy DESTDIR Ns Pa /var . 1109. 1110.It Sy buildworld 1111As per 1112.Dq make distribution , 1113except that it ensures that 1114.Sy DESTDIR 1115is not the root directory. 1116. 1117.It Sy installworld 1118Install the distribution from 1119.Sy DESTDIR 1120to 1121.Sy INSTALLWORLDDIR , 1122which defaults to the root directory. 1123Ensures that 1124.Sy INSTALLWORLDDIR 1125is not the root directory if cross compiling. 1126.Pp 1127The 1128.Sy INSTALLSETS 1129environment variable may be set to a space-separated list of 1130distribution sets to be installed. 1131By default, all sets except 1132.Dq etc 1133and 1134.Dq xetc 1135are installed, so most files in 1136.Sy INSTALLWORLDDIR Ns Pa /etc 1137will not be installed or modified. 1138.Pp 1139.Em Note : 1140Before performing this operation with 1141.Sy INSTALLWORLDDIR Ns = Ns Pa / , 1142it is highly recommended that you upgrade your kernel and reboot. 1143After performing this operation, 1144it is recommended that you use 1145.Xr etcupdate 8 1146to update files in 1147.Sy INSTALLWORLDDIR Ns Pa /etc , 1148and 1149.Xr postinstall 8 1150to check for or fix inconsistencies. 1151.It Sy sets 1152Create distribution sets from 1153.Sy DESTDIR 1154into 1155.Sy RELEASEDIR/RELEASEMACHINEDIR Ns Pa /binary/sets . 1156Should be run after 1157.Dq make distribution , 1158as 1159.Dq make build 1160alone does not install all of the required files. 1161. 1162.It Sy sourcesets 1163Create source sets of the source tree into 1164.Sy RELEASEDIR Ns Pa /source/sets . 1165. 1166.It Sy syspkgs 1167Create syspkgs from 1168.Sy DESTDIR 1169into 1170.Sy RELEASEDIR/RELEASEMACHINEDIR Ns Pa /binary/syspkgs . 1171Should be run after 1172.Dq make distribution , 1173as 1174.Dq make build 1175alone does not install all of the required files. 1176. 1177.It Sy release 1178Do a 1179.Dq make distribution , 1180build kernels, distribution media, and install sets 1181(this as per 1182.Dq make sets ) , 1183and 1184then package the system into a standard release layout as described by 1185.Xr release 7 . 1186This requires that 1187.Sy RELEASEDIR 1188be set (see above). 1189. 1190.It Sy iso-image 1191Create a 1192.Nx 1193installation CD-ROM image in the 1194.Sy RELEASEDIR Ns Pa /images 1195directory. 1196The CD-ROM file system will have a layout as described in 1197.Xr release 7 . 1198.Pp 1199For most machine types, the CD-ROM will be bootable, and will automatically 1200run the 1201.Xr sysinst 8 1202menu-based installation program, which can be used to install or upgrade a 1203.Nx 1204system. 1205Bootable CD-ROMs also contain tools that may be useful in 1206repairing a damaged 1207.Nx 1208installation. 1209.Pp 1210Before 1211.Dq make iso-image 1212is attempted, RELEASEDIR must be populated by 1213.Dq make release 1214or equivalent. 1215.Pp 1216Note that other, smaller, CD-ROM images may be created in the 1217.Sy RELEASEDIR/RELEASEMACHINEDIR Ns Pa /installation/cdrom 1218directory by 1219.Dq "make release" . 1220These smaller images usually contain the same tools as the larger images in 1221.Sy RELEASEDIR Ns Pa /images , 1222but do not contain additional content such as the distribution sets. 1223.Pp 1224Note that the mac68k port still uses an older method of creating 1225CD-ROM images. 1226This requires the 1227.Xr mkisofs 1 1228utility, which is not part of 1229.Nx , 1230but which can be installed from 1231.Pa pkgsrc/sysutils/cdrtools . 1232. 1233.It Sy iso-image-source 1234Create a 1235.Nx 1236installation CD-ROM image in the 1237.Sy RELEASEDIR Ns Pa /images 1238directory. 1239The CD-ROM file system will have a layout as described in 1240.Xr release 7 . 1241It will have top level directories for the machine type and source. 1242.Pp 1243For most machine types, the CD-ROM will be bootable, and will automatically 1244run the 1245.Xr sysinst 8 1246menu-based installation program, which can be used to install or upgrade a 1247.Nx 1248system. 1249Bootable CD-ROMs also contain tools that may be useful in 1250repairing a damaged 1251.Nx 1252installation. 1253.Pp 1254Before 1255.Dq make iso-image-source 1256is attempted, RELEASEDIR must be populated by 1257.Dq make sourcesets release 1258or equivalent. 1259.Pp 1260Note that other, smaller, CD-ROM images may be created in the 1261.Sy RELEASEDIR/RELEASEMACHINEDIR Ns Pa /installation/cdrom 1262directory by 1263.Dq make release . 1264These smaller images usually contain the same tools as the larger images in 1265.Sy RELEASEDIR Ns Pa /images , 1266but do not contain additional content such as the distribution sets. 1267.Pp 1268Note that the mac68k port still uses an older method of creating 1269CD-ROM images. 1270This requires the 1271.Xr mkisofs 1 1272utility, which is not part of 1273.Nx , 1274but which can be installed from 1275.Pa pkgsrc/sysutils/cdrtools . 1276. 1277.It Sy install-image 1278Create a bootable 1279.Nx 1280installation disk image in the 1281.Sy RELEASEDIR Ns Pa /images 1282directory. 1283The installation disk image is suitable for copying to 1284bootable USB flash memory sticks, etc., for machines which 1285are able to boot from such devices. 1286The file system in the bootable disk image will have a layout 1287as described in 1288.Xr release 7 . 1289.Pp 1290The installation image is bootable, and will automatically 1291run the 1292.Xr sysinst 8 1293menu-based installation program, which can be used to install or upgrade a 1294.Nx 1295system. 1296The image also contains tools that may be 1297useful in repairing a damaged 1298.Nx 1299installation. 1300.Pp 1301Before 1302.Dq make install-image 1303is attempted, 1304.Sy RELEASEDIR 1305must be populated by 1306.Dq make release 1307or equivalent. 1308The build must have been performed with 1309.Sy MKUNPRIVED=yes 1310because 1311.Dq make install-image 1312relies on information in 1313.Sy DESTDIR Ns Pa /METALOG . 1314. 1315.It Sy live-image 1316Create 1317.Nx 1318live images in the 1319.Sy RELEASEDIR/images 1320directory. 1321The live image contains all necessary files 1322to boot 1323.Nx 1324up to multi-user mode, including all files 1325which should be extracted during installation, 1326.Nx 1327disklabel, bootloaders, etc. 1328.Pp 1329The live image is suitable for use as a disk image in 1330virtual machine environments such as QEMU, 1331and also useful to boot 1332.Nx 1333from a USB flash memory stick 1334on a real machine, without the need for installation. 1335.Pp 1336Before 1337.Dq make live-image 1338is attempted, RELEASEDIR must be populated by 1339.Dq make release 1340or equivalent. 1341The build must have been performed with 1342.Sy MKUNPRIVED=yes 1343because 1344.Dq make install-image 1345relies on information in 1346.Sy DESTDIR Ns Pa /METALOG . 1347. 1348.It Sy regression-tests 1349Can only be run after building the regression tests in the directory 1350.Dq regress . 1351Runs those compiled regression tests on the local host. 1352Note that most tests are now managed instead using 1353.Xr atf 7 ; 1354this target should probably run those as well but currently does not. 1355. 1356.El 1357. 1358.Ss The \*qbuild.sh\*q script 1359. 1360This script file is a shell script designed to build the 1361entire 1362.Nx 1363system on any host with a suitable modern shell and some common 1364utilities. 1365The required shell features are described under the 1366.Sy HOST_SH 1367variable. 1368.Pp 1369If a host system's default shell does support the required 1370features, then we suggest that you explicitly specify 1371a suitable shell using a command like 1372.Bd -unfilled -offset indent 1373.Li /path/to/suitable/shell build.sh Op Ar options 1374.Ed 1375.Pp 1376The above command will usually enable 1377.Nm build.sh 1378to automatically set 1379.Sy HOST_SH Ns Cm = Ns Pa /path/to/suitable/shell , 1380but if that fails, then the following set of commands may be used instead: 1381.Bd -unfilled -offset indent 1382.Li HOST_SH= Ns Va /path/to/suitable/shell 1383.Li export HOST_SH 1384.Li ${HOST_SH} build.sh Op Ar options 1385.Ed 1386.Pp 1387If 1388.Sy build.sh 1389detects that it is being executed under an unsuitable shell, it attempts 1390to exec a suitable shell instead, or prints an error message. 1391If 1392.Sy HOST_SH 1393is not set explicitly, then 1394.Nm build.sh 1395sets a default using heuristics dependent on the host platform, 1396or from the shell under which 1397.Nm build.sh 1398is executed (if that can be determined), 1399or using the first copy of 1400.Pa sh 1401found in 1402.Sy PATH . 1403.Pp 1404All cross-compile builds, and most native builds, of the entire system 1405should make use of 1406.Sy build.sh 1407rather than just running 1408.Dq make . 1409This way, the 1410.Xr make 1 1411program will be bootstrapped properly, in case the host system has an 1412older or incompatible 1413.Dq make 1414program. 1415.Pp 1416When compiling the entire system via 1417.Sy build.sh , 1418many 1419.Xr make 1 1420variables are set for you in order to help encapsulate the build 1421process. 1422In the list of options below, variables that are automatically set by 1423.Sy build.sh 1424are noted where applicable. 1425. 1426.Pp 1427The following operations are supported by 1428.Sy build.sh : 1429. 1430.Bl -tag -width "distribution" 1431. 1432.It Sy build 1433Build the system as per 1434.Dq make build . 1435Before the main part of the build commences, this command runs the 1436.Sy obj 1437operation (unless the 1438.Fl o 1439option is given), 1440.Dq make cleandir 1441(unless the 1442.Fl u 1443option is given), 1444and the 1445.Sy tools 1446operation. 1447. 1448.It Sy distribution 1449Build a full distribution as per 1450.Dq make distribution . 1451This command first runs the 1452.Sy build 1453operation. 1454. 1455.It Sy release 1456Build a full release as per 1457.Dq make release . 1458This command first runs the 1459.Sy distribution 1460operation. 1461. 1462.It Sy makewrapper 1463Create the 1464.Sy \*[toolprefix]make-MACHINE 1465wrapper. 1466This operation is automatically performed for any of the other 1467operations. 1468. 1469.It Sy cleandir 1470Perform 1471.Dq make cleandir . 1472. 1473.It Sy obj 1474Perform 1475.Dq make obj . 1476. 1477.It Sy tools 1478Build and install the host tools from 1479.Pa src/tools . 1480This command will first run 1481.Dq make obj 1482and 1483.Dq make cleandir 1484in the 1485.Pa tools 1486subdirectory unless the 1487.Fl o 1488or 1489.Fl u 1490options (respectively) are given. 1491. 1492.It Sy install Ns = Ns Ar idir 1493Install the contents of 1494.Sy DESTDIR 1495to 1496.Ar idir , 1497using 1498.Dq make installworld . 1499Note that files that are part of the 1500.Dq etc 1501or 1502.Dq xetc 1503sets will not be installed, unless overridden by 1504the INSTALLSETS environment variable. 1505. 1506.It Sy kernel Ns = Ns Ar kconf 1507Build a new kernel. 1508The 1509.Ar kconf 1510argument is the name of a configuration file suitable 1511for use by 1512.Xr config 1 . 1513If 1514.Ar kconf 1515does not contain any 1516.Sq / 1517characters, the configuration file is expected to be found in the 1518.Sy KERNCONFDIR 1519directory, which is typically 1520.Pa sys/arch/MACHINE/conf . 1521The new kernel will be built in a subdirectory of 1522.Sy KERNOBJDIR , 1523which is typically 1524.Pa sys/arch/MACHINE/compile 1525or an associated object directory. 1526.Pp 1527This command does 1528.Em not 1529imply the 1530.Sy tools 1531command; run the 1532.Sy tools 1533command first unless it is 1534.Em certain 1535that the tools already exist and are up to date. 1536.Pp 1537This command will run 1538.Dq make cleandir 1539on the kernel in question first unless the 1540.Fl u 1541option is given. 1542. 1543.It Sy kernel.gdb Ns = Ns Ar kconf 1544Build a new kernel with debug information. 1545Similar to the above 1546.Sy kernel Ns = Ns Ar kconf 1547operation, but creates a 1548.Pa netbsd.gdb 1549file alongside of the kernel 1550.Pa netbsd , 1551which contains a full symbol table and can be used for debugging 1552(for example with a cross-gdb built by 1553.Sy MKCROSSGDB ) . 1554.It Sy kernels 1555This command will build all kernels defined in port specific release build 1556procedure. 1557.Pp 1558This command internally calls the 1559.Sy kernel Ns = Ns Ar kconf 1560operation for each found kernel configuration file. 1561.It Sy modules 1562This command will build kernel modules and install them into 1563.Sy DESTDIR . 1564. 1565.It Sy releasekernel Ns = Ns Ar kconf 1566Install a 1567.Xr gzip 1 Ns ed 1568copy of the kernel previously built by 1569.Sy kernel Ns = Ns Ar kconf 1570into 1571.Sy RELEASEDIR/RELEASEMACHINEDIR Ns Pa /binary/kernel , 1572usually as 1573.Pa netbsd- Ns Ar kconf Ns Pa .gz , 1574although the 1575.Dq Pa netbsd 1576prefix is determined from the 1577.Dq Sy config 1578directives in 1579.Ar kconf . 1580. 1581.It Sy sets 1582Perform 1583.Dq make sets . 1584. 1585.It Sy sourcesets 1586Perform 1587.Dq make sourcesets . 1588. 1589.It Sy syspkgs 1590Perform 1591.Dq make syspkgs . 1592. 1593.It Sy iso-image 1594Perform 1595.Dq make iso-image . 1596. 1597.It Sy iso-image-source 1598Perform 1599.Dq make iso-image-source . 1600. 1601.It Sy install-image 1602Perform 1603.Dq make install-image . 1604. 1605.It Sy live-image 1606Perform 1607.Dq make live-image . 1608. 1609.It Sy list-arch 1610Prints a list of valid 1611.Sy MACHINE 1612and 1613.Sy MACHINE_ARCH 1614settings, the default 1615.Sy MACHINE_ARCH 1616for each 1617.Sy MACHINE , 1618and aliases for 1619.Sy MACHINE Ns No / Ns Sy MACHINE_ARCH 1620pairs, and then exits. 1621The 1622.Fl m 1623or 1624.Fl a 1625options (or both) may be used to specify glob patterns 1626that will be used to narrow the list of results; 1627for example, 1628.Dq Li build.sh -m 'evm*' -a '*arm*' list-arch 1629will list all known 1630.Sy MACHINE Ns No / Ns Sy MACHINE_ARCH 1631values in which either 1632.Sy MACHINE 1633or 1634.Sy ALIAS 1635matches the pattern 1636.Ql evb* , 1637and 1638.Sy MACHINE_ARCH 1639matches the pattern 1640.Ql *arm* . 1641. 1642.El 1643. 1644.Pp 1645The following command line options alter the behaviour of the 1646.Sy build.sh 1647operations described above: 1648. 1649.Bl -tag -width "-T tools" 1650. 1651.It Fl a Ar arch 1652Set the value of 1653.Sy MACHINE_ARCH 1654to 1655.Ar arch . 1656See the 1657.Fl m 1658option for more information. 1659. 1660.It Fl B Ar buildid 1661Set the value of 1662.Sy BUILDID 1663to 1664.Ar buildid . 1665This will also append the build identifier to the name of the 1666.Dq make 1667wrapper script so that the resulting name is of the form 1668.Dq Sy \*[toolprefix]make-MACHINE-BUILDID . 1669. 1670.It Fl C Ar cdextras 1671Append 1672.Ar cdextras 1673to the 1674.Sy CDEXTRA 1675variable, 1676which is a space-separated list of files or directories that will be 1677added to the CD-ROM image that may be create by the 1678.Dq iso-image 1679or 1680.Dq iso-image-source 1681operations. 1682Files will be added to the root of the CD-ROM image, whereas directories 1683will be copied recursively. 1684If relative paths are specified, they will be converted to 1685absolute paths before being used. 1686Multiple paths may be specified via multiple 1687.Fl C 1688options, or via a single option whose argument contains multiple 1689space-separated paths. 1690. 1691.It Fl D Ar dest 1692Set the value of 1693.Sy DESTDIR 1694to 1695.Ar dest . 1696If a relative path is specified, it will be converted to an 1697absolute path before being used. 1698. 1699.It Fl E 1700Set 1701.Sq expert 1702mode. 1703This overrides various sanity checks, and allows: 1704.Sy DESTDIR 1705does not have to be set to a non-root path for builds, 1706and 1707.Sy MKUNPRIVED=yes 1708does not have to be set when building as a non-root user. 1709.Pp 1710.Em Note : 1711It is highly recommended that you know what you are doing when 1712you use this option. 1713. 1714.It Fl h 1715Print a help message. 1716. 1717.It Fl j Ar njob 1718Run up to 1719.Ar njob 1720.Xr make 1 1721subjobs in parallel; 1722passed through to 1723.Xr make 1 . 1724If you see failures for reasons other than running out of memory 1725while using 1726.Sy build.sh 1727with 1728.Fl j , 1729please save complete build logs 1730so the failures can be analyzed. 1731.Pp 1732To achieve the fastest builds, 1733.Fl j 1734values between (1 + the number of CPUs) and (2 * the number of CPUs) 1735are recommended. 1736Use lower values on machines with limited memory or I/O bandwidth. 1737. 1738.It Fl M Ar obj 1739Set 1740.Sy MAKEOBJDIRPREFIX 1741to 1742.Ar obj . 1743Unsets 1744.Sy MAKEOBJDIR . 1745See 1746.Dq Fl O Ar obj 1747for more information. 1748.Pp 1749For instance, if the source directory is 1750.Pa /usr/src , 1751a setting of 1752.Dq Fl M Pa /usr/obj 1753will place build-time files under 1754.Pa /usr/obj/usr/src/bin , 1755.Pa /usr/obj/usr/src/lib , 1756.Pa /usr/obj/usr/src/usr.bin , 1757and so forth. 1758.Pp 1759If a relative path is specified, it will be converted to an 1760absolute path before being used. 1761.Sy build.sh 1762imposes the restriction that the argument to the 1763.Fl M 1764option must not begin with a 1765.Dq \&$ 1766(dollar sign) 1767character; otherwise it would be too difficult 1768to determine whether the value is an absolute or a relative path. 1769If the directory does not already exist, 1770.Sy build.sh 1771will create it. 1772. 1773.It Fl m Ar mach 1774Set the value of 1775.Sy MACHINE 1776to 1777.Ar mach , 1778unless the 1779.Ar mach 1780argument is an alias that refers to a 1781.Sy MACHINE Ns No / Ns Sy MACHINE_ARCH 1782pair, in which case both 1783.Sy MACHINE 1784and 1785.Sy MACHINE_ARCH 1786are set from the alias. 1787Such aliases are interpreted entirely by 1788.Sy build.sh ; 1789they are not used by any other part of the build system. 1790The 1791.Sy MACHINE_ARCH 1792setting implied by 1793.Ar mach 1794will override any value of 1795.Sy MACHINE_ARCH 1796in the process environment, but will not override a value set by the 1797.Fl a 1798option. 1799All cross builds require 1800.Fl m , 1801but if unset on a NetBSD host, the host's value of MACHINE will be 1802detected and used automatically. 1803.Pp 1804See the 1805.Cm list-arch 1806operation for a way to get a list of valid 1807.Sy MACHINE 1808and 1809.Sy MACHINE_ARCH 1810settings. 1811. 1812.It Fl N Ar noiselevel 1813Set the 1814.Dq noisyness 1815level of the build, by setting 1816.Sy MAKEVERBOSE 1817to 1818.Ar noiselevel . 1819. 1820.It Fl n 1821Show the commands that would be executed by 1822.Sy build.sh , 1823but do not make any changes. 1824This is similar in concept to 1825.Dq make -n . 1826. 1827.It Fl O Ar obj 1828Create an appropriate transform macro for 1829.Sy MAKEOBJDIR 1830that will place the built object files under 1831.Ar obj . 1832Unsets 1833.Sy MAKEOBJDIRPREFIX . 1834.Pp 1835For instance, a setting of 1836.Dq Fl O Pa /usr/obj 1837will place build-time files under 1838.Pa /usr/obj/bin , 1839.Pa /usr/obj/lib , 1840.Pa /usr/obj/usr.bin , 1841and so forth. 1842.Pp 1843If a relative path is specified, it will be converted to an 1844absolute path before being used. 1845.Sy build.sh 1846imposes the restriction that the argument to the 1847.Fl O 1848option must not contain a 1849.Dq \&$ 1850(dollar sign) 1851character. 1852If the directory does not already exist, 1853.Sy build.sh 1854will create it. 1855.Pp 1856In normal use, exactly one of the 1857.Fl M 1858or 1859.Fl O 1860options should be specified. 1861If neither 1862.Fl M 1863nor 1864.Fl O 1865is specified, then a default object directory will be chosen 1866according to rules in 1867.Aq bsd.obj.mk . 1868Relying on this default is not recommended because 1869it is determined by complex rules that are influenced 1870by the values of several variables and 1871by the location of the source directory. 1872.Pp 1873Note that placing the 1874.Ar obj 1875directory location outside of the default source tree hierarchy makes 1876it easier to manually clear out old files in the event the 1877.Dq make cleandir 1878operation is unable to do so. 1879(See 1880.Sx CAVEATS 1881below.) 1882.Pp 1883Note also that use of one of 1884.Fl M 1885or 1886.Fl O 1887is the only means of building multiple machine architecture userlands 1888from the same source tree without cleaning between builds (in which 1889case, one would specify distinct 1890.Ar obj 1891locations for each). 1892.It Fl o 1893Set the value of 1894.Sy MKOBJDIRS 1895to 1896.Dq no . 1897Otherwise, it will be automatically set to 1898.Dq yes . 1899This default is opposite to the behaviour when not using 1900.Sy build.sh . 1901. 1902.It Fl R Ar rel 1903Set the value of 1904.Sy RELEASEDIR 1905to 1906.Ar rel . 1907If a relative path is specified, it will be converted to an 1908absolute path before being used. 1909. 1910.It Fl r 1911Remove the contents of 1912.Sy DESTDIR 1913and 1914.Sy TOOLDIR 1915before building (provides a clean starting point). 1916This will skip deleting 1917.Sy DESTDIR 1918if building on a native system to the root directory. 1919. 1920.It Fl S Ar seed 1921Change the value of 1922.Sy BUILDSEED 1923to 1924.Ar seed . 1925This should rarely be necessary. 1926. 1927.It Fl T Ar tools 1928Set the value of 1929.Sy TOOLDIR 1930to 1931.Ar tools . 1932If a relative path is specified, it will be converted to an 1933absolute path before being used. 1934If set, the bootstrap 1935.Dq make 1936will only be rebuilt if the source files for 1937.Xr make 1 1938have changed. 1939. 1940.It Fl U 1941Set 1942.Sy MKUNPRIVED=yes . 1943. 1944.It Fl u 1945Set 1946.Sy MKUPDATE=yes . 1947. 1948.It Xo 1949.Fl V 1950.Sm off 1951.Ar var 1952.Li = 1953.Op Ar value 1954.Sm on 1955.Xc 1956Set the environment variable 1957.Ar var 1958to an optional 1959.Ar value . 1960This is propagated to the 1961.Sy \*[toolprefix]make 1962wrapper. 1963. 1964.It Fl w Ar wrapper 1965Create the 1966.Sy \*[toolprefix]make 1967wrapper script (see below) in a custom location, 1968specified by 1969.Ar wrapper . 1970This allows, for instance, to place the wrapper in 1971.Sy PATH 1972automatically. 1973Note that 1974.Ar wrapper 1975is the full name of the file, not just a directory name. 1976If a relative path is specified, it will be converted to an 1977absolute path before being used. 1978. 1979.It Fl X Ar x11src 1980Set the value of 1981.Sy X11SRCDIR 1982to 1983.Ar x11src . 1984If a relative path is specified, it will be converted to an 1985absolute path before being used. 1986. 1987.It Fl x 1988Set 1989.Sy MKX11=yes . 1990. 1991.It Fl Y Ar extsrcdir 1992Set the value of 1993.Sy EXTSRCSRCDIR 1994to 1995.Ar extsrcdir . 1996If a relative path is specified, it will be converted to an 1997absolute path before being used. 1998. 1999.It Fl y 2000Set 2001.Sy MKEXTSRC=yes . 2002. 2003.It Fl Z Ar var 2004Unset ("zap") the environment variable 2005.Ar var . 2006This is propagated to the 2007.Sy \*[toolprefix]make 2008wrapper. 2009. 2010.El 2011. 2012.Ss The \*q\*[toolprefix]make-MACHINE\*q wrapper script 2013. 2014If using the 2015.Sy build.sh 2016script to build 2017.Nx , 2018a 2019.Sy \*[toolprefix]make-MACHINE 2020script will be created in 2021.Sy TOOLDIR Ns Pa /bin 2022upon the first build to assist in building subtrees on a cross-compile 2023host. 2024.Pp 2025.Sy \*[toolprefix]make-MACHINE 2026can be invoked in lieu of 2027.Xr make 1 , 2028and will instead call the up-to-date version of 2029.Dq \*[toolprefix]make 2030installed into 2031.Sy TOOLDIR Ns Pa /bin 2032with several key variables pre-set, including 2033.Sy MACHINE , MACHINE_ARCH , 2034and 2035.Sy TOOLDIR . 2036.Sy \*[toolprefix]make-MACHINE 2037will also set variables specified with 2038.Fl V , 2039and unset variables specified with 2040.Fl Z . 2041.Pp 2042This script can be symlinked into a directory listed in 2043.Sy PATH , 2044or called with an absolute path. 2045. 2046.Sh EXAMPLES 2047. 2048.Bl -enum 2049. 2050.It 2051.Li "% ./build.sh [options] tools kernel=GENERIC" 2052.Pp 2053Build a new toolchain, and use the new toolchain to 2054configure and build a new GENERIC kernel. 2055. 2056.It 2057.Li "% ./build.sh [options] -U distribution" 2058.Pp 2059Using unprivileged mode, 2060build a complete distribution to a 2061.Sy DESTDIR 2062directory that 2063.Sy build.sh 2064selects (and will display). 2065. 2066.It 2067.Li "# ./build.sh [options] -U install=/" 2068.Pp 2069As root, install to 2070.Pa / 2071the distribution that was built 2072by example 2. 2073Even though this is run as root, 2074.Fl U 2075is required so that the permissions stored in 2076.Sy DESTDIR Ns Pa /METALOG 2077are correctly applied to the files as they're copied to 2078.Pa / . 2079. 2080.It 2081.Li "% ./build.sh [options] -U -u release" 2082.Pp 2083Using unprivileged mode, 2084build a complete release to 2085.Sy DESTDIR 2086and 2087.Sy RELEASEDIR 2088directories that 2089.Sy build.sh 2090selects (and will display). 2091.Sy MKUPDATE=yes 2092.Pq Fl u 2093is set to prevent the 2094.Dq make cleandir , 2095so that if this is run after example 2, it doesn't need to redo that 2096portion of the release build. 2097.El 2098. 2099.Sh OBSOLETE VARIABLES 2100. 2101.Bl -tag -width "NBUILDJOBS" 2102. 2103.It Sy NBUILDJOBS 2104Use the 2105.Xr make 1 2106option 2107.Fl j 2108instead. 2109. 2110.It Sy USE_NEW_TOOLCHAIN 2111The new toolchain is now the default. 2112To disable, use 2113.Sy TOOLCHAIN_MISSING=yes . 2114.El 2115.Sh SEE ALSO 2116.Xr make 1 , 2117.Xr hier 7 , 2118.Xr release 7 , 2119.Xr etcupdate 8 , 2120.Xr postinstall 8 , 2121.Xr sysinst 8 , 2122.Pa pkgsrc/sysutils/cdrtools 2123. 2124.Sh HISTORY 2125. 2126The 2127.Nm build.sh 2128based build scheme was introduced for 2129.Nx 1.6 2130as 2131.Sy USE_NEW_TOOLCHAIN , 2132and re-worked to 2133.Sy TOOLCHAIN_MISSING 2134after that. 2135. 2136.Sh CAVEATS 2137. 2138After significant updates to third-party components in the source 2139tree, the 2140.Dq make cleandir 2141operation may be insufficient to clean out old files in object 2142directories. 2143Instead, one may have to manually remove the files. 2144Consult the 2145.Pa UPDATING 2146file for notices concerning this. 2147