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