BUILDING revision 1.101
1BUILDING(8) NetBSD 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 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 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). (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 81CONFIGURATION 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: ``yes'' 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 program 317 binaries and shared libraries should be built to include RCS 318 IDs for use with ident(1). 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 460BUILDING 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 that you use 561 postinstall(8) to check for inconsistencies (and possibly 562 to fix them). 563 564 sets Create distribution sets from DESTDIR into 565 RELEASEDIR/RELEASEMACHINEDIR/binary/sets. Should be run 566 after ``make distribution'', as ``make build'' alone does 567 not install all of the required files. 568 569 sourcesets Create source sets of the source tree into 570 RELEASEDIR/source/sets. 571 572 syspkgs Create syspkgs from DESTDIR into 573 RELEASEDIR/RELEASEMACHINEDIR/binary/syspkgs. Should be run 574 after ``make distribution'', as ``make build'' alone does 575 not install all of the required files. 576 577 release Do a ``make distribution'', build kernels, distribution 578 media, and install sets (this as per ``make sets''), and 579 then package the system into a standard release layout as 580 described by release(7). This requires that RELEASEDIR be 581 set (see above). 582 583 iso-image Create a NetBSD installation CD-ROM image in the 584 RELEASEDIR/iso directory. The CD-ROM file system will have 585 a layout as described in release(7). 586 587 For most machine types, the CD-ROM will be bootable, and 588 will automatically run the sysinst(8) menu-based installa- 589 tion program, which can be used to install or upgrade a 590 NetBSD system. Bootable CD-ROMs also contain tools that 591 may be useful in repairing a damaged NetBSD installation. 592 593 Before ``make iso-image'' is attempted, RELEASEDIR must be 594 populated by ``make release'' or equivalent. 595 596 Note that other, smaller, CD-ROM images may be created in 597 the RELEASEDIR/RELEASEMACHINEDIR/installation/cdrom direc- 598 tory by ``make release''. These smaller images usually 599 contain the same tools as the larger images in 600 RELEASEDIR/iso, but do not contain additional content such 601 as the distribution sets. 602 603 Note that the mac68k port still uses an older method of 604 creating CD-ROM images. This requires the mkisofs(1) util- 605 ity, which is not part of NetBSD, but which can be 606 installed from pkgsrc/sysutils/cdrtools. 607 608 iso-image-source 609 Create a NetBSD installation CD-ROM image in the 610 RELEASEDIR/iso directory. The CD-ROM file system will have 611 a layout as described in release(7). It will have top 612 level directories for the machine type and source. 613 614 For most machine types, the CD-ROM will be bootable, and 615 will automatically run the sysinst(8) menu-based installa- 616 tion program, which can be used to install or upgrade a 617 NetBSD system. Bootable CD-ROMs also contain tools that 618 may be useful in repairing a damaged NetBSD installation. 619 620 Before ``make iso-image-source'' is attempted, RELEASEDIR 621 must be populated by ``make sourcesets release'' or equiva- 622 lent. 623 624 Note that other, smaller, CD-ROM images may be created in 625 the RELEASEDIR/RELEASEMACHINEDIR/installation/cdrom direc- 626 tory by ``make release''. These smaller images usually 627 contain the same tools as the larger images in 628 RELEASEDIR/iso, but do not contain additional content such 629 as the distribution sets. 630 631 Note that the mac68k port still uses an older method of 632 creating CD-ROM images. This requires the mkisofs(1) util- 633 ity, which is not part of NetBSD, but which can be 634 installed from pkgsrc/sysutils/cdrtools. 635 636 install-image 637 Create a bootable NetBSD installation disk image in the 638 RELEASEDIR/RELEASEMACHINEDIR/installation/installimage 639 directory. The installation disk image is suitable for 640 copying to bootable USB flash memory sticks, etc., for 641 machines which are able to boot from such devices. The 642 file system in the bootable disk image will have a layout 643 as described in release(7). 644 645 The installation image is bootable, and will automatically 646 run the sysinst(8) menu-based installation program, which 647 can be used to install or upgrade a NetBSD system. The 648 image also contains tools that may be useful in repairing a 649 damaged NetBSD installation. 650 651 Before ``make install-image'' is attempted, RELEASEDIR must 652 be populated by ``make release'' or equivalent. The build 653 must have been performed with MKUNPRIVED=yes because ``make 654 install-image'' relies on information in DESTDIR/METALOG. 655 656 live-image Create NetBSD live images in the 657 RELEASEDIR/RELEASEMACHINEDIR/installation/liveimage direc- 658 tory. The live image contains all necessary files to boot 659 NetBSD up to multi-user mode, including all files which 660 should be extracted during installation, NetBSD disklabel, 661 bootloaders, etc. 662 663 The live image is suitable for use as a disk image in vir- 664 tual machine environments such as QEMU, and also useful to 665 boot NetBSD from a USB flash memory stick on a real 666 machine, without the need for installation. 667 668 Before ``make live-image'' is attempted, RELEASEDIR must be 669 populated by ``make release'' or equivalent. The build 670 must have been performed with MKUNPRIVED=yes because ``make 671 install-image'' relies on information in DESTDIR/METALOG. 672 673 regression-tests 674 Can only be run after building the regression tests in the 675 directory ``regress''. Runs those compiled regression 676 tests on the local host. Note that most tests are now man- 677 aged instead using atf(7); this target should probably run 678 those as well but currently does not. 679 680 The "build.sh" script 681 This script file is a shell script designed to build the entire NetBSD 682 system on any host with a suitable modern shell and some common utili- 683 ties. The required shell features are described under the HOST_SH vari- 684 able. 685 686 If a host system's default shell does support the required features, then 687 we suggest that you explicitly specify a suitable shell using a command 688 like 689 690 /path/to/suitable/shell build.sh [options] 691 692 The above command will usually enable build.sh to automatically set 693 HOST_SH=/path/to/suitable/shell, but if that fails, then the following 694 set of commands may be used instead: 695 696 HOST_SH=/path/to/suitable/shell 697 export HOST_SH 698 ${HOST_SH} build.sh [options] 699 700 If build.sh detects that it is being executed under an unsuitable shell, 701 it attempts to exec a suitable shell instead, or prints an error message. 702 If HOST_SH is not set explicitly, then build.sh sets a default using 703 heuristics dependent on the host platform, or from the shell under which 704 build.sh is executed (if that can be determined), or using the first copy 705 of sh found in PATH. 706 707 All cross-compile builds, and most native builds, of the entire system 708 should make use of build.sh rather than just running ``make''. This way, 709 the make(1) program will be bootstrapped properly, in case the host sys- 710 tem has an older or incompatible ``make'' program. 711 712 When compiling the entire system via build.sh, many make(1) variables are 713 set for you in order to help encapsulate the build process. In the list 714 of options below, variables that are automatically set by build.sh are 715 noted where applicable. 716 717 The following operations are supported by build.sh: 718 719 build Build the system as per ``make build''. Before the main 720 part of the build commences, this command runs the obj 721 operation (unless the -o option is given), ``make 722 cleandir'' (unless the -u option is given), and the tools 723 operation. 724 725 distribution Build a full distribution as per ``make distribution''. 726 This command first runs the build operation. 727 728 release Build a full release as per ``make release''. This command 729 first runs the distribution operation. 730 731 makewrapper Create the nbmake-MACHINE wrapper. This operation is auto- 732 matically performed for any of the other operations. 733 734 cleandir Perform ``make cleandir''. 735 736 obj Perform ``make obj''. 737 738 tools Build and install the host tools from src/tools. This com- 739 mand will first run ``make obj'' and ``make cleandir'' in 740 the tools subdirectory unless the -o or -u options (respec- 741 tively) are given. 742 743 install=idir Install the contents of DESTDIR to idir, using ``make 744 installworld''. Note that files that are part of the 745 ``etc'' or ``xetc'' sets will not be installed, unless 746 overridden by the INSTALLSETS environment variable. 747 748 kernel=kconf Build a new kernel. The kconf argument is the name of a 749 configuration file suitable for use by config(1). If kconf 750 does not contain any `/' characters, the configuration file 751 is expected to be found in the KERNCONFDIR directory, which 752 is typically sys/arch/MACHINE/conf. The new kernel will be 753 built in a subdirectory of KERNOBJDIR, which is typically 754 sys/arch/MACHINE/compile or an associated object directory. 755 756 This command does not imply the tools command; run the 757 tools command first unless it is certain that the tools 758 already exist and are up to date. 759 760 This command will run ``make cleandir'' on the kernel in 761 question first unless the -u option is given. 762 763 modules This command will build kernel modules and install them 764 into DESTDIR. 765 766 releasekernel=kconf 767 Install a gzip(1)ed copy of the kernel previously built by 768 kernel=kconf into 769 RELEASEDIR/RELEASEMACHINEDIR/binary/kernel, usually as 770 netbsd-kconf.gz, although the ``netbsd'' prefix is deter- 771 mined from the ``config'' directives in kconf. 772 773 sets Perform ``make sets''. 774 775 sourcesets Perform ``make sourcesets''. 776 777 syspkgs Perform ``make syspkgs''. 778 779 iso-image Perform ``make iso-image''. 780 781 iso-image-source 782 Perform ``make iso-image-source''. 783 784 install-image 785 Perform ``make install-image''. 786 787 live-image Perform ``make live-image''. 788 789 The following command line options alter the behaviour of the build.sh 790 operations described above: 791 792 -a arch Set the value of MACHINE_ARCH to arch. 793 794 -B buildid 795 Set the value of BUILDID to buildid. This will also append the 796 build identifier to the name of the ``make'' wrapper script so 797 that the resulting name is of the form 798 ``nbmake-MACHINE-BUILDID''. 799 800 -C cdextras 801 Append cdextras to the CDEXTRA variable, which is a space-sepa- 802 rated list of files or directories that will be added to the 803 CD-ROM image that may be create by the ``iso-image'' or 804 ``iso-image-source'' operations. Files will be added to the 805 root of the CD-ROM image, whereas directories will be copied 806 recursively. If relative paths are specified, they will be 807 converted to absolute paths before being used. Multiple paths 808 may be specified via multiple -C options, or via a single 809 option whose argument contains multiple space-separated paths. 810 811 -D dest Set the value of DESTDIR to dest. If a relative path is speci- 812 fied, it will be converted to an absolute path before being 813 used. 814 815 -E Set `expert' mode. This overrides various sanity checks, and 816 allows: DESTDIR does not have to be set to a non-root path for 817 builds, and MKUNPRIVED=yes does not have to be set when build- 818 ing as a non-root user. 819 820 Note: It is highly recommended that you know what you are doing 821 when you use this option. 822 823 -h Print a help message. 824 825 -j njob Run up to njob make(1) subjobs in parallel; passed through to 826 make(1). If you see failures for reasons other than running 827 out of memory while using build.sh with -j, please save com- 828 plete build logs so the failures can be analyzed. 829 830 To achieve the fastest builds, -j values between (1 + the num- 831 ber of CPUs) and (2 * the number of CPUs) are recommended. Use 832 lower values on machines with limited memory or I/O bandwidth. 833 834 -M obj Set MAKEOBJDIRPREFIX to obj. Unsets MAKEOBJDIR. See ``-O 835 -obj'' for more information. 836 837 For instance, if the source directory is /usr/src, a setting of 838 ``-M /usr/obj'' will place build-time files under 839 /usr/obj/usr/src/bin, /usr/obj/usr/src/lib, 840 /usr/obj/usr/src/usr.bin, and so forth. 841 842 If a relative path is specified, it will be converted to an 843 absolute path before being used. build.sh imposes the restric- 844 tion that the argument to the -M option must not begin with a 845 ``$'' (dollar sign) character; otherwise it would be too diffi- 846 cult to determine whether the value is an absolute or a rela- 847 tive path. If the directory does not already exist, build.sh 848 will create it. 849 850 -m mach Set the value of MACHINE to mach, except in some special cases 851 listed below. This will also override any value of 852 MACHINE_ARCH in the process environment with a value deduced 853 from mach, unless -a is specified. All cross builds require 854 -m, but if unset on a NetBSD host, the host's value of MACHINE 855 will be detected and used automatically. 856 857 Some machines support multiple values for MACHINE_ARCH. The 858 following special cases for the mach argument are defined to 859 set the listed values of MACHINE and MACHINE_ARCH: 860 861 mach MACHINE MACHINE_ARCH 862 evbarm evbarm (not set) 863 evbarm-eb evbarm armeb 864 evbarm-el evbarm arm 865 evbmips evbmips (not set) 866 evbmips-eb evbmips mipseb 867 evbmips-el evbmips mipsel 868 evbsh3 evbsh3 (not set) 869 evbsh3-eb evbsh3 sh3eb 870 evbsh3-el evbsh3 sh3el 871 sbmips sbmips (not set) 872 sbmips-eb sbmips mipseb 873 sbmips-el sbmips mipsel 874 875 -N noiselevel 876 Set the ``noisyness'' level of the build, by setting 877 MAKEVERBOSE to noiselevel. 878 879 -n Show the commands that would be executed by build.sh, but do 880 not make any changes. This is similar in concept to ``make 881 -n''. 882 883 -O obj Create an appropriate transform macro for MAKEOBJDIR that will 884 place the built object files under obj. Unsets 885 MAKEOBJDIRPREFIX. 886 887 For instance, a setting of ``-O /usr/obj'' will place build- 888 time files under /usr/obj/bin, /usr/obj/lib, /usr/obj/usr.bin, 889 and so forth. 890 891 If a relative path is specified, it will be converted to an 892 absolute path before being used. build.sh imposes the restric- 893 tion that the argument to the -O option must not contain a 894 ``$'' (dollar sign) character. If the directory does not 895 already exist, build.sh will create it. 896 897 In normal use, exactly one of the -M or -O options should be 898 specified. If neither -M nor -O is specified, then a default 899 object directory will be chosen according to rules in 900 <bsd.obj.mk>. Relying on this default is not recommended 901 because it is determined by complex rules that are influenced 902 by the values of several variables and by the location of the 903 source directory. 904 905 -o Set the value of MKOBJDIRS to ``no''. Otherwise, it will be 906 automatically set to ``yes''. This default is opposite to the 907 behaviour when not using build.sh. 908 909 -R rel Set the value of RELEASEDIR to rel. If a relative path is 910 specified, it will be converted to an absolute path before 911 being used. 912 913 -r Remove the contents of DESTDIR and TOOLDIR before building 914 (provides a clean starting point). This will skip deleting 915 DESTDIR if building on a native system to the root directory. 916 917 -S seed Change the value of BUILDSEED to seed. This should rarely be 918 necessary. 919 920 -T tools Set the value of TOOLDIR to tools. If a relative path is spec- 921 ified, it will be converted to an absolute path before being 922 used. If set, the bootstrap ``make'' will only be rebuilt if 923 the source files for make(1) have changed. 924 925 -U Set MKUNPRIVED=yes. 926 927 -u Set MKUPDATE=yes. 928 929 -V var=[value] 930 Set the environment variable var to an optional value. This is 931 propagated to the nbmake wrapper. 932 933 -w wrapper 934 Create the nbmake wrapper script (see below) in a custom loca- 935 tion, specified by wrapper. This allows, for instance, to 936 place the wrapper in PATH automatically. Note that wrapper is 937 the full name of the file, not just a directory name. If a 938 relative path is specified, it will be converted to an absolute 939 path before being used. 940 941 -X x11src 942 Set the value of X11SRCDIR to x11src. If a relative path is 943 specified, it will be converted to an absolute path before 944 being used. 945 946 -x Set MKX11=yes. 947 948 -Z var Unset ("zap") the environment variable var. This is propagated 949 to the nbmake wrapper. 950 951 The "nbmake-MACHINE" wrapper script 952 If using the build.sh script to build NetBSD, a nbmake-MACHINE script 953 will be created in TOOLDIR/bin upon the first build to assist in building 954 subtrees on a cross-compile host. 955 956 nbmake-MACHINE can be invoked in lieu of make(1), and will instead call 957 the up-to-date version of ``nbmake'' installed into TOOLDIR/bin with sev- 958 eral key variables pre-set, including MACHINE, MACHINE_ARCH, and TOOLDIR. 959 nbmake-MACHINE will also set variables specified with -V, and unset vari- 960 ables specified with -Z. 961 962 This script can be symlinked into a directory listed in PATH, or called 963 with an absolute path. 964 965EXAMPLES 966 1. % ./build.sh [options] tools kernel=GENERIC 967 968 Build a new toolchain, and use the new toolchain to configure and 969 build a new GENERIC kernel. 970 971 2. % ./build.sh [options] -U distribution 972 973 Using unprivileged mode, build a complete distribution to a DESTDIR 974 directory that build.sh selects (and will display). 975 976 3. # ./build.sh [options] -U install=/ 977 978 As root, install to / the distribution that was built by example 2. 979 Even though this is run as root, -U is required so that the permis- 980 sions stored in DESTDIR/METALOG are correctly applied to the files 981 as they're copied to /. 982 983 4. % ./build.sh [options] -U -u release 984 985 Using unprivileged mode, build a complete release to DESTDIR and 986 RELEASEDIR directories that build.sh selects (and will display). 987 MKUPDATE=yes (-u) is set to prevent the ``make cleandir'', so that 988 if this is run after example 2, it doesn't need to redo that portion 989 of the release build. 990 991OBSOLETE VARIABLES 992 NBUILDJOBS Use the make(1) option -j instead. 993 994 USE_NEW_TOOLCHAIN 995 The new toolchain is now the default. To disable, use 996 TOOLCHAIN_MISSING=yes. 997 998SEE ALSO 999 make(1), hier(7), release(7), etcupdate(8), postinstall(8), sysinst(8), 1000 pkgsrc/sysutils/cdrtools 1001 1002HISTORY 1003 The build.sh based build scheme was introduced for NetBSD 1.6 as 1004 USE_NEW_TOOLCHAIN, and re-worked to TOOLCHAIN_MISSING after that. 1005 1006NetBSD May 25, 2012 NetBSD 1007