1.\" $NetBSD: BUILDING.mdoc,v 1.81 2010/07/25 07:19:00 mrg 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 MKUNPRIVED 558.YorN 559Indicates whether an unprivileged install will occur. 560The user, group, permissions, and file flags, will not be set on 561the installed items; instead the information will be appended to 562a file called 563.Pa METALOG 564in 565.Sy DESTDIR . 566The contents of 567.Pa METALOG 568are used during the generation of the distribution tar files to ensure 569that the appropriate file ownership is stored. 570.DFLTn 571. 572.It Sy MKUPDATE 573.YorN 574Indicates whether all install operations intended to write to 575.Sy DESTDIR 576will compare file timestamps before installing, and skip the install 577phase if the destination files are up-to-date. 578This also has implications on full builds (see next subsection). 579.DFLTn 580. 581.It Sy MKX11 582.YorN 583Indicates whether X11 is built from 584.Sy X11SRCDIR . 585.DFLTn 586. 587.It Sy TOOLDIR 588Directory to hold the host tools, once built. 589If specified, must be an absolute path. 590This directory should be unique to a given host system and 591.Nx 592source tree. 593(However, multiple targets may share the same 594.Sy TOOLDIR ; 595the target-dependent files have unique names.) If unset, a default based 596on the 597.Xr uname 1 598information of the host platform will be created in the 599.Sy .OBJDIR 600of 601.Pa src . 602.DFLTu 603. 604.It Sy USETOOLS 605Indicates whether the tools specified by 606.Sy TOOLDIR 607should be used as part of a build in progress. 608Must be set to 609.Dq yes 610if cross-compiling. 611.Bl -tag -width "never" 612.It Sy yes 613Use the tools from 614.Sy TOOLDIR . 615.It Sy no 616Do not use the tools from 617.Sy TOOLDIR , 618but refuse to build native compilation tool components that are 619version-specific for that tool. 620.It Sy never 621Do not use the tools from 622.Sy TOOLDIR , 623even when building native tool components. 624This is similar to the traditional 625.Nx 626build method, but does 627.Em not 628verify that the compilation tools in use are up-to-date enough in order 629to build the tree successfully. 630This may cause build or runtime problems when building the whole 631.Nx 632source tree. 633.El 634.DFLT 635.Dq yes , 636unless 637.Sy TOOLCHAIN_MISSING 638is set to 639.Dq yes . 640.Pp 641.Sy USETOOLS 642is also set to 643.Dq no 644when using 645.Aq bsd.*.mk 646outside the 647.Nx 648source tree. 649. 650.It Sy X11SRCDIR 651Directory containing the X11R6 source. 652If specified, must be an absolute path. 653The main X11R6 source is found in 654.Sy X11SRCDIR Ns Pa /xfree/xc . 655.DFLT 656.Sy NETBSDRCDIR Ns Pa /../xsrc , 657if that exists; otherwise 658.Pa /usr/xsrc . 659. 660.It Sy X11FLAVOUR 661The style of X11 cross-built, set to either 662.Dq Xorg 663or 664.Dq XFree86 . 665.DFLT 666.Dq Xorg 667on amd64, i386, macppc, shark and sparc64 platforms, 668.Dq XFree86 669on everything else. 670. 671.El 672. 673.Ss \*qmake\*q variables for full builds 674These variables only affect the top level 675.Dq Makefile 676and do not affect manually building subtrees of the 677.Nx 678source code. 679. 680.Bl -tag -width "INSTALLWORLDDIR" 681. 682.It Sy INSTALLWORLDDIR 683Location for the 684.Dq make installworld 685target to install to. 686If specified, must be an absolute path. 687.DFLT 688.Dq / 689. 690.It Sy MKOBJDIRS 691.YorN 692Indicates whether object directories will be created automatically 693(via a 694.Dq make obj 695pass) at the start of a build. 696.DFLTn 697.Pp 698If using 699.Sy build.sh , 700the default is 701.Dq yes . 702This may be set back to 703.Dq no 704by giving 705.Sy build.sh 706the 707.Fl o 708option. 709. 710.It Sy MKUPDATE 711.YorN 712If set, then in addition to the effects described for 713.Sy MKUPDATE=yes 714above, this implies the effects of 715.Sy NOCLEANDIR 716(i.e., 717.Dq make cleandir 718is avoided). 719.DFLTn 720.Pp 721If using 722.Sy build.sh , 723this may be set by giving the 724.Fl u 725option. 726. 727.It Sy NBUILDJOBS 728Now obsolete. 729Use the 730.Xr make 1 731option 732.Fl j , 733instead. 734See below. 735.DFLTu 736. 737.It Sy NOCLEANDIR 738If set, avoids the 739.Dq make cleandir 740phase of a full build. 741This has the effect of allowing only changed 742files in a source tree to be recompiled. 743This can speed up builds when updating only a few files in the tree. 744.DFLTu 745.Pp 746See also 747.Sy MKUPDATE . 748. 749.It Sy NODISTRIBDIRS 750If set, avoids the 751.Dq make distrib-dirs 752phase of a full build. 753This skips running 754.Xr mtree 8 755on 756.Sy DESTDIR , 757useful on systems where building as an unprivileged user, or where it is 758known that the system-wide mtree files have not changed. 759.DFLTu 760. 761.It Sy NOINCLUDES 762If set, avoids the 763.Dq make includes 764phase of a full build. 765This has the effect of preventing 766.Xr make 1 767from thinking that some programs are out-of-date simply because the 768system include files have changed. 769However, this option should not be used when updating the entire 770.Nx 771source tree arbitrarily; it is suggested to use 772.Sy MKUPDATE=yes 773instead in that case. 774.DFLTu 775. 776.It Sy RELEASEDIR 777If set, specifies the directory to which a 778.Xr release 7 779layout will be written at the end of a 780.Dq make release . 781If specified, must be an absolute path. 782.DFLTu 783.Pp 784.Em Note : 785.Sy build.sh 786will provide a default of 787.Pa releasedir 788(in the top-level 789.Sy .OBJDIR ) 790unless run in 791.Sq expert 792mode. 793. 794.El 795. 796.Sh BUILDING 797. 798.Ss \*qmake\*q command line options 799This is not a summary of all the options available to 800.Xr make 1 ; 801only the options used most frequently with 802.Nx 803builds are listed here. 804. 805.Bl -tag -width "var=value" 806. 807.It Fl j Ar njob 808Run up to 809.Ar njob 810.Xr make 1 811subjobs in parallel. 812Makefiles should use .WAIT or have explicit dependencies 813as necessary to enforce build ordering. 814. 815.It Fl m Ar dir 816Specify the default directory for searching for system Makefile 817segments, mainly the 818.Aq bsd.*.mk 819files. 820When building any full 821.Nx 822source tree, this should be set to the 823.Dq share/mk 824directory in the source tree. 825This is set automatically when building from the top level, or when using 826.Sy build.sh . 827. 828.It Fl n 829Display the commands that would have been executed, but do not 830actually execute them. 831This will still cause recursion to take place. 832. 833.It Fl V Ar var 834Print 835.Xr make 1 Ns 's 836idea of the value of 837.Ar var . 838Does not build any targets. 839. 840.It Em var=value 841Set the variable 842.Em var 843to 844.Em value , 845overriding any setting specified by the process environment, the 846.Sy MAKECONF 847configuration file, or the system Makefile segments. 848. 849.El 850. 851.Ss \*qmake\*q targets 852. 853These default targets may be built by running 854.Xr make 1 855in any subtree of the 856.Nx 857source code. 858It is recommended that none of these be used from the top 859level Makefile; as a specific exception, 860.Dq make obj 861and 862.Dq make cleandir 863are useful in that context. 864. 865.Bl -tag -width "dependall" 866. 867.It Sy all 868Build programs, libraries, and preformatted documentation. 869. 870.It Sy clean 871Remove program and library object code files. 872. 873.It Sy cleandir 874Same as 875.Sy clean , 876but also remove preformatted documentation, dependency files generated 877by 878.Dq make depend , 879and any other files known to be created at build time. 880. 881.It Sy depend 882Create dependency files 883.Sy ( .depend ) 884containing more detailed information about the dependencies of source 885code on header files. 886Allows programs to be recompiled automatically when a dependency changes. 887. 888.It Sy dependall 889Does a 890.Dq make depend 891immediately followed by a 892.Dq make all . 893This improves cache locality of the build since both passes read the source 894files in their entirety. 895. 896.It Sy distclean 897Synonym for 898.Sy cleandir . 899. 900.It Sy includes 901Build and install system header files. 902Typically needed before any system libraries or programs can be built. 903. 904.It Sy install 905Install programs, libraries, and documentation into 906.Sy DESTDIR . 907Few files will be installed to 908.Sy DESTDIR Ns Pa /dev , 909.Sy DESTDIR Ns Pa /etc , 910.Sy DESTDIR Ns Pa /root 911or 912.Sy DESTDIR Ns Pa /var 913in order to prevent user supplied configuration data from being overwritten. 914.It Sy lint 915Run 916.Xr lint 1 917against the C source code, where appropriate, and generate 918system-installed lint libraries. 919. 920.It Sy obj 921Create object directories to be used for built files, instead of 922building directly in the source tree. 923. 924.It Sy tags 925Create 926.Xr ctags 1 927searchable function lists usable by the 928.Xr ex 1 929and 930.Xr vi 1 931text editors. 932. 933.El 934. 935.Ss \*qmake\*q targets for the top level 936. 937Additional 938.Xr make 1 939targets are usable specifically from the top source level to facilitate 940building the entire 941.Nx 942source tree. 943. 944.Bl -tag -width "distribution" 945. 946.It Sy build 947Build the entire 948.Nx 949system (except the kernel). 950This orders portions of the source tree such that prerequisites 951will be built in the proper order. 952. 953.It Sy distribution 954Do a 955.Dq make build , 956and then install a full distribution (which does not include a kernel) into 957.Sy DESTDIR , 958including files in 959.Sy DESTDIR Ns Pa /dev , 960.Sy DESTDIR Ns Pa /etc , 961.Sy DESTDIR Ns Pa /root 962and 963.Sy DESTDIR Ns Pa /var . 964. 965.It Sy buildworld 966As per 967.Dq make distribution , 968except that it ensures that 969.Sy DESTDIR 970is not the root directory. 971. 972.It Sy installworld 973Install the distribution from 974.Sy DESTDIR 975to 976.Sy INSTALLWORLDDIR , 977which defaults to the root directory. 978Ensures that 979.Sy INSTALLWORLDDIR 980is not the root directory if cross compiling. 981.Pp 982The 983.Sy INSTALLSETS 984environment variable may be set to a list of 985distribution sets to be installed. 986By default, all sets except 987.Dq etc 988and 989.Dq xetc 990are installed, so most files in 991.Sy INSTALLWORLDDIR Ns Pa /etc 992will not be installed or modified. 993.Pp 994.Em Note : 995Before performing this operation with 996.Sy INSTALLWORLDDIR Ns = Ns Pa / , 997it is highly recommended that you upgrade your kernel and reboot. 998After performing this operation, 999it is recommended that you use 1000.Xr etcupdate 8 1001to update files in 1002.Sy INSTALLWORLDDIR Ns Pa /etc 1003and that you use 1004.Xr postinstall 8 1005to check for inconsistencies (and possibly to fix them). 1006.It Sy sets 1007Create distribution sets from 1008.Sy DESTDIR 1009into 1010.Sy RELEASEDIR/RELEASEMACHINEDIR Ns Pa /binary/sets . 1011Should be run after 1012.Dq make distribution , 1013as 1014.Dq make build 1015alone does not install all of the required files. 1016. 1017.It Sy sourcesets 1018Create source sets of the source tree into 1019.Sy RELEASEDIR Ns Pa /source/sets . 1020. 1021.It Sy syspkgs 1022Create syspkgs from 1023.Sy DESTDIR 1024into 1025.Sy RELEASEDIR/RELEASEMACHINEDIR Ns Pa /binary/syspkgs . 1026Should be run after 1027.Dq make distribution , 1028as 1029.Dq make build 1030alone does not install all of the required files. 1031. 1032.It Sy release 1033Do a 1034.Dq make distribution , 1035build kernels, distribution media, and install sets 1036(this as per 1037.Dq make sets ) , 1038and 1039then package the system into a standard release layout as described by 1040.Xr release 7 . 1041This requires that 1042.Sy RELEASEDIR 1043be set (see above). 1044. 1045.It Sy iso-image 1046Create a 1047.Nx 1048installation CD-ROM image in the 1049.Sy RELEASEDIR Ns Pa /iso 1050directory. 1051The CD-ROM file system will have a layout as described in 1052.Xr release 7 . 1053.Pp 1054For most machine types, the CD-ROM will be bootable, and will automatically 1055run the 1056.Xr sysinst 8 1057menu-based installation program, which can be used to install or upgrade a 1058.Nx 1059system. 1060Bootable CD-ROMs also contain tools that may be useful in 1061repairing a damaged 1062.Nx 1063installation. 1064.Pp 1065Before 1066.Dq make iso-image 1067is attempted, RELEASEDIR must be populated by 1068.Dq make release 1069or equivalent. 1070.Pp 1071Note that other, smaller, CD-ROM images may be created in the 1072.Sy RELEASEDIR/RELEASEMACHINEDIR Ns Pa /installation/cdrom 1073directory by 1074.Dq "make release" . 1075These smaller images usually contain the same tools as the larger images in 1076.Sy RELEASEDIR Ns Pa /iso , 1077but do not contain additional content such as the distribution sets. 1078.Pp 1079Note that the mac68k port still uses an older method of creating 1080CD-ROM images. 1081This requires the 1082.Xr mkisofs 1 1083utility, which is not part of 1084.Nx , 1085but which can be installed from 1086.Pa pkgsrc/sysutils/cdrtools . 1087. 1088.It Sy iso-image-source 1089Create a 1090.Nx 1091installation CD-ROM image in the 1092.Sy RELEASEDIR Ns Pa /iso 1093directory. 1094The CD-ROM file system will have a layout as described in 1095.Xr release 7 . 1096It will have top level directories for the machine type and source. 1097.Pp 1098For most machine types, the CD-ROM will be bootable, and will automatically 1099run the 1100.Xr sysinst 8 1101menu-based installation program, which can be used to install or upgrade a 1102.Nx 1103system. 1104Bootable CD-ROMs also contain tools that may be useful in 1105repairing a damaged 1106.Nx 1107installation. 1108.Pp 1109Before 1110.Dq make iso-image-source 1111is attempted, RELEASEDIR must be populated by 1112.Dq make sourcesets release 1113or equivalent. 1114.Pp 1115Note that other, smaller, CD-ROM images may be created in the 1116.Sy RELEASEDIR/RELEASEMACHINEDIR Ns Pa /installation/cdrom 1117directory by 1118.Dq make release . 1119These smaller images usually contain the same tools as the larger images in 1120.Sy RELEASEDIR Ns Pa /iso , 1121but do not contain additional content such as the distribution sets. 1122.Pp 1123Note that the mac68k port still uses an older method of creating 1124CD-ROM images. 1125This requires the 1126.Xr mkisofs 1 1127utility, which is not part of 1128.Nx , 1129but which can be installed from 1130.Pa pkgsrc/sysutils/cdrtools . 1131. 1132.It Sy regression-tests 1133Can only be run after building the regression tests in the directory 1134.Dq regress . 1135Runs those compiled regression tests on the local host. 1136Note that most tests are now managed instead using 1137.Xr atf 7 ; 1138this target should probably run those as well but currently does not. 1139. 1140.El 1141. 1142.Ss The \*qbuild.sh\*q script 1143. 1144This script file is a Bourne shell script designed to build the 1145entire 1146.Nx 1147system on any host with a Bourne shell in 1148.Sy /bin/sh , 1149including many that are not POSIX compliant. 1150Note that if a host system's 1151.Sy /bin/sh 1152is unusually old and broken, the Korn Shell 1153.Sy ( /bin/ksh ) , 1154if available, may be a usable alternative. 1155.Pp 1156All cross-compile builds, and most native builds, of the entire system 1157should make use of 1158.Sy build.sh 1159rather than just running 1160.Dq make . 1161This way, the 1162.Xr make 1 1163program will be bootstrapped properly, in case the host system has an 1164older or incompatible 1165.Dq make 1166program. 1167.Pp 1168When compiling the entire system via 1169.Sy build.sh , 1170many 1171.Xr make 1 1172variables are set for you in order to help encapsulate the build 1173process. 1174In the list of options below, variables that are automatically set by 1175.Sy build.sh 1176are noted where applicable. 1177. 1178.Pp 1179The following operations are supported by 1180.Sy build.sh : 1181. 1182.Bl -tag -width "distribution" 1183. 1184.It Sy build 1185Build the system as per 1186.Dq make build . 1187Before the main part of the build commences, this command runs the 1188.Sy obj 1189operation (unless the 1190.Fl o 1191option is given), 1192.Dq make cleandir 1193(unless the 1194.Fl u 1195option is given), 1196and the 1197.Sy tools 1198operation. 1199. 1200.It Sy distribution 1201Build a full distribution as per 1202.Dq make distribution . 1203This command first runs the 1204.Sy build 1205operation. 1206. 1207.It Sy release 1208Build a full release as per 1209.Dq make release . 1210This command first runs the 1211.Sy distribution 1212operation. 1213. 1214.It Sy makewrapper 1215Create the 1216.Sy \*[toolprefix]make-MACHINE 1217wrapper. 1218This operation is automatically performed for any of the other 1219operations. 1220. 1221.It Sy cleandir 1222Perform 1223.Dq make cleandir . 1224. 1225.It Sy obj 1226Perform 1227.Dq make obj . 1228. 1229.It Sy tools 1230Build and install the host tools from 1231.Pa src/tools . 1232This command will first run 1233.Dq make obj 1234and 1235.Dq make cleandir 1236in the 1237.Pa tools 1238subdirectory unless the 1239.Fl o 1240or 1241.Fl u 1242options (respectively) are given. 1243. 1244.It Sy install Ns = Ns Ar idir 1245Install the contents of 1246.Sy DESTDIR 1247to 1248.Ar idir , 1249using 1250.Dq make installworld . 1251Note that files that are part of the 1252.Dq etc 1253or 1254.Dq xetc 1255sets will not be installed. 1256. 1257.It Sy kernel Ns = Ns Ar kconf 1258Build a new kernel. 1259The 1260.Ar kconf 1261argument is the name of a configuration file suitable 1262for use by 1263.Xr config 1 . 1264If 1265.Ar kconf 1266does not contain any 1267.Sq / 1268characters, the configuration file is expected to be found in the 1269.Sy KERNCONFDIR 1270directory, which is typically 1271.Sy sys/arch/MACHINE/conf . 1272The new kernel will be built in a subdirectory of 1273.Sy KERNOBJDIR , 1274which is typically 1275.Sy sys/arch/MACHINE/compile 1276or an associated object directory. 1277.Pp 1278This command does 1279.Em not 1280imply the 1281.Sy tools 1282command; run the 1283.Sy tools 1284command first unless it is 1285.Em certain 1286that the tools already exist and are up to date. 1287.Pp 1288This command will run 1289.Dq make cleandir 1290on the kernel in question first unless the 1291.Fl u 1292option is given. 1293. 1294.It Sy modules 1295This command will build kernel modules and install them into 1296.Sy DESTDIR . 1297. 1298.It Sy releasekernel Ns = Ns Ar kconf 1299Install a 1300.Xr gzip 1 Ns ed 1301copy of the kernel previously built by 1302.Sy kernel Ns = Ns Ar kconf 1303into 1304.Sy RELEASEDIR/RELEASEMACHINEDIR Ns Pa /binary/kernel , 1305usually as 1306.Pa netbsd- Ns Ar kconf Ns Pa .gz , 1307although the 1308.Dq Pa netbsd 1309prefix is determined from the 1310.Dq Sy config 1311directives in 1312.Ar kconf . 1313. 1314.It Sy sets 1315Perform 1316.Dq make sets . 1317. 1318.It Sy sourcesets 1319Perform 1320.Dq make sourcesets . 1321. 1322.It Sy syspkgs 1323Perform 1324.Dq make syspkgs . 1325. 1326.It Sy iso-image 1327Perform 1328.Dq make iso-image . 1329. 1330.It Sy iso-image-source 1331Perform 1332.Dq make iso-image-source . 1333. 1334.El 1335. 1336.Pp 1337The following command line options alter the behaviour of the 1338.Sy build.sh 1339operations described above: 1340. 1341.Bl -tag -width "-T tools" 1342. 1343.It Fl a Ar arch 1344Set the value of 1345.Sy MACHINE_ARCH 1346to 1347.Ar arch . 1348. 1349.It Fl B Ar buildid 1350Set the value of 1351.Sy BUILDID 1352to 1353.Ar buildid . 1354This will also append the build identifier to the name of the 1355.Dq make 1356wrapper script so that the resulting name is of the form 1357.Dq Sy \*[toolprefix]make-MACHINE-BUILDID . 1358. 1359.It Fl C Ar cdextras 1360Append 1361.Ar cdextras 1362to the 1363.Sy CDEXTRA 1364variable, 1365which is a space-separated list of files or directories that will be 1366added to the CD-ROM image that may be create by the 1367.Dq iso-image 1368or 1369.Dq iso-image-source 1370operations. 1371Files will be added to the root of the CD-ROM image, whereas directories 1372will be copied recursively. 1373If relative paths are specified, they will be converted to 1374absolute paths before being used. 1375Multiple paths may be specified via multiple 1376.Fl C 1377options, or via a single option whose argument contains multiple 1378space-separated paths. 1379. 1380.It Fl D Ar dest 1381Set the value of 1382.Sy DESTDIR 1383to 1384.Ar dest . 1385If a relative path is specified, it will be converted to an 1386absolute path before being used. 1387. 1388.It Fl E 1389Set 1390.Sq expert 1391mode. 1392This overrides various sanity checks, and allows: 1393.Sy DESTDIR 1394does not have to be set to a non-root path for builds, 1395and 1396.Sy MKUNPRIVED=yes 1397does not have to be set when building as a non-root user. 1398.Pp 1399.Em Note : 1400It is highly recommended that you know what you are doing when 1401you use this option. 1402. 1403.It Fl h 1404Print a help message. 1405. 1406.It Fl j Ar njob 1407Run up to 1408.Ar njob 1409.Xr make 1 1410subjobs in parallel; 1411passed through to 1412.Xr make 1 . 1413If you see failures for reasons other than running out of memory 1414while using 1415.Sy build.sh 1416with 1417.Fl j , 1418please save complete build logs 1419so the failures can be analyzed. 1420.Pp 1421To achieve the fastest builds, 1422.Fl j 1423values between (1 + the number of CPUs) and (2 * the number of CPUs) 1424are recommended. 1425Use lower values on machines with limited memory or I/O bandwidth. 1426. 1427.It Fl M Ar obj 1428Set 1429.Sy MAKEOBJDIRPREFIX 1430to 1431.Ar obj . 1432Unsets 1433.Sy MAKEOBJDIR . 1434See 1435.Dq Fl O obj 1436for more information. 1437.Pp 1438For instance, if the source directory is 1439.Pa /usr/src , 1440a setting of 1441.Dq Fl M Pa /usr/obj 1442will place build-time files under 1443.Pa /usr/obj/usr/src/bin , 1444.Pa /usr/obj/usr/src/lib , 1445.Pa /usr/obj/usr/src/usr.bin , 1446and so forth. 1447.Pp 1448If a relative path is specified, it will be converted to an 1449absolute path before being used. 1450.Sy build.sh 1451imposes the restriction that the argument to the 1452.Fl M 1453option must not begin with a 1454.Dq \&$ 1455(dollar sign) 1456character; otherwise it would be too difficult 1457to determine whether the value is an absolute or a relative path. 1458If the directory does not already exist, 1459.Sy build.sh 1460will create it. 1461. 1462.It Fl m Ar mach 1463Set the value of 1464.Sy MACHINE 1465to 1466.Ar mach , 1467except in some special cases listed below. 1468This will also override any value of 1469.Sy MACHINE_ARCH 1470in the process environment with a value deduced from 1471.Ar mach , 1472unless 1473.Fl a 1474is specified. 1475All cross builds require 1476.Fl m , 1477but if unset on a NetBSD host, the host's value of MACHINE will be 1478detected and used automatically. 1479.Pp 1480Some machines support multiple values for 1481.Sy MACHINE_ARCH . 1482The following special cases for the 1483.Ar mach 1484argument are defined to set the listed values of 1485.Sy MACHINE 1486and 1487.Sy MACHINE_ARCH : 1488.Bl -column "evbmips-el" "MACHINE" "MACHINE_ARCH" -offset indent 1489.It Sy mach Ta Sy "MACHINE" Ta Sy "MACHINE_ARCH" 1490.It evbarm Ta evbarm Ta (not set) 1491.It evbarm-eb Ta evbarm Ta armeb 1492.It evbarm-el Ta evbarm Ta arm 1493.It evbmips Ta evbmips Ta (not set) 1494.It evbmips-eb Ta evbmips Ta mipseb 1495.It evbmips-el Ta evbmips Ta mipsel 1496.It evbsh3 Ta evbsh3 Ta (not set) 1497.It evbsh3-eb Ta evbsh3 Ta sh3eb 1498.It evbsh3-el Ta evbsh3 Ta sh3el 1499.It sbmips Ta sbmips Ta (not set) 1500.It sbmips-eb Ta sbmips Ta mipseb 1501.It sbmips-el Ta sbmips Ta mipsel 1502.El 1503. 1504.It Fl N Ar noiselevel 1505Set the 1506.Dq noisyness 1507level of the build, by setting 1508.Sy MAKEVERBOSE 1509to 1510.Ar noiselevel . 1511. 1512.It Fl n 1513Show the commands that would be executed by 1514.Sy build.sh , 1515but do not make any changes. 1516This is similar in concept to 1517.Dq make -n . 1518. 1519.It Fl O Ar obj 1520Create an appropriate transform macro for 1521.Sy MAKEOBJDIR 1522that will place the built object files under 1523.Ar obj . 1524Unsets 1525.Sy MAKEOBJDIRPREFIX . 1526.Pp 1527For instance, a setting of 1528.Dq Fl O Pa /usr/obj 1529will place build-time files under 1530.Pa /usr/obj/bin , 1531.Pa /usr/obj/lib , 1532.Pa /usr/obj/usr.bin , 1533and so forth. 1534.Pp 1535If a relative path is specified, it will be converted to an 1536absolute path before being used. 1537.Sy build.sh 1538imposes the restriction that the argument to the 1539.Fl O 1540option must not contain a 1541.Dq \&$ 1542(dollar sign) 1543character. 1544If the directory does not already exist, 1545.Sy build.sh 1546will create it. 1547.Pp 1548In normal use, exactly one of the 1549.Fl M 1550or 1551.Fl O 1552options should be specified. 1553If neither 1554.Fl M 1555nor 1556.Fl O 1557is specified, then a default object directory will be chosen 1558according to rules in 1559.Aq bsd.obj.mk . 1560Relying on this default is not recommended because 1561it is determined by complex rules that are influenced 1562by the values of several variables and 1563by the location of the source directory. 1564.It Fl o 1565Set the value of 1566.Sy MKOBJDIRS 1567to 1568.Dq no . 1569Otherwise, it will be automatically set to 1570.Dq yes . 1571This default is opposite to the behaviour when not using 1572.Sy build.sh . 1573. 1574.It Fl R Ar rel 1575Set the value of 1576.Sy RELEASEDIR 1577to 1578.Ar rel . 1579If a relative path is specified, it will be converted to an 1580absolute path before being used. 1581. 1582.It Fl r 1583Remove the contents of 1584.Sy DESTDIR 1585and 1586.Sy TOOLDIR 1587before building (provides a clean starting point). 1588This will skip deleting 1589.Sy DESTDIR 1590if building on a native system to the root directory. 1591. 1592.It Fl S Ar seed 1593Change the value of 1594.Sy BUILDSEED 1595to 1596.Ar seed . 1597This should rarely be necessary. 1598. 1599.It Fl T Ar tools 1600Set the value of 1601.Sy TOOLDIR 1602to 1603.Ar tools . 1604If a relative path is specified, it will be converted to an 1605absolute path before being used. 1606If set, the bootstrap 1607.Dq make 1608will only be rebuilt if the source files for 1609.Xr make 1 1610have changed. 1611. 1612.It Fl U 1613Set 1614.Sy MKUNPRIVED=yes . 1615. 1616.It Fl u 1617Set 1618.Sy MKUPDATE=yes . 1619. 1620.It Xo 1621.Fl V 1622.Sm off 1623.Ar var 1624.Li = 1625.Op Ar value 1626.Sm on 1627.Xc 1628Set the environment variable 1629.Ar var 1630to an optional 1631.Ar value . 1632This is propagated to the 1633.Sy \*[toolprefix]make 1634wrapper. 1635. 1636.It Fl w Ar wrapper 1637Create the 1638.Sy \*[toolprefix]make 1639wrapper script (see below) in a custom location, 1640specified by 1641.Ar wrapper . 1642This allows, for instance, to place the wrapper in 1643.Sy PATH 1644automatically. 1645Note that 1646.Ar wrapper 1647is the full name of the file, not just a directory name. 1648If a relative path is specified, it will be converted to an 1649absolute path before being used. 1650. 1651.It Fl X Ar x11src 1652Set the value of 1653.Sy X11SRCDIR 1654to 1655.Ar x11src . 1656If a relative path is specified, it will be converted to an 1657absolute path before being used. 1658. 1659.It Fl x 1660Set 1661.Sy MKX11=yes . 1662. 1663.It Fl Z Ar var 1664Unset ("zap") the environment variable 1665.Ar var . 1666This is propagated to the 1667.Sy \*[toolprefix]make 1668wrapper. 1669. 1670.El 1671. 1672.Ss The \*q\*[toolprefix]make-MACHINE\*q wrapper script 1673. 1674If using the 1675.Sy build.sh 1676script to build 1677.Nx , 1678a 1679.Sy \*[toolprefix]make-MACHINE 1680script will be created in 1681.Sy TOOLDIR/bin 1682upon the first build to assist in building subtrees on a cross-compile 1683host. 1684.Pp 1685.Sy \*[toolprefix]make-MACHINE 1686can be invoked in lieu of 1687.Xr make 1 , 1688and will instead call the up-to-date version of 1689.Dq \*[toolprefix]make 1690installed into 1691.Sy TOOLDIR/bin 1692with several key variables pre-set, including 1693.Sy MACHINE , MACHINE_ARCH , 1694and 1695.Sy TOOLDIR . 1696.Sy \*[toolprefix]make-MACHINE 1697will also set variables specified with 1698.Fl V , 1699and unset variables specified with 1700.Fl Z . 1701.Pp 1702This script can be symlinked into a directory listed in 1703.Sy PATH , 1704or called with an absolute path. 1705. 1706.Sh EXAMPLES 1707. 1708.Bl -enum 1709. 1710.It 1711.Li "% ./build.sh [options] tools kernel=GENERIC" 1712.Pp 1713Build a new toolchain, and use the new toolchain to 1714configure and build a new GENERIC kernel. 1715. 1716.It 1717.Li "% ./build.sh [options] -U distribution" 1718.Pp 1719Using unprivileged mode, 1720build a complete distribution to a 1721.Sy DESTDIR 1722directory that 1723.Sy build.sh 1724selects (and will display). 1725. 1726.It 1727.Li "# ./build.sh [options] -U install=/" 1728.Pp 1729As root, install to 1730.Pa / 1731the distribution that was built 1732by example 2. 1733Even though this is run as root, 1734.Fl U 1735is required so that the permissions stored in 1736.Sy DESTDIR Ns Pa /METALOG 1737are correctly applied to the files as they're copied to 1738.Pa / . 1739. 1740.It 1741.Li "% ./build.sh [options] -U -u release" 1742.Pp 1743Using unprivileged mode, 1744build a complete release to 1745.Sy DESTDIR 1746and 1747.Sy RELEASEDIR 1748directories that 1749.Sy build.sh 1750selects (and will display). 1751.Sy MKUPDATE=yes 1752.Pq Fl u 1753is set to prevent the 1754.Dq make cleandir , 1755so that if this is run after example 2, it doesn't need to redo that 1756portion of the release build. 1757.El 1758. 1759.Sh OBSOLETE VARIABLES 1760. 1761.Bl -tag -width "NBUILDJOBS" 1762. 1763.It Sy NBUILDJOBS 1764Use the 1765.Xr make 1 1766option 1767.Fl j 1768instead. 1769. 1770.It Sy USE_NEW_TOOLCHAIN 1771The new toolchain is now the default. 1772To disable, use 1773.Sy TOOLCHAIN_MISSING=yes . 1774.El 1775.Sh SEE ALSO 1776.Xr make 1 , 1777.Xr hier 7 , 1778.Xr release 7 , 1779.Xr etcupdate 8 , 1780.Xr postinstall 8 , 1781.Xr sysinst 8 , 1782.Pa pkgsrc/sysutils/cdrtools 1783. 1784.Sh HISTORY 1785. 1786The 1787.Nm build.sh 1788based build scheme was introduced for 1789.Nx 1.6 1790as 1791.Sy USE_NEW_TOOLCHAIN , 1792and re-worked to 1793.Sy TOOLCHAIN_MISSING 1794after that. 1795