BUILDING revision 1.158
1BUILDING(8) System Manager's Manual BUILDING(8) 2 3NAME 4 BUILDING - Procedure for building NetBSD from source code 5 6REQUIREMENTS 7 NetBSD is designed to be buildable on most POSIX-compliant host systems. 8 The basic build procedure is the same whether compiling natively (on the 9 same NetBSD architecture) or cross compiling (on another architecture or 10 OS). 11 12 This source tree contains the build.sh shell script which supports both 13 native and cross builds of NetBSD. 14 15 This source tree contains a special subtree, "tools", which uses the host 16 system to create a build toolchain for the target architecture. The host 17 system must have at least C and C++ compilers in order to create the 18 toolchain (make(1) is not required); all other tools (including make(1) 19 as nbmake) are created as part of the NetBSD build process. (See the 20 Environment variables section below if you need to override or manually 21 select your compilers.) 22 23 Note: Within this document, cross-references to manual pages are to the 24 NetBSD manual pages, not the host system manual pages. The mdoc(7) 25 source to the NetBSD manual pages can be found within the source tree, 26 and these and can be formatted with mandoc(1) or nroff(1) if those are 27 available on the host system. The NetBSD manual pages are also available 28 at https://man.netbsd.org 29 30FILES 31 Source tree layout 32 BUILDING This document (in plaintext). Generated from 33 doc/BUILDING.mdoc. 34 35 Makefile The main Makefile for NetBSD; should only be run for 36 native builds with an appropriately up-to-date version of 37 NetBSD make(1). Intended for expert use with knowledge of 38 its shortcomings, it has been superseded by the build.sh 39 shell script as the recommended means for building NetBSD. 40 41 UPDATING Special notes for updating from an earlier revision of 42 NetBSD. It is important to read this file before every 43 build of an updated source tree. 44 45 build.sh Bourne-compatible shell script used for building the host 46 build tools and the NetBSD system from scratch. Can be 47 used for both native and cross builds, and should be used 48 instead of make(1) as it performs additional checks to 49 prevent common issues going undetected, such as building 50 with an outdated version of make(1). 51 52 crypto/dist/, dist/, gnu/dist/ 53 Sources imported verbatim from third parties, without 54 mangling the existing build structure. Other source trees 55 in bin through usr.sbin use the NetBSD make(1) "reachover" 56 Makefile semantics when building these programs for a 57 native host. 58 59 distrib/, etc/ 60 Sources for items used when making a full release 61 snapshot, such as files installed in DESTDIR/etc on the 62 destination system, boot media, and release notes. 63 64 doc/BUILDING.mdoc 65 The source to this document, in mdoc(7) format. Used to 66 generate BUILDING. 67 68 external/, sys/external/ 69 Sources and build infrastructure for components imported 70 (mostly) unchanged from upstream maintainers, sorted by 71 applicable license. This is (slowly) replacing the 72 crypto/dist, dist, and gnu/dist directories. 73 74 external/mit/xorg/ 75 "Reachover" build structure for modular Xorg; the source 76 is in X11SRCDIR. 77 78 mk.conf Optional source tree specific mk.conf(5), used (if 79 present) instead of /etc/mk.conf unless MAKECONF is 80 defined. 81 82 Note: Not part of the NetBSD source repository. 83 84 regress/, tests/ 85 Regression test harness. Can be cross-compiled, but only 86 run natively. tests/ uses the atf(7) test framework; 87 regress/ contains older tests that have not yet been 88 migrated to atf(7). 89 90 sys/ NetBSD kernel sources. 91 92 tools/ "Reachover" build structure for the host build tools. 93 This has a special method of determining out-of-date 94 status. 95 96 tools/compat/README 97 Special notes for cross-hosting a NetBSD build on non- 98 NetBSD platforms. 99 100 Other directories including bin/ ... usr.sbin/ 101 Sources to the NetBSD userland (non-kernel) programs. If 102 any of these directories are missing, they will be skipped 103 during the build. 104 105 Build tree layout 106 The NetBSD build tree is described in hier(7) (whose mdoc(7) source is in 107 share/man/man7/hier.7), and the release layout is described in release(7) 108 (whose mdoc(7) source is in share/man/man7/release.7). 109 110CONFIGURATION 111 Environment variables 112 Several environment variables control the behaviour of NetBSD builds. 113 114 HOST_CC Path name to C compiler used to create the toolchain. 115 116 Default: "cc". 117 118 HOST_CFLAGS Flags passed to the host C compiler. 119 120 Default: "-O". 121 122 HOST_CPPFLAGS Flags passed to the host C/C++ pre-processor. 123 124 Default: Unset. 125 126 HOST_CXX Path name to C++ compiler used to create the toolchain. 127 128 Default: Unset, but defaults to "c++" where required. 129 130 HOST_CXXFLAGS Flags passed to the host C++ compiler. 131 132 Default: Unset. 133 134 HOST_SH Path name to a shell available on the host system and 135 suitable for use during the build. The NetBSD build 136 system requires a modern Bourne-like shell with POSIX- 137 compliant features, and also requires support for the 138 "local" keyword to declare local variables in shell 139 functions (which is a widely-implemented but non- 140 standardised feature). 141 142 Depending on the host system, a suitable shell may be 143 /bin/sh, /usr/xpg4/bin/sh, /bin/ksh (provided it is a 144 variant of ksh that supports the "local" keyword, such as 145 ksh88, but not ksh93), or /usr/local/bin/bash. 146 147 Most parts of the build require HOST_SH to be an absolute 148 path; however, build.sh allows it to be a simple command 149 name, which will be converted to an absolute path by 150 searching the PATH. 151 152 Default: "sh". 153 154 INSTALLBOOT_UBOOT_PATHS 155 A colon-separated list of search paths used by 156 installboot(8) to find U-Boot packages. 157 158 Default: Unset. 159 160 MACHINE Machine type, e.g., "macppc". 161 162 Default: Unset. 163 164 MACHINE_ARCH Machine architecture, e.g., "powerpc". 165 166 Default: Unset. 167 168 MAKE Path name to invoke make(1) as. 169 170 Default: "make". 171 172 MAKECONF The name of the make(1) configuration file. See "make" 173 variables and mk.conf(5). 174 175 Note: Only settable in the process environment. 176 177 Default: "/etc/mk.conf", although build.sh will set the 178 default to the full path to mk.conf if the latter is 179 present in the same directory as build.sh. 180 181 MAKEFLAGS Flags to invoke make(1) with. 182 183 Note: build.sh ignores the value of MAKEFLAGS passed in 184 the environment, but allows MAKEFLAGS to be set via the 185 -V option. 186 187 Default: "-X" on systems with a small ARG_MAX (Cygwin, 188 Darwin, FreeBSD); otherwise unset. 189 190 MAKEOBJDIR Directory to use as the .OBJDIR for the current 191 directory. The value is subjected to variable expansion 192 by make(1). Typical usage is to set this variable to a 193 value involving the use of `${.CURDIR:S...}' or 194 `${.CURDIR:C...}', to derive the value of .OBJDIR from 195 the value of .CURDIR. Used only if MAKEOBJDIRPREFIX is 196 not defined. 197 198 Note: MAKEOBJDIR can be provided only in the environment 199 or via the -O flag of build.sh; it cannot usefully be set 200 inside a Makefile, including in mk.conf(5) or MAKECONF. 201 202 Default: Unset. 203 204 MAKEOBJDIRPREFIX 205 Top level directory of the object directory tree. The 206 value is subjected to variable expansion by make(1). 207 build.sh will create the ${MAKEOBJDIRPREFIX} directory if 208 necessary, but if make(1) is used without build.sh, then 209 rules in <bsd.obj.mk> will abort the build if the 210 ${MAKEOBJDIRPREFIX} directory does not exist. If the 211 value is defined and valid, then 212 ${MAKEOBJDIRPREFIX}/${.CURDIR} is used as the .OBJDIR for 213 the current directory. The current directory may be read 214 only. 215 216 Note: MAKEOBJDIRPREFIX can be provided only in the 217 environment or via the -M flag of build.sh; it cannot 218 usefully be set inside a Makefile, including in 219 mk.conf(5) or MAKECONF. 220 221 Default: Unset. 222 223 TMPDIR Top-level directory to store temporary directories used 224 by build.sh before paths to other directories such as 225 .OBJDIR can be determined. 226 227 Note: Must support execution of binaries. I.e., without 228 mount(8)'s -o noexec option. 229 230 Default: "/tmp". 231 232 "make" variables 233 Variables that control the behavior of NetBSD builds are documented in 234 mk.conf(5) (whose mdoc(7) source is in share/man/man5/mk.conf.5). 235 236 Unless otherwise specified, these variables may be set in either the 237 process environment or the make(1) configuration file mk.conf(5) 238 specified by MAKECONF. 239 240BUILDING 241 "make" command line options 242 This is not a summary of all the options available to make(1); only the 243 options used most frequently with NetBSD builds are listed here. 244 245 -j njob Run up to njob make(1) subjobs in parallel. Makefiles should 246 use .WAIT or have explicit dependencies as necessary to 247 enforce build ordering. 248 249 -m dir Specify the default directory for searching for system 250 Makefile segments, mainly the <bsd.*.mk> files. When building 251 any full NetBSD source tree, this should be set to the 252 "share/mk" directory in the source tree. This is set 253 automatically when building from the top level, or when using 254 build.sh. 255 256 -n Show the commands that would have been executed, but do not 257 actually execute them. This will still cause recursion to 258 take place. 259 260 -V var Show make(1)'s idea of the value of var. Does not build any 261 targets. 262 263 var=value Set the variable var to value, overriding any setting 264 specified by the process environment, the MAKECONF 265 configuration file, or the system Makefile segments. 266 267 "make" targets 268 These default targets may be built by running make(1) in any subtree of 269 the NetBSD source code. It is recommended that none of these be used 270 from the top level Makefile; as a specific exception, "make obj" and 271 "make cleandir" are useful in that context. 272 273 all Build programs, libraries, and preformatted documentation. 274 275 clean Remove program and library object code files. 276 277 cleandir Same as clean, but also remove preformatted documentation, 278 dependency files generated by "make depend", and any other 279 files known to be created at build time. 280 281 depend Create dependency files (.depend) containing more detailed 282 information about the dependencies of source code on header 283 files. Allows programs to be recompiled automatically when a 284 dependency changes. 285 286 dependall Does a "make depend" immediately followed by a "make all". 287 This improves cache locality of the build since both passes 288 read the source files in their entirety. 289 290 distclean Synonym for cleandir. 291 292 includes Build and install system header files. Typically needed 293 before any system libraries or programs can be built. 294 295 install Install programs, libraries, and documentation into DESTDIR. 296 Few files will be installed to DESTDIR/dev, DESTDIR/etc, 297 DESTDIR/root or DESTDIR/var in order to prevent user supplied 298 configuration data from being overwritten. 299 300 lint Run lint(1) against the C source code, where appropriate, and 301 generate system-installed lint libraries. 302 303 obj Create object directories to be used for built files, instead 304 of building directly in the source tree. 305 306 tags Create ctags(1) searchable function lists usable by the ex(1) 307 and vi(1) text editors. 308 309 "make" targets for the top level 310 Additional make(1) targets are usable specifically from the top source 311 level to facilitate building the entire NetBSD source tree. 312 313 build Build the entire NetBSD system (except the kernel). This 314 orders portions of the source tree such that prerequisites 315 will be built in the proper order. 316 317 distribution Do a "make build", and then install a full distribution 318 (which does not include a kernel) into DESTDIR, including 319 files in DESTDIR/dev, DESTDIR/etc, DESTDIR/root and 320 DESTDIR/var. 321 322 buildworld As per "make distribution", except that it ensures that 323 DESTDIR is not the root directory. 324 325 installworld Install the distribution from DESTDIR to INSTALLWORLDDIR, 326 which defaults to the root directory. Ensures that 327 INSTALLWORLDDIR is not the root directory if cross 328 compiling. 329 330 The INSTALLSETS environment variable may be set to a space- 331 separated list of distribution sets to be installed. By 332 default, all sets except "etc" and "xetc" are installed, so 333 most files in INSTALLWORLDDIR/etc will not be installed or 334 modified. 335 336 Note: Before performing this operation with 337 INSTALLWORLDDIR=/, it is highly recommended that you 338 upgrade your kernel and reboot. After performing this 339 operation, it is recommended that you use etcupdate(8) to 340 update files in INSTALLWORLDDIR/etc, and postinstall(8) to 341 check for or fix inconsistencies. 342 343 sets Create distribution sets from DESTDIR into 344 RELEASEDIR/RELEASEMACHINEDIR/binary/sets. Should be run 345 after "make distribution", as "make build" alone does not 346 install all of the required files. 347 348 sourcesets Create source sets of the source tree into 349 RELEASEDIR/source/sets. 350 351 syspkgs Create syspkgs from DESTDIR into 352 RELEASEDIR/RELEASEMACHINEDIR/binary/syspkgs. Should be run 353 after "make distribution", as "make build" alone does not 354 install all of the required files. 355 356 release Do a "make distribution", build kernels, distribution 357 media, and install sets (this as per "make sets"), and then 358 package the system into a standard release layout as 359 described by release(7). This requires that RELEASEDIR be 360 set (see above). 361 362 iso-image Create a NetBSD installation CD-ROM image in the 363 RELEASEDIR/images directory. The CD-ROM file system will 364 have a layout as described in release(7). 365 366 For most machine types, the CD-ROM will be bootable, and 367 will automatically run the sysinst(8) menu-based 368 installation program, which can be used to install or 369 upgrade a NetBSD system. Bootable CD-ROMs also contain 370 tools that may be useful in repairing a damaged NetBSD 371 installation. 372 373 Before "make iso-image" is attempted, RELEASEDIR must be 374 populated by "make release" or equivalent. 375 376 Note: Other, smaller, CD-ROM images may be created in the 377 RELEASEDIR/RELEASEMACHINEDIR/installation/cdrom directory 378 by "make release". These smaller images usually contain 379 the same tools as the larger images in RELEASEDIR/images, 380 but do not contain additional content such as the 381 distribution sets. 382 383 Note: The mac68k port still uses an older method of 384 creating CD-ROM images. This requires the mkisofs(1) 385 utility, which is not part of NetBSD, but which can be 386 installed from pkgsrc/sysutils/cdrtools. 387 388 iso-image-source 389 Create a NetBSD installation CD-ROM image in the 390 RELEASEDIR/images directory. The CD-ROM file system will 391 have a layout as described in release(7). It will have top 392 level directories for the machine type and source. 393 394 For most machine types, the CD-ROM will be bootable, and 395 will automatically run the sysinst(8) menu-based 396 installation program, which can be used to install or 397 upgrade a NetBSD system. Bootable CD-ROMs also contain 398 tools that may be useful in repairing a damaged NetBSD 399 installation. 400 401 Before "make iso-image-source" is attempted, RELEASEDIR 402 must be populated by "make sourcesets release" or 403 equivalent. 404 405 Note: Other, smaller, CD-ROM images may be created in the 406 RELEASEDIR/RELEASEMACHINEDIR/installation/cdrom directory 407 by "make release". These smaller images usually contain 408 the same tools as the larger images in RELEASEDIR/images, 409 but do not contain additional content such as the 410 distribution sets. 411 412 Note: The mac68k port still uses an older method of 413 creating CD-ROM images. This requires the mkisofs(1) 414 utility, which is not part of NetBSD, but which can be 415 installed from pkgsrc/sysutils/cdrtools. 416 417 install-image 418 Create a bootable NetBSD installation disk image in the 419 RELEASEDIR/images directory. The installation disk image 420 is suitable for copying to bootable USB flash memory 421 sticks, etc., for machines which are able to boot from such 422 devices. The file system in the bootable disk image will 423 have a layout as described in release(7). 424 425 The installation image is bootable, and will automatically 426 run the sysinst(8) menu-based installation program, which 427 can be used to install or upgrade a NetBSD system. The 428 image also contains tools that may be useful in repairing a 429 damaged NetBSD installation. 430 431 Before "make install-image" is attempted, RELEASEDIR must 432 be populated by "make release" or equivalent. The build 433 must have been performed with MKUNPRIVED=yes because "make 434 install-image" relies on information in DESTDIR/METALOG. 435 436 live-image Create NetBSD live images in the RELEASEDIR/images 437 directory. The live image contains all necessary files to 438 boot NetBSD up to multi-user mode, including all files 439 which should be extracted during installation, NetBSD 440 disklabel, bootloaders, etc. 441 442 The live image is suitable for use as a disk image in 443 virtual machine environments such as QEMU, and also useful 444 to boot NetBSD from a USB flash memory stick on a real 445 machine, without the need for installation. 446 447 Before "make live-image" is attempted, RELEASEDIR must be 448 populated by "make release" or equivalent. The build must 449 have been performed with MKUNPRIVED=yes because "make 450 install-image" relies on information in DESTDIR/METALOG. 451 452 regression-tests 453 Can only be run after building the regression tests in the 454 directory "regress". Runs those compiled regression tests 455 on the local host. 456 457 Note: Most tests are now managed instead using atf(7); this 458 target should probably run those as well but currently does 459 not. 460 461 The "build.sh" script 462 This script file is a shell script designed to build the entire NetBSD 463 system on any host with a suitable modern shell and some common 464 utilities. The required shell features are described under the HOST_SH 465 variable. 466 467 If a host system's default shell does support the required features, then 468 we suggest that you explicitly specify a suitable shell using a command 469 like 470 471 /path/to/suitable/shell build.sh [options] 472 473 The above command will usually enable build.sh to automatically set 474 HOST_SH=/path/to/suitable/shell, but if that fails, then the following 475 set of commands may be used instead: 476 477 HOST_SH=/path/to/suitable/shell 478 export HOST_SH 479 ${HOST_SH} build.sh [options] 480 481 If build.sh detects that it is being executed under an unsuitable shell, 482 it attempts to exec a suitable shell instead, or shows an error message. 483 If HOST_SH is not set explicitly, then build.sh sets a default using 484 heuristics dependent on the host platform, or from the shell under which 485 build.sh is executed (if that can be determined), or using the first copy 486 of sh found in PATH. 487 488 All cross-compile builds, and most native builds, of the entire system 489 should make use of build.sh rather than just running "make". This way, 490 the make(1) program will be bootstrapped properly, in case the host 491 system has an older or incompatible "make" program. 492 493 When compiling the entire system via build.sh, many make(1) variables are 494 set for you in order to help encapsulate the build process. In the list 495 of options below, variables that are automatically set by build.sh are 496 noted where applicable. 497 498 The following operations are supported by build.sh: 499 500 build Build the system as per "make build". Before the main part 501 of the build commences, this command runs the obj operation 502 (unless the -o option is given), "make cleandir" (unless 503 the -u option is given), and the tools operation. 504 505 distribution Build a full distribution as per "make distribution". This 506 command first runs the build operation. 507 508 release Build a full release as per "make release". This command 509 first runs the distribution operation. 510 511 help Show a help message, and exit. 512 513 makewrapper Create the nbmake-MACHINE wrapper. This operation is 514 automatically performed for any of the other operations. 515 516 cleandir Perform "make cleandir". 517 518 obj Perform "make obj". 519 520 tools Build and install the host tools from src/tools. This 521 command will first run "make obj" and "make cleandir" in 522 the tools subdirectory unless the -o or -u options 523 (respectively) are given. 524 525 install=idir Install the contents of DESTDIR to idir, using "make 526 installworld". 527 528 Note: Files that are part of the "etc" or "xetc" sets will 529 not be installed, unless overridden by the INSTALLSETS 530 environment variable. 531 532 kernel=kconf Build a new kernel. The kconf argument is the name of a 533 configuration file suitable for use by config(1). If kconf 534 does not contain any `/' characters, the configuration file 535 is expected to be found in the KERNCONFDIR directory, which 536 is typically sys/arch/MACHINE/conf. The new kernel will be 537 built in a subdirectory of KERNOBJDIR, which is typically 538 sys/arch/MACHINE/compile or an associated object directory. 539 540 This command does not imply the tools command; run the 541 tools command first unless it is certain that the tools 542 already exist and are up to date. 543 544 This command will run "make cleandir" on the kernel in 545 question first unless the -u option is given. 546 547 kernel.gdb=kconf 548 Build a new kernel with debug information. Similar to the 549 above kernel=kconf operation, but creates a netbsd.gdb file 550 alongside of the kernel netbsd, which contains a full 551 symbol table and can be used for debugging (for example 552 with a cross-gdb built by MKCROSSGDB). 553 554 kernels This command will build all kernels defined in port 555 specific release build procedure. 556 557 This command internally calls the kernel=kconf operation 558 for each found kernel configuration file. 559 560 modules This command will build kernel modules and install them 561 into DESTDIR. 562 563 releasekernel=kconf 564 Install a gzip(1)ed copy of the kernel previously built by 565 kernel=kconf into 566 RELEASEDIR/RELEASEMACHINEDIR/binary/kernel, usually as 567 netbsd-kconf.gz, although the "netbsd" prefix is determined 568 from the "config" directives in kconf. 569 570 sets Perform "make sets". 571 572 sourcesets Perform "make sourcesets". 573 574 syspkgs Perform "make syspkgs". 575 576 iso-image Perform "make iso-image". 577 578 iso-image-source 579 Perform "make iso-image-source". 580 581 install-image 582 Perform "make install-image". 583 584 live-image Perform "make live-image". 585 586 list-arch Show a list of valid MACHINE and MACHINE_ARCH settings, the 587 default MACHINE_ARCH for each MACHINE, and aliases for 588 MACHINE/MACHINE_ARCH pairs, and then exits. The -m or -a 589 options (or both) may be used to specify glob patterns that 590 will be used to narrow the list of results; for example, 591 "build.sh -m 'evb*' -a '*arm*' list-arch" will list all 592 known MACHINE/MACHINE_ARCH values in which either MACHINE 593 or ALIAS matches the pattern `evb*', and MACHINE_ARCH 594 matches the pattern `*arm*'. 595 596 The following command line options alter the behaviour of the build.sh 597 operations described above: 598 599 -a arch Set the value of MACHINE_ARCH to arch. See the -m option for 600 more information. 601 602 -B buildid 603 Set the value of BUILDID to buildid. This will also append the 604 build identifier to the name of the "make" wrapper script so 605 that the resulting name is of the form 606 "nbmake-MACHINE-BUILDID". 607 608 -C cdextras 609 Append cdextras to the CDEXTRA variable, which is a space- 610 separated list of files or directories that will be added to 611 the CD-ROM image that may be create by the "iso-image" or 612 "iso-image-source" operations. Files will be added to the root 613 of the CD-ROM image, whereas directories will be copied 614 recursively. If relative paths are specified, they will be 615 converted to absolute paths before being used. Multiple paths 616 may be specified via multiple -C options, or via a single 617 option whose argument contains multiple space-separated paths. 618 619 -c compiler 620 Select the compiler for the toolchain to build NetBSD and for 621 inclusion in the NetBSD distribution. Supported choices: 622 623 clang 624 625 gcc [default] 626 627 The compiler used to build the toolchain can be different; see 628 HOST_CC and HOST_CXX. 629 630 -D dest Set the value of DESTDIR to dest. If a relative path is 631 specified, it will be converted to an absolute path before 632 being used. 633 634 -E Set `expert' mode. This overrides various sanity checks, and 635 allows: DESTDIR does not have to be set to a non-root path for 636 builds, and MKUNPRIVED=yes does not have to be set when 637 building as a non-root user. 638 639 Note: It is highly recommended that you know what you are doing 640 when you use this option. 641 642 -h Show a help message, and exit. 643 644 -j njob Run up to njob make(1) subjobs in parallel; passed through to 645 make(1). If you see failures for reasons other than running 646 out of memory while using build.sh with -j, please save 647 complete build logs so the failures can be analyzed. 648 649 To achieve the fastest builds, -j values between (1 + the 650 number of CPUs) and (2 * the number of CPUs) are recommended. 651 Use lower values on machines with limited memory or I/O 652 bandwidth. 653 654 -M obj Set MAKEOBJDIRPREFIX to obj. Unsets MAKEOBJDIR. See "-O obj" 655 for more information. 656 657 For instance, if the source directory is /usr/src, a setting of 658 "-M /usr/obj" will place build-time files under 659 /usr/obj/usr/src/bin, /usr/obj/usr/src/lib, 660 /usr/obj/usr/src/usr.bin, and so forth. 661 662 If a relative path is specified, it will be converted to an 663 absolute path before being used. build.sh imposes the 664 restriction that the argument to the -M option must not begin 665 with a "$" (dollar sign) character; otherwise it would be too 666 difficult to determine whether the value is an absolute or a 667 relative path. If the directory does not already exist, 668 build.sh will create it. 669 670 -m mach Set the value of MACHINE to mach, unless the mach argument is 671 an alias that refers to a MACHINE/MACHINE_ARCH pair, in which 672 case both MACHINE and MACHINE_ARCH are set from the alias. 673 Such aliases are interpreted entirely by build.sh; they are not 674 used by any other part of the build system. The MACHINE_ARCH 675 setting implied by mach will override any value of MACHINE_ARCH 676 in the process environment, but will not override a value set 677 by the -a option. All cross builds require -m, but if unset on 678 a NetBSD host, the host's value of MACHINE will be detected and 679 used automatically. 680 681 See the list-arch operation for a way to get a list of valid 682 MACHINE and MACHINE_ARCH settings. 683 684 -N noiselevel 685 Set the "noisyness" level of the build, by setting MAKEVERBOSE 686 to noiselevel. 687 688 -n Show the commands that would be executed by build.sh, but do 689 not make any changes. This is similar in concept to "make -n". 690 691 -O obj Create an appropriate transform macro for MAKEOBJDIR that will 692 place the built object files under obj. Unsets 693 MAKEOBJDIRPREFIX. 694 695 For instance, a setting of "-O /usr/obj" will place build-time 696 files under /usr/obj/bin, /usr/obj/lib, /usr/obj/usr.bin, and 697 so forth. 698 699 If a relative path is specified, it will be converted to an 700 absolute path before being used. build.sh imposes the 701 restriction that the argument to the -O option must not contain 702 a "$" (dollar sign) character. If the directory does not 703 already exist, build.sh will create it. 704 705 In normal use, exactly one of the -M or -O options should be 706 specified. If neither -M nor -O is specified, then a default 707 object directory will be chosen according to rules in 708 <bsd.obj.mk>. Relying on this default is not recommended 709 because it is determined by complex rules that are influenced 710 by the values of several variables and by the location of the 711 source directory. 712 713 Note: Placing the obj directory location outside of the default 714 source tree hierarchy makes it easier to manually clear out old 715 files in the event the "make cleandir" operation is unable to 716 do so. (See CAVEATS below.) 717 718 Note: The use of one of -M or -O is the only means of building 719 multiple machine architecture userlands from the same source 720 tree without cleaning between builds (in which case, one would 721 specify distinct obj locations for each). 722 723 -o Set the value of MKOBJDIRS to "no". Otherwise, it will be 724 automatically set to "yes". This default is opposite to the 725 behaviour when not using build.sh. 726 727 -P Set the value of MKREPRO and MKREPRO_TIMESTAMP to the latest 728 source CVS timestamp for reproducible builds. 729 730 -R rel Set the value of RELEASEDIR to rel. If a relative path is 731 specified, it will be converted to an absolute path before 732 being used. 733 734 -r Remove the contents of DESTDIR and TOOLDIR before building 735 (provides a clean starting point). This will skip deleting 736 DESTDIR if building on a native system to the root directory. 737 738 -S seed Change the value of BUILDSEED to seed. This should rarely be 739 necessary. 740 741 -T tools Set the value of TOOLDIR to tools. If a relative path is 742 specified, it will be converted to an absolute path before 743 being used. If set, the bootstrap "make" will only be rebuilt 744 if the source files for make(1) have changed. 745 746 -U Set MKUNPRIVED=yes. 747 748 -u Set MKUPDATE=yes. 749 750 -V var=[value] 751 Set the environment variable var to an optional value. This is 752 propagated to the nbmake wrapper. 753 754 -w wrapper 755 Create the nbmake wrapper script (see below) in a custom 756 location, specified by wrapper. This allows, for instance, to 757 place the wrapper in PATH automatically. 758 759 Note: wrapper is the full name of the file, not just a 760 directory name. If a relative path is specified, it will be 761 converted to an absolute path before being used. 762 763 -X x11src 764 Set the value of X11SRCDIR to x11src. If a relative path is 765 specified, it will be converted to an absolute path before 766 being used. 767 768 -x Set MKX11=yes. 769 770 -Z var Unset ("zap") the environment variable var. This is propagated 771 to the nbmake wrapper. 772 773 -? Show a help message, and exit. 774 775 The "nbmake-MACHINE" wrapper script 776 If using the build.sh script to build NetBSD, a nbmake-MACHINE script 777 will be created in TOOLDIR/bin upon the first build to assist in building 778 subtrees on a cross-compile host. 779 780 nbmake-MACHINE can be invoked in lieu of make(1), and will instead call 781 the up-to-date version of "nbmake" installed into TOOLDIR/bin with 782 several key variables pre-set, including MACHINE, MACHINE_ARCH, and 783 TOOLDIR. nbmake-MACHINE will also set variables specified with -V, and 784 unset variables specified with -Z. 785 786 This script can be symlinked into a directory listed in PATH, or called 787 with an absolute path. 788 789EXAMPLES 790 1. % ./build.sh [OPTIONS] tools kernel=GENERIC 791 792 Build a new toolchain, and use the new toolchain to configure and 793 build a new GENERIC kernel. 794 795 2. % ./build.sh [OPTIONS] -U distribution 796 797 Using unprivileged mode, build a complete distribution to a DESTDIR 798 directory that build.sh selects (and will show). 799 800 3. # ./build.sh [OPTIONS] -U install=/ 801 802 As root, install to / the distribution that was built by example 2. 803 Even though this is run as root, -U is required so that the 804 permissions stored in DESTDIR/METALOG are correctly applied to the 805 files as they're copied to /. 806 807 4. % ./build.sh [OPTIONS] -U -u release 808 809 Using unprivileged mode, build a complete release to DESTDIR and 810 RELEASEDIR directories that build.sh selects (and will show). 811 MKUPDATE=yes (-u) is set to prevent the "make cleandir", so that if 812 this is run after example 2, it doesn't need to redo that portion of 813 the release build. 814 815SEE ALSO 816 config(1), ctags(1), ex(1), gzip(1), lint(1), make(1), mandoc(1), 817 mkisofs(1), nroff(1), vi(1), mk.conf(5), atf(7), hier(7), mdoc(7), 818 release(7), etcupdate(8), installboot(8), mount(8), postinstall(8), 819 sysinst(8), pkgsrc/sysutils/cdrtools 820 821 Note: The NetBSD manual pages are also available at 822 https://man.netbsd.org 823 824HISTORY 825 The build.sh based build scheme was introduced for NetBSD 1.6 as 826 USE_NEW_TOOLCHAIN, and re-worked to TOOLCHAIN_MISSING after that. 827 828CAVEATS 829 After significant updates to third-party components in the source tree, 830 the "make cleandir" operation may be insufficient to clean out old files 831 in object directories. Instead, one may have to manually remove the 832 files. Consult the UPDATING file for notices concerning this. 833 834NetBSD July 18, 2023 NetBSD 835