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