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