BUILDING revision 1.139
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 a special subtree, "tools", which uses the host 13 system to create a build toolchain for the target architecture. The host 14 system must have at least C and C++ compilers in order to create the 15 toolchain (make is not required); all other tools are created as part of 16 the NetBSD build process. (See the environment variables section below 17 if you need to override or manually select your compilers.) 18 19FILES 20 Source tree layout 21 doc/BUILDING.mdoc 22 This document (in -mdoc troff format; the original copy). 23 24 BUILDING This document (in plaintext). 25 26 tools/compat/README 27 Special notes for cross-hosting a NetBSD build on non- 28 NetBSD platforms. 29 30 Makefile The main Makefile for NetBSD; should only be run for 31 native builds with an appropriately up-to-date version of 32 NetBSD make(1). Intended for expert use with knowlege of 33 its shortcomings, it has been superseded by the build.sh 34 shell script as the recommended means for building NetBSD. 35 36 UPDATING Special notes for updating from an earlier revision of 37 NetBSD. It is important to read this file before every 38 build of an updated source tree. 39 40 build.sh Bourne-compatible shell script used for building the host 41 build tools and the NetBSD system from scratch. Can be 42 used for both native and cross builds, and should be used 43 instead of make(1) as it performs additional checks to 44 prevent common issues going undetected, such as building 45 with an outdated version of make(1). 46 47 crypto/dist/, dist/, gnu/dist/ 48 Sources imported verbatim from third parties, without 49 mangling the existing build structure. Other source trees 50 in bin through usr.sbin use the NetBSD make(1) "reachover" 51 Makefile semantics when building these programs for a 52 native host. 53 54 external, sys/external 55 Sources and build infrastructure for components imported 56 (mostly) unchanged from upstream maintainers, sorted by 57 applicable license. This is (slowly) replacing the 58 crypto/dist, dist, and gnu/dist directories. 59 60 distrib/, etc/ 61 Sources for items used when making a full release 62 snapshot, such as files installed in DESTDIR/etc on the 63 destination system, boot media, and release notes. 64 65 tests/, regress/ 66 Regression test harness. Can be cross-compiled, but only 67 run natively. tests/ uses the atf(7) test framework; 68 regress/ contains older tests that have not yet been 69 migrated to atf(7). 70 71 sys/ NetBSD kernel sources. 72 73 tools/ "Reachover" build structure for the host build tools. 74 This has a special method of determining out-of-date 75 status. 76 77 bin/ ... usr.sbin/ 78 Sources to the NetBSD userland (non-kernel) programs. If 79 any of these directories are missing, they will be skipped 80 during the build. 81 82 external/mit/xorg/ 83 "Reachover" build structure for modular Xorg; the source 84 is in X11SRCDIR. 85 86 extsrc/ "Reachover" build structure for externally added programs 87 and libraries; the source is in EXTSRCSRCDIR. 88 89 Build tree layout 90 The NetBSD build tree is described in hier(7), and the release layout is 91 described in release(7). 92 93CONFIGURATION 94 Environment variables 95 Several environment variables control the behaviour of NetBSD builds. 96 97 HOST_SH Path name to a shell available on the host system and 98 suitable for use during the build. The NetBSD build 99 system requires a modern Bourne-like shell with POSIX- 100 compliant features, and also requires support for the 101 "local" keyword to declare local variables in shell 102 functions (which is a widely-implemented but non- 103 standardised feature). 104 105 Depending on the host system, a suitable shell may be 106 /bin/sh, /usr/xpg4/bin/sh, /bin/ksh (provided it is a 107 variant of ksh that supports the "local" keyword, such 108 as ksh88, but not ksh93), or /usr/local/bin/bash. 109 110 Most parts of the build require HOST_SH to be an 111 absolute path; however, build.sh allows it to be a 112 simple command name, which will be converted to an 113 absolute path by searching the PATH. 114 115 HOST_CC Path name to C compiler used to create the toolchain. 116 117 HOST_CFLAGS Flags passed to the host C compiler. 118 119 HOST_CXX Path name to C++ compiler used to create the toolchain. 120 121 HOST_CXXFLAGS Flags passed to the host C++ compiler. 122 123 MACHINE Machine type, e.g., "macppc". 124 125 MACHINE_ARCH Machine architecture, e.g., "powerpc". 126 127 MAKE Path name to invoke make(1) as. 128 129 MAKEFLAGS Flags to invoke make(1) with. Note that build.sh 130 ignores the value of MAKEFLAGS passed in the 131 environment, but allows MAKEFLAGS to be set via the -V 132 option. 133 134 MAKEOBJDIR Directory to use as the .OBJDIR for the current 135 directory. The value is subjected to variable 136 expansion by make(1). Typical usage is to set this 137 variable to a value involving the use of 138 `${.CURDIR:S...}' or `${.CURDIR:C...}', to derive the 139 value of .OBJDIR from the value of .CURDIR. Used only 140 if MAKEOBJDIRPREFIX is not defined. MAKEOBJDIR can be 141 provided only in the environment or via the -O flag of 142 build.sh; it cannot usefully be set inside a Makefile, 143 including mk.conf or ${MAKECONF}. 144 145 MAKEOBJDIRPREFIX Top level directory of the object directory tree. The 146 value is subjected to variable expansion by make(1). 147 build.sh will create the ${MAKEOBJDIRPREFIX} directory 148 if necessary, but if make(1) is used without build.sh, 149 then rules in <bsd.obj.mk> will abort the build if the 150 ${MAKEOBJDIRPREFIX} directory does not exist. If the 151 value is defined and valid, then 152 ${MAKEOBJDIRPREFIX}/${.CURDIR} is used as the .OBJDIR 153 for the current directory. The current directory may 154 be read only. MAKEOBJDIRPREFIX can be provided only in 155 the environment or via the -M flag of build.sh; it 156 cannot usefully be set inside a Makefile, including 157 mk.conf or ${MAKECONF}. 158 159 "make" variables 160 Several variables control the behavior of NetBSD builds. Unless 161 otherwise specified, these variables may be set in either the process 162 environment or the make(1) configuration file specified by MAKECONF. 163 164 BUILDID Identifier for the build. If set, this should be a short 165 string that is suitable for use as part of a file or 166 directory name. The identifier will be appended to object 167 directory names, and can be consulted in the make(1) 168 configuration file in order to set additional build 169 parameters, such as compiler flags. It will also be used as 170 part of the kernel version string, which can be printed by 171 "uname -v". 172 173 Default: Unset. 174 175 BUILDINFO This may be a multi-line string containing information about 176 the build. This will appear in DESTDIR/etc/release, and it 177 will be stored in the buildinfo variable in any kernels that 178 are built. When such kernels are booted, the sysctl(7) 179 kern.buildinfo variable will report this value. The string 180 may contain backslash escape sequences, such as "\\" 181 (representing a backslash character) and "\n" (representing a 182 newline). 183 184 Default: Unset. 185 186 BUILDSEED GCC uses random numbers when compiling C++ code. This 187 variable seeds the gcc random number generator using the 188 -frandom-seed flag with this value. By default, it is set to 189 NetBSD-(majorversion). Using a fixed value causes C++ 190 binaries to be the same when built from the same sources, 191 resulting in identical (reproducible) builds. Additional 192 information is available in the GCC documentation of 193 -frandom-seed. 194 195 CPUFLAGS Additional flags to the compiler/assembler to select CPU 196 instruction set options, CPU tuning options, etc. 197 198 Default: Unset. 199 200 DESTDIR Directory to contain the built NetBSD system. If set, 201 special options are passed to the compilation tools to 202 prevent their default use of the host system's /usr/include, 203 /usr/lib, and so forth. This pathname must be an absolute 204 path, and should not end with a slash (/) character. (For 205 installation into the system's root directory, set DESTDIR to 206 an empty string, not to "/"). The directory must reside on a 207 file system which supports long file names and hard links. 208 209 Default: Empty string if USETOOLS is "yes"; unset otherwise. 210 211 Note: build.sh will provide a default of destdir.MACHINE (in 212 the top-level .OBJDIR) unless run in `expert' mode. 213 214 EXTSRCSRCDIR 215 Directory containing sources of externally added programs and 216 libraries. If specified, must be an absolute path. 217 218 Default: NETBSDSRCDIR/../extsrc, if that exists; otherwise 219 /usr/extsrc. 220 221 MAKECONF The name of the make(1) configuration file. Only settable in 222 the process environment. 223 224 Default: "/etc/mk.conf" 225 226 MAKEVERBOSE 227 Level of verbosity of status messages. Supported values: 228 229 0 No descriptive messages or commands executed by make(1) 230 are shown. 231 232 1 Brief messages are shown describing what is being done, 233 but the actual commands executed by make(1) are not 234 displayed. 235 236 2 Descriptive messages are shown as above (prefixed with a 237 `#'), and ordinary commands performed by make(1) are 238 displayed. 239 240 3 In addition to the above, all commands performed by 241 make(1) are displayed, even if they would ordinarily 242 have been hidden through use of the "@" prefix in the 243 relevant makefile. 244 245 4 In addition to the above, commands executed by make(1) 246 are traced through use of the sh(1) "-x" flag. 247 248 Default: 2 249 250 MKCROSSGDB Can be set to "yes" or "no". Create a cross-gdb as a host 251 tool. 252 253 Default: "no" 254 255 MKDEBUG Can be set to "yes" or "no". Indicates whether debug 256 information should be generated for all userland binaries 257 compiled. The result is collected as an additional debug.tgz 258 and xdebug.tgz set and installed in /usr/libdata/debug. 259 260 Default: "no" 261 262 MKDEBUGLIB Can be set to "yes" or "no". Indicates whether debug 263 information (see MKDEBUG) should also be generated for all 264 libraries built. 265 266 Default: "no" 267 268 MKDOC Can be set to "yes" or "no". Indicates whether system 269 documentation destined for DESTDIR/usr/share/doc will be 270 installed during a build. 271 272 Default: "yes" 273 274 MKEXTSRC Can be set to "yes" or "no". Indicates whether extsrc is 275 built from EXTSRCSRCDIR. 276 277 Default: "no" 278 279 MKHTML Can be set to "yes" or "no". Indicates whether preformatted 280 HTML manual pages will be built and installed 281 282 Default: "yes" 283 284 MKHOSTOBJ Can be set to "yes" or "no". If set to "yes", then for 285 programs intended to be run on the compile host, the name, 286 release, and architecture of the host operating system will 287 be suffixed to the name of the object directory created by 288 "make obj". (This allows multiple host systems to compile 289 NetBSD for a single target.) If set to "no", then programs 290 built to be run on the compile host will use the same object 291 directory names as programs built to be run on the target. 292 293 Default: "no" 294 295 MKINFO Can be set to "yes" or "no". Indicates whether GNU Info 296 files will be created and installed during a build. GNU Info 297 files are used for providing documentation by most of the 298 compilation tools. 299 300 Default: "yes" 301 302 MKKDEBUG Can be set to "yes" or "no". Force generation of full-debug 303 symbol versions of all kernels compiled. Alongside of the 304 netbsd kernel file, an unstripped version netbsd.gdb is 305 created. This is useful if a cross-gdb is built as well (see 306 MKCROSSGDB). 307 308 Default: "no" 309 310 MKKMOD Can be set to "yes" or "no". Indicates whether kernel 311 modules are built and installed. 312 313 Default: "yes" 314 315 MKLINT Can be set to "yes" or "no". Indicates whether lint(1) will 316 be run against portions of the NetBSD source code during the 317 build, and whether lint libraries will be installed into 318 DESTDIR/usr/libdata/lint. 319 320 Default: "yes" 321 322 MKMAN Can be set to "yes" or "no". Indicates whether manual pages 323 will be installed during a build. 324 325 Default: "yes" 326 327 MKNLS Can be set to "yes" or "no". Indicates whether Native 328 Language System locale zone files will be compiled and 329 installed during a build. 330 331 Default: "yes" 332 333 MKOBJ Can be set to "yes" or "no". Indicates whether object 334 directories will be created when running "make obj". If set 335 to "no", then all built files will be located inside the 336 regular source tree. 337 338 Default: "yes" 339 340 Note that setting MKOBJ to "no" is not recommended and may 341 cause problems when updating the tree with cvs(1). 342 343 MKPIC Can be set to "yes" or "no". Indicates whether shared 344 objects and libraries will be created and installed during a 345 build. If set to "no", the entire built system will be 346 statically linked. 347 348 Default: Platform dependent. As of this writing, all 349 platforms except m68000 default to "yes". 350 351 MKPICINSTALL 352 Can be set to "yes" or "no". Indicates whether the ar(1) 353 format libraries (lib*_pic.a), used to generate shared 354 libraries, are installed during a build. 355 356 Default: "yes" 357 358 MKPROFILE Can be set to "yes" or "no". Indicates whether profiled 359 libraries (lib*_p.a) will be built and installed during a 360 build. 361 362 Default: "yes"; however, some platforms turn off MKPROFILE by 363 default at times due to toolchain problems with profiled 364 code. 365 366 MKREPRO Can be set to "yes" or "no". Create reproducible builds. 367 This enables different switches to make two builds from the 368 same source tree result in the same build results. 369 370 Default: "no" This may be set to "yes" by giving build.sh the 371 -P option. 372 373 MKREPRO_TIMESTAMP 374 Unix timestamp. When MKREPRO is set, the timestamp of all 375 files in the sets will be set to this value. 376 377 Default: Unset. This may be set automatically to the latest 378 source tree timestamp using cvslatest(1) by giving build.sh 379 the -P option. 380 381 MKSHARE Can be set to "yes" or "no". Indicates whether files 382 destined to reside in DESTDIR/usr/share will be built and 383 installed during a build. If set to "no", then all of MKDOC, 384 MKINFO, MKMAN, and MKNLS will be set to "no" unconditionally. 385 386 Default: "yes" 387 388 MKSTRIPIDENT 389 Can be set to "yes" or "no". Indicates whether RCS IDs, for 390 use with ident(1), should be stripped from program binaries 391 and shared libraries. 392 393 Default: "no" 394 395 MKSTRIPSYM Can be set to "yes" or "no". Indicates whether all local 396 symbols should be stripped from shared libraries. If "yes", 397 strip all local symbols from shared libraries; the affect is 398 equivalent to the -x option of ld(1). If "no", strip only 399 temporary local symbols; the affect is equivalent to the -X 400 option of ld(1). Keeping non-temporary local symbols such as 401 static function names is useful on using DTrace for userland 402 libraries and getting a backtrace from a rump kernel loading 403 shared libraries. 404 405 Default: "yes" 406 407 MKUNPRIVED Can be set to "yes" or "no". Indicates whether an 408 unprivileged install will occur. The user, group, 409 permissions, and file flags, will not be set on the installed 410 items; instead the information will be appended to a file 411 called METALOG in DESTDIR. The contents of METALOG are used 412 during the generation of the distribution tar files to ensure 413 that the appropriate file ownership is stored. 414 415 Default: "no" 416 417 MKUPDATE Can be set to "yes" or "no". Indicates whether all install 418 operations intended to write to DESTDIR will compare file 419 timestamps before installing, and skip the install phase if 420 the destination files are up-to-date. This also has 421 implications on full builds (see next subsection). 422 423 Default: "no" 424 425 MKX11 Can be set to "yes" or "no". Indicates whether X11 is built 426 from X11SRCDIR. 427 428 Default: "no" 429 430 TOOLDIR Directory to hold the host tools, once built. If specified, 431 must be an absolute path. This directory should be unique to 432 a given host system and NetBSD source tree. (However, 433 multiple targets may share the same TOOLDIR; the target- 434 dependent files have unique names.) If unset, a default 435 based on the uname(1) information of the host platform will 436 be created in the .OBJDIR of src. 437 438 Default: Unset. 439 440 USETOOLS Indicates whether the tools specified by TOOLDIR should be 441 used as part of a build in progress. Must be set to "yes" if 442 cross-compiling. 443 444 yes Use the tools from TOOLDIR. 445 446 no Do not use the tools from TOOLDIR, but refuse to build 447 native compilation tool components that are version- 448 specific for that tool. 449 450 never Do not use the tools from TOOLDIR, even when building 451 native tool components. This is similar to the 452 traditional NetBSD build method, but does not verify 453 that the compilation tools in use are up-to-date 454 enough in order to build the tree successfully. This 455 may cause build or runtime problems when building the 456 whole NetBSD source tree. 457 458 Default: "yes", unless TOOLCHAIN_MISSING is set to "yes". 459 460 USETOOLS is also set to "no" when using <bsd.*.mk> outside 461 the NetBSD source tree. 462 463 X11SRCDIR Directory containing the modular Xorg source. If specified, 464 must be an absolute path. The main modular Xorg source is 465 found in X11SRCDIR/external/mit. 466 467 Default: NETBSDSRCDIR/../xsrc, if that exists; otherwise 468 /usr/xsrc. 469 470 "make" variables for full builds 471 These variables only affect the top level "Makefile" and do not affect 472 manually building subtrees of the NetBSD source code. 473 474 INSTALLWORLDDIR Location for the "make installworld" target to install 475 to. If specified, must be an absolute path. 476 477 Default: "/" 478 479 MKOBJDIRS Can be set to "yes" or "no". Indicates whether object 480 directories will be created automatically (via a "make 481 obj" pass) at the start of a build. 482 483 Default: "no" 484 485 If using build.sh, the default is "yes". This may be 486 set back to "no" by giving build.sh the -o option. 487 488 MKUPDATE Can be set to "yes" or "no". If set, then in addition 489 to the effects described for MKUPDATE=yes above, this 490 implies the effects of NOCLEANDIR (i.e., "make cleandir" 491 is avoided). 492 493 Default: "no" 494 495 If using build.sh, this may be set by giving the -u 496 option. 497 498 NBUILDJOBS Now obsolete. Use the make(1) option -j, instead. See 499 below. 500 501 Default: Unset. 502 503 NOCLEANDIR If set, avoids the "make cleandir" phase of a full 504 build. This has the effect of allowing only changed 505 files in a source tree to be recompiled. This can speed 506 up builds when updating only a few files in the tree. 507 508 Default: Unset. 509 510 See also MKUPDATE. 511 512 NODISTRIBDIRS If set, avoids the "make distrib-dirs" phase of a full 513 build. This skips running mtree(8) on DESTDIR, useful 514 on systems where building as an unprivileged user, or 515 where it is known that the system-wide mtree files have 516 not changed. 517 518 Default: Unset. 519 520 NOINCLUDES If set, avoids the "make includes" phase of a full 521 build. This has the effect of preventing make(1) from 522 thinking that some programs are out-of-date simply 523 because the system include files have changed. However, 524 this option should not be used when updating the entire 525 NetBSD source tree arbitrarily; it is suggested to use 526 MKUPDATE=yes instead in that case. 527 528 Default: Unset. 529 530 RELEASEDIR If set, specifies the directory to which a release(7) 531 layout will be written at the end of a "make release". 532 If specified, must be an absolute path. 533 534 Default: Unset. 535 536 Note: build.sh will provide a default of releasedir (in 537 the top-level .OBJDIR) unless run in `expert' mode. 538 539BUILDING 540 "make" command line options 541 This is not a summary of all the options available to make(1); only the 542 options used most frequently with NetBSD builds are listed here. 543 544 -j njob Run up to njob make(1) subjobs in parallel. Makefiles should 545 use .WAIT or have explicit dependencies as necessary to 546 enforce build ordering. 547 548 -m dir Specify the default directory for searching for system 549 Makefile segments, mainly the <bsd.*.mk> files. When building 550 any full NetBSD source tree, this should be set to the 551 "share/mk" directory in the source tree. This is set 552 automatically when building from the top level, or when using 553 build.sh. 554 555 -n Display the commands that would have been executed, but do not 556 actually execute them. This will still cause recursion to 557 take place. 558 559 -V var Print make(1)'s idea of the value of var. Does not build any 560 targets. 561 562 var=value Set the variable var to value, overriding any setting 563 specified by the process environment, the MAKECONF 564 configuration file, or the system Makefile segments. 565 566 "make" targets 567 These default targets may be built by running make(1) in any subtree of 568 the NetBSD source code. It is recommended that none of these be used 569 from the top level Makefile; as a specific exception, "make obj" and 570 "make cleandir" are useful in that context. 571 572 all Build programs, libraries, and preformatted documentation. 573 574 clean Remove program and library object code files. 575 576 cleandir Same as clean, but also remove preformatted documentation, 577 dependency files generated by "make depend", and any other 578 files known to be created at build time. 579 580 depend Create dependency files (.depend) containing more detailed 581 information about the dependencies of source code on header 582 files. Allows programs to be recompiled automatically when a 583 dependency changes. 584 585 dependall Does a "make depend" immediately followed by a "make all". 586 This improves cache locality of the build since both passes 587 read the source files in their entirety. 588 589 distclean Synonym for cleandir. 590 591 includes Build and install system header files. Typically needed 592 before any system libraries or programs can be built. 593 594 install Install programs, libraries, and documentation into DESTDIR. 595 Few files will be installed to DESTDIR/dev, DESTDIR/etc, 596 DESTDIR/root or DESTDIR/var in order to prevent user supplied 597 configuration data from being overwritten. 598 599 lint Run lint(1) against the C source code, where appropriate, and 600 generate system-installed lint libraries. 601 602 obj Create object directories to be used for built files, instead 603 of building directly in the source tree. 604 605 tags Create ctags(1) searchable function lists usable by the ex(1) 606 and vi(1) text editors. 607 608 "make" targets for the top level 609 Additional make(1) targets are usable specifically from the top source 610 level to facilitate building the entire NetBSD source tree. 611 612 build Build the entire NetBSD system (except the kernel). This 613 orders portions of the source tree such that prerequisites 614 will be built in the proper order. 615 616 distribution Do a "make build", and then install a full distribution 617 (which does not include a kernel) into DESTDIR, including 618 files in DESTDIR/dev, DESTDIR/etc, DESTDIR/root and 619 DESTDIR/var. 620 621 buildworld As per "make distribution", except that it ensures that 622 DESTDIR is not the root directory. 623 624 installworld Install the distribution from DESTDIR to INSTALLWORLDDIR, 625 which defaults to the root directory. Ensures that 626 INSTALLWORLDDIR is not the root directory if cross 627 compiling. 628 629 The INSTALLSETS environment variable may be set to a space- 630 separated list of distribution sets to be installed. By 631 default, all sets except "etc" and "xetc" are installed, so 632 most files in INSTALLWORLDDIR/etc will not be installed or 633 modified. 634 635 Note: Before performing this operation with 636 INSTALLWORLDDIR=/, it is highly recommended that you 637 upgrade your kernel and reboot. After performing this 638 operation, it is recommended that you use etcupdate(8) to 639 update files in INSTALLWORLDDIR/etc, and postinstall(8) to 640 check for or fix inconsistencies. 641 642 sets Create distribution sets from DESTDIR into 643 RELEASEDIR/RELEASEMACHINEDIR/binary/sets. Should be run 644 after "make distribution", as "make build" alone does not 645 install all of the required files. 646 647 sourcesets Create source sets of the source tree into 648 RELEASEDIR/source/sets. 649 650 syspkgs Create syspkgs from DESTDIR into 651 RELEASEDIR/RELEASEMACHINEDIR/binary/syspkgs. Should be run 652 after "make distribution", as "make build" alone does not 653 install all of the required files. 654 655 release Do a "make distribution", build kernels, distribution 656 media, and install sets (this as per "make sets"), and then 657 package the system into a standard release layout as 658 described by release(7). This requires that RELEASEDIR be 659 set (see above). 660 661 iso-image Create a NetBSD installation CD-ROM image in the 662 RELEASEDIR/images directory. The CD-ROM file system will 663 have a layout as described in release(7). 664 665 For most machine types, the CD-ROM will be bootable, and 666 will automatically run the sysinst(8) menu-based 667 installation program, which can be used to install or 668 upgrade a NetBSD system. Bootable CD-ROMs also contain 669 tools that may be useful in repairing a damaged NetBSD 670 installation. 671 672 Before "make iso-image" is attempted, RELEASEDIR must be 673 populated by "make release" or equivalent. 674 675 Note that other, smaller, CD-ROM images may be created in 676 the RELEASEDIR/RELEASEMACHINEDIR/installation/cdrom 677 directory by "make release". These smaller images usually 678 contain the same tools as the larger images in 679 RELEASEDIR/images, but do not contain additional content 680 such as the distribution sets. 681 682 Note that the mac68k port still uses an older method of 683 creating CD-ROM images. This requires the mkisofs(1) 684 utility, which is not part of NetBSD, but which can be 685 installed from pkgsrc/sysutils/cdrtools. 686 687 iso-image-source 688 Create a NetBSD installation CD-ROM image in the 689 RELEASEDIR/images directory. The CD-ROM file system will 690 have a layout as described in release(7). It will have top 691 level directories for the machine type and source. 692 693 For most machine types, the CD-ROM will be bootable, and 694 will automatically run the sysinst(8) menu-based 695 installation program, which can be used to install or 696 upgrade a NetBSD system. Bootable CD-ROMs also contain 697 tools that may be useful in repairing a damaged NetBSD 698 installation. 699 700 Before "make iso-image-source" is attempted, RELEASEDIR 701 must be populated by "make sourcesets release" or 702 equivalent. 703 704 Note that other, smaller, CD-ROM images may be created in 705 the RELEASEDIR/RELEASEMACHINEDIR/installation/cdrom 706 directory by "make release". These smaller images usually 707 contain the same tools as the larger images in 708 RELEASEDIR/images, but do not contain additional content 709 such as the distribution sets. 710 711 Note that the mac68k port still uses an older method of 712 creating CD-ROM images. This requires the mkisofs(1) 713 utility, which is not part of NetBSD, but which can be 714 installed from pkgsrc/sysutils/cdrtools. 715 716 install-image 717 Create a bootable NetBSD installation disk image in the 718 RELEASEDIR/images directory. The installation disk image 719 is suitable for copying to bootable USB flash memory 720 sticks, etc., for machines which are able to boot from such 721 devices. The file system in the bootable disk image will 722 have a layout as described in release(7). 723 724 The installation image is bootable, and will automatically 725 run the sysinst(8) menu-based installation program, which 726 can be used to install or upgrade a NetBSD system. The 727 image also contains tools that may be useful in repairing a 728 damaged NetBSD installation. 729 730 Before "make install-image" is attempted, RELEASEDIR must 731 be populated by "make release" or equivalent. The build 732 must have been performed with MKUNPRIVED=yes because "make 733 install-image" relies on information in DESTDIR/METALOG. 734 735 live-image Create NetBSD live images in the RELEASEDIR/images 736 directory. The live image contains all necessary files to 737 boot NetBSD up to multi-user mode, including all files 738 which should be extracted during installation, NetBSD 739 disklabel, bootloaders, etc. 740 741 The live image is suitable for use as a disk image in 742 virtual machine environments such as QEMU, and also useful 743 to boot NetBSD from a USB flash memory stick on a real 744 machine, without the need for installation. 745 746 Before "make live-image" is attempted, RELEASEDIR must be 747 populated by "make release" or equivalent. The build must 748 have been performed with MKUNPRIVED=yes because "make 749 install-image" relies on information in DESTDIR/METALOG. 750 751 regression-tests 752 Can only be run after building the regression tests in the 753 directory "regress". Runs those compiled regression tests 754 on the local host. Note that most tests are now managed 755 instead using atf(7); this target should probably run those 756 as well but currently does not. 757 758 The "build.sh" script 759 This script file is a shell script designed to build the entire NetBSD 760 system on any host with a suitable modern shell and some common 761 utilities. The required shell features are described under the HOST_SH 762 variable. 763 764 If a host system's default shell does support the required features, then 765 we suggest that you explicitly specify a suitable shell using a command 766 like 767 768 /path/to/suitable/shell build.sh [options] 769 770 The above command will usually enable build.sh to automatically set 771 HOST_SH=/path/to/suitable/shell, but if that fails, then the following 772 set of commands may be used instead: 773 774 HOST_SH=/path/to/suitable/shell 775 export HOST_SH 776 ${HOST_SH} build.sh [options] 777 778 If build.sh detects that it is being executed under an unsuitable shell, 779 it attempts to exec a suitable shell instead, or prints an error message. 780 If HOST_SH is not set explicitly, then build.sh sets a default using 781 heuristics dependent on the host platform, or from the shell under which 782 build.sh is executed (if that can be determined), or using the first copy 783 of sh found in PATH. 784 785 All cross-compile builds, and most native builds, of the entire system 786 should make use of build.sh rather than just running "make". This way, 787 the make(1) program will be bootstrapped properly, in case the host 788 system has an older or incompatible "make" program. 789 790 When compiling the entire system via build.sh, many make(1) variables are 791 set for you in order to help encapsulate the build process. In the list 792 of options below, variables that are automatically set by build.sh are 793 noted where applicable. 794 795 The following operations are supported by build.sh: 796 797 build Build the system as per "make build". Before the main part 798 of the build commences, this command runs the obj operation 799 (unless the -o option is given), "make cleandir" (unless 800 the -u option is given), and the tools operation. 801 802 distribution Build a full distribution as per "make distribution". This 803 command first runs the build operation. 804 805 release Build a full release as per "make release". This command 806 first runs the distribution operation. 807 808 makewrapper Create the nbmake-MACHINE wrapper. This operation is 809 automatically performed for any of the other operations. 810 811 cleandir Perform "make cleandir". 812 813 obj Perform "make obj". 814 815 tools Build and install the host tools from src/tools. This 816 command will first run "make obj" and "make cleandir" in 817 the tools subdirectory unless the -o or -u options 818 (respectively) are given. 819 820 install=idir Install the contents of DESTDIR to idir, using "make 821 installworld". Note that files that are part of the "etc" 822 or "xetc" sets will not be installed, unless overridden by 823 the INSTALLSETS environment variable. 824 825 kernel=kconf Build a new kernel. The kconf argument is the name of a 826 configuration file suitable for use by config(1). If kconf 827 does not contain any `/' characters, the configuration file 828 is expected to be found in the KERNCONFDIR directory, which 829 is typically sys/arch/MACHINE/conf. The new kernel will be 830 built in a subdirectory of KERNOBJDIR, which is typically 831 sys/arch/MACHINE/compile or an associated object directory. 832 833 This command does not imply the tools command; run the 834 tools command first unless it is certain that the tools 835 already exist and are up to date. 836 837 This command will run "make cleandir" on the kernel in 838 question first unless the -u option is given. 839 840 kernel.gdb=kconf 841 Build a new kernel with debug information. Similar to the 842 above kernel=kconf operation, but creates a netbsd.gdb file 843 alongside of the kernel netbsd, which contains a full 844 symbol table and can be used for debugging (for example 845 with a cross-gdb built by MKCROSSGDB). 846 847 kernels This command will build all kernels defined in port 848 specific release build procedure. 849 850 This command internally calls the kernel=kconf operation 851 for each found kernel configuration file. 852 853 modules This command will build kernel modules and install them 854 into DESTDIR. 855 856 releasekernel=kconf 857 Install a gzip(1)ed copy of the kernel previously built by 858 kernel=kconf into 859 RELEASEDIR/RELEASEMACHINEDIR/binary/kernel, usually as 860 netbsd-kconf.gz, although the "netbsd" prefix is determined 861 from the "config" directives in kconf. 862 863 sets Perform "make sets". 864 865 sourcesets Perform "make sourcesets". 866 867 syspkgs Perform "make syspkgs". 868 869 iso-image Perform "make iso-image". 870 871 iso-image-source 872 Perform "make iso-image-source". 873 874 install-image 875 Perform "make install-image". 876 877 live-image Perform "make live-image". 878 879 list-arch Prints a list of valid MACHINE and MACHINE_ARCH settings, 880 the default MACHINE_ARCH for each MACHINE, and aliases for 881 MACHINE/MACHINE_ARCH pairs, and then exits. The -m or -a 882 options (or both) may be used to specify glob patterns that 883 will be used to narrow the list of results; for example, 884 "build.sh -m 'evb*' -a '*arm*' list-arch" will list all 885 known MACHINE/MACHINE_ARCH values in which either MACHINE 886 or ALIAS matches the pattern `evb*', and MACHINE_ARCH 887 matches the pattern `*arm*'. 888 889 The following command line options alter the behaviour of the build.sh 890 operations described above: 891 892 -a arch Set the value of MACHINE_ARCH to arch. See the -m option for 893 more information. 894 895 -B buildid 896 Set the value of BUILDID to buildid. This will also append the 897 build identifier to the name of the "make" wrapper script so 898 that the resulting name is of the form 899 "nbmake-MACHINE-BUILDID". 900 901 -C cdextras 902 Append cdextras to the CDEXTRA variable, which is a space- 903 separated list of files or directories that will be added to 904 the CD-ROM image that may be create by the "iso-image" or 905 "iso-image-source" operations. Files will be added to the root 906 of the CD-ROM image, whereas directories will be copied 907 recursively. If relative paths are specified, they will be 908 converted to absolute paths before being used. Multiple paths 909 may be specified via multiple -C options, or via a single 910 option whose argument contains multiple space-separated paths. 911 912 -c compiler 913 Select the compiler for the toolchain to build NetBSD and for 914 inclusion in the NetBSD distribution. Supported choices: 915 916 clang 917 918 gcc [default] 919 920 The compiler used to build the toolchain can be different; see 921 HOST_CC and HOST_CXX. 922 923 -D dest Set the value of DESTDIR to dest. If a relative path is 924 specified, it will be converted to an absolute path before 925 being used. 926 927 -E Set `expert' mode. This overrides various sanity checks, and 928 allows: DESTDIR does not have to be set to a non-root path for 929 builds, and MKUNPRIVED=yes does not have to be set when 930 building as a non-root user. 931 932 Note: It is highly recommended that you know what you are doing 933 when you use this option. 934 935 -h Print a help message. 936 937 -j njob Run up to njob make(1) subjobs in parallel; passed through to 938 make(1). If you see failures for reasons other than running 939 out of memory while using build.sh with -j, please save 940 complete build logs so the failures can be analyzed. 941 942 To achieve the fastest builds, -j values between (1 + the 943 number of CPUs) and (2 * the number of CPUs) are recommended. 944 Use lower values on machines with limited memory or I/O 945 bandwidth. 946 947 -M obj Set MAKEOBJDIRPREFIX to obj. Unsets MAKEOBJDIR. See "-O obj" 948 for more information. 949 950 For instance, if the source directory is /usr/src, a setting of 951 "-M /usr/obj" will place build-time files under 952 /usr/obj/usr/src/bin, /usr/obj/usr/src/lib, 953 /usr/obj/usr/src/usr.bin, and so forth. 954 955 If a relative path is specified, it will be converted to an 956 absolute path before being used. build.sh imposes the 957 restriction that the argument to the -M option must not begin 958 with a "$" (dollar sign) character; otherwise it would be too 959 difficult to determine whether the value is an absolute or a 960 relative path. If the directory does not already exist, 961 build.sh will create it. 962 963 -m mach Set the value of MACHINE to mach, unless the mach argument is 964 an alias that refers to a MACHINE/MACHINE_ARCH pair, in which 965 case both MACHINE and MACHINE_ARCH are set from the alias. 966 Such aliases are interpreted entirely by build.sh; they are not 967 used by any other part of the build system. The MACHINE_ARCH 968 setting implied by mach will override any value of MACHINE_ARCH 969 in the process environment, but will not override a value set 970 by the -a option. All cross builds require -m, but if unset on 971 a NetBSD host, the host's value of MACHINE will be detected and 972 used automatically. 973 974 See the list-arch operation for a way to get a list of valid 975 MACHINE and MACHINE_ARCH settings. 976 977 -N noiselevel 978 Set the "noisyness" level of the build, by setting MAKEVERBOSE 979 to noiselevel. 980 981 -n Show the commands that would be executed by build.sh, but do 982 not make any changes. This is similar in concept to "make -n". 983 984 -O obj Create an appropriate transform macro for MAKEOBJDIR that will 985 place the built object files under obj. Unsets 986 MAKEOBJDIRPREFIX. 987 988 For instance, a setting of "-O /usr/obj" will place build-time 989 files under /usr/obj/bin, /usr/obj/lib, /usr/obj/usr.bin, and 990 so forth. 991 992 If a relative path is specified, it will be converted to an 993 absolute path before being used. build.sh imposes the 994 restriction that the argument to the -O option must not contain 995 a "$" (dollar sign) character. If the directory does not 996 already exist, build.sh will create it. 997 998 In normal use, exactly one of the -M or -O options should be 999 specified. If neither -M nor -O is specified, then a default 1000 object directory will be chosen according to rules in 1001 <bsd.obj.mk>. Relying on this default is not recommended 1002 because it is determined by complex rules that are influenced 1003 by the values of several variables and by the location of the 1004 source directory. 1005 1006 Note that placing the obj directory location outside of the 1007 default source tree hierarchy makes it easier to manually clear 1008 out old files in the event the "make cleandir" operation is 1009 unable to do so. (See CAVEATS below.) 1010 1011 Note also that use of one of -M or -O is the only means of 1012 building multiple machine architecture userlands from the same 1013 source tree without cleaning between builds (in which case, one 1014 would specify distinct obj locations for each). 1015 1016 -o Set the value of MKOBJDIRS to "no". Otherwise, it will be 1017 automatically set to "yes". This default is opposite to the 1018 behaviour when not using build.sh. 1019 1020 -R rel Set the value of RELEASEDIR to rel. If a relative path is 1021 specified, it will be converted to an absolute path before 1022 being used. 1023 1024 -r Remove the contents of DESTDIR and TOOLDIR before building 1025 (provides a clean starting point). This will skip deleting 1026 DESTDIR if building on a native system to the root directory. 1027 1028 -S seed Change the value of BUILDSEED to seed. This should rarely be 1029 necessary. 1030 1031 -T tools Set the value of TOOLDIR to tools. If a relative path is 1032 specified, it will be converted to an absolute path before 1033 being used. If set, the bootstrap "make" will only be rebuilt 1034 if the source files for make(1) have changed. 1035 1036 -U Set MKUNPRIVED=yes. 1037 1038 -u Set MKUPDATE=yes. 1039 1040 -V var=[value] 1041 Set the environment variable var to an optional value. This is 1042 propagated to the nbmake wrapper. 1043 1044 -w wrapper 1045 Create the nbmake wrapper script (see below) in a custom 1046 location, specified by wrapper. This allows, for instance, to 1047 place the wrapper in PATH automatically. Note that wrapper is 1048 the full name of the file, not just a directory name. If a 1049 relative path is specified, it will be converted to an absolute 1050 path before being used. 1051 1052 -X x11src 1053 Set the value of X11SRCDIR to x11src. If a relative path is 1054 specified, it will be converted to an absolute path before 1055 being used. 1056 1057 -x Set MKX11=yes. 1058 1059 -Y extsrcdir 1060 Set the value of EXTSRCSRCDIR to extsrcdir. If a relative path 1061 is specified, it will be converted to an absolute path before 1062 being used. 1063 1064 -y Set MKEXTSRC=yes. 1065 1066 -Z var Unset ("zap") the environment variable var. This is propagated 1067 to the nbmake wrapper. 1068 1069 The "nbmake-MACHINE" wrapper script 1070 If using the build.sh script to build NetBSD, a nbmake-MACHINE script 1071 will be created in TOOLDIR/bin upon the first build to assist in building 1072 subtrees on a cross-compile host. 1073 1074 nbmake-MACHINE can be invoked in lieu of make(1), and will instead call 1075 the up-to-date version of "nbmake" installed into TOOLDIR/bin with 1076 several key variables pre-set, including MACHINE, MACHINE_ARCH, and 1077 TOOLDIR. nbmake-MACHINE will also set variables specified with -V, and 1078 unset variables specified with -Z. 1079 1080 This script can be symlinked into a directory listed in PATH, or called 1081 with an absolute path. 1082 1083EXAMPLES 1084 1. % ./build.sh [options] tools kernel=GENERIC 1085 1086 Build a new toolchain, and use the new toolchain to configure and 1087 build a new GENERIC kernel. 1088 1089 2. % ./build.sh [options] -U distribution 1090 1091 Using unprivileged mode, build a complete distribution to a DESTDIR 1092 directory that build.sh selects (and will display). 1093 1094 3. # ./build.sh [options] -U install=/ 1095 1096 As root, install to / the distribution that was built by example 2. 1097 Even though this is run as root, -U is required so that the 1098 permissions stored in DESTDIR/METALOG are correctly applied to the 1099 files as they're copied to /. 1100 1101 4. % ./build.sh [options] -U -u release 1102 1103 Using unprivileged mode, build a complete release to DESTDIR and 1104 RELEASEDIR directories that build.sh selects (and will display). 1105 MKUPDATE=yes (-u) is set to prevent the "make cleandir", so that if 1106 this is run after example 2, it doesn't need to redo that portion of 1107 the release build. 1108 1109OBSOLETE VARIABLES 1110 NBUILDJOBS Use the make(1) option -j instead. 1111 1112 USE_NEW_TOOLCHAIN 1113 The new toolchain is now the default. To disable, use 1114 TOOLCHAIN_MISSING=yes. 1115 1116SEE ALSO 1117 make(1), hier(7), release(7), etcupdate(8), postinstall(8), sysinst(8), 1118 pkgsrc/sysutils/cdrtools 1119 1120HISTORY 1121 The build.sh based build scheme was introduced for NetBSD 1.6 as 1122 USE_NEW_TOOLCHAIN, and re-worked to TOOLCHAIN_MISSING after that. 1123 1124CAVEATS 1125 After significant updates to third-party components in the source tree, 1126 the "make cleandir" operation may be insufficient to clean out old files 1127 in object directories. Instead, one may have to manually remove the 1128 files. Consult the UPDATING file for notices concerning this. 1129 1130NetBSD October 13, 2020 NetBSD 1131