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