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