share/man/man7/build.7

   1 .\" Copyright (c) 2000
   2 .\"     Mike W. Meyer
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .\" $FreeBSD$
  26 .\"
  27 .Dd January 4, 2015
  28 .Dt BUILD 7
  29 .Os
  30 .Sh NAME
  31 .Nm build
  32 .Nd information on how to build the system
  33 .Sh DESCRIPTION
  34 The sources for the
  35 .Fx
  36 system and its applications are contained in three different directories,
  37 normally
  38 .Pa /usr/src ,
  39 .Pa /usr/doc ,
  40 and
  41 .Pa /usr/ports .
  42 These directories may be initially empty or non-existent until updated with
  43 .Xr svn 1
  44 or
  45 .Xr portsnap 8 .
  46 Directory
  47 .Pa /usr/src
  48 contains the
  49 .Dq "base system"
  50 sources, which is loosely defined as the things required to rebuild
  51 the system to a useful state.
  52 Directory
  53 .Pa /usr/doc
  54 contains the source for the system documentation, excluding the manual
  55 pages.
  56 Directory
  57 .Pa /usr/ports
  58 contains a tree that provides a consistent interface for building and
  59 installing third party applications.
  60 For more information about the ports build process, see
  61 .Xr ports 7 .
  62 .Pp
  63 The
  64 .Xr make 1
  65 command is used in each of these directories to build and install the
  66 things in that directory.
  67 Issuing the
  68 .Xr make 1
  69 command in any directory or
  70 subdirectory of those directories has the same effect as issuing the
  71 same command in all subdirectories of that directory.
  72 With no target specified, the things in that directory are just built.
  73 .Pp
  74 A source tree is allowed to be read-only.
  75 As described in
  76 .Xr make 1 ,
  77 objects are usually built in a separate object directory hierarchy
  78 specified by the environment variable
  79 .Va MAKEOBJDIRPREFIX ,
  80 or under
  81 .Pa /usr/obj
  82 if variable
  83 .Va MAKEOBJDIRPREFIX
  84 is not set.
  85 For a given source directory, its canonical object directory
  86 would be
  87 .Pa ${MAKEOBJDIRPREFIX}${.CURDIR}
  88 if
  89 .Xr make 1
  90 variable
  91 .Va MAKEOBJDIRPREFIX
  92 is set, or
  93 .Pa /usr/obj${.CURDIR}
  94 if this variable is not set.
  95 Cross-builds set the object directory as described in the
  96 documentation for the
  97 .Cm buildworld
  98 target below.
  99 .Pp
 100 The build may be controlled by defining
 101 .Xr make 1
 102 variables described in the
 103 .Sx ENVIRONMENT
 104 section below, and by the variables documented in
 105 .Xr make.conf 5 .
 106 .Pp
 107 The following list provides the names and actions for the targets
 108 supported by the build system:
 109 .Bl -tag -width ".Cm cleandepend"
 110 .It Cm clean
 111 Remove any files created during the build process.
 112 .It Cm cleandepend
 113 Remove the file
 114 .Pa ${.OBJDIR}/${DEPENDFILE}
 115 generated by a prior
 116 .Dq Li "make depend"
 117 step.
 118 .It Cm cleandir
 119 Remove the canonical object directory if it exists, or perform
 120 actions equivalent to
 121 .Dq Li "make clean cleandepend"
 122 if it does not.
 123 This target will also remove an
 124 .Pa obj
 125 link in
 126 .Pa ${.CURDIR}
 127 if that exists.
 128 .Pp
 129 It is advisable to run
 130 .Dq Li "make cleandir"
 131 twice: the first invocation will remove the canonical object directory
 132 and the second one will clean up
 133 .Pa ${.CURDIR} .
 134 .It Cm depend
 135 Generate a list of build dependencies in file
 136 .Pa ${.OBJDIR}/${DEPENDFILE} .
 137 .It Cm install
 138 Install the results of the build to the appropriate location in the
 139 installation directory hierarchy specified in variable
 140 .Va DESTDIR .
 141 .It Cm obj
 142 Create the canonical object directory associated with the current
 143 directory.
 144 .It Cm objlink
 145 Create a symbolic link to the canonical object directory in
 146 .Pa ${.CURDIR} .
 147 .It Cm tags
 148 Generate a tags file using the program specified in the
 149 .Xr make 1
 150 variable
 151 .Va CTAGS .
 152 The build system supports
 153 .Xr ctags 1
 154 and
 155 .Nm "GNU Global" .
 156 .El
 157 .Pp
 158 The other supported targets under directory
 159 .Pa /usr/src
 160 are:
 161 .Bl -tag -width ".Cm distributeworld"
 162 .It Cm buildenv
 163 Spawn an interactive shell with environment variables set up for
 164 cross-building the system.
 165 The target architecture needs to be specified with
 166 .Xr make 1
 167 variables
 168 .Va TARGET_ARCH
 169 and
 170 .Va TARGET .
 171 .Pp
 172 This target is only useful after a complete cross-toolchain including
 173 the compiler, linker, assembler, headers and libraries has been
 174 built; see the
 175 .Cm toolchain
 176 target below.
 177 .It Cm buildworld
 178 Build everything but the kernel, configure files in
 179 .Pa etc ,
 180 and
 181 .Pa release .
 182 The actual build location prefix used is
 183 .Pa ${MAKEOBJDIRPREFIX}${.CURDIR}
 184 for native builds, and
 185 .Pa ${MAKEOBJDIRPREFIX}/${TARGET}${.CURDIR}
 186 for cross builds and native builds with variable
 187 .Va CROSS_BUILD_TESTING
 188 set.
 189 .It Cm cleanworld
 190 Attempt to clean up targets built by a preceding
 191 .Cm buildworld
 192 step.
 193 .It Cm distributeworld
 194 Distribute everything compiled by a preceding
 195 .Cm buildworld
 196 step.
 197 Files are placed in the directory hierarchy specified by
 198 .Xr make 1
 199 variable
 200 .Va DISTDIR .
 201 This target is used while building a release; see
 202 .Xr release 7 .
 203 .It Cm packageworld
 204 Archive the results of
 205 .Cm distributeworld ,
 206 placing the results in
 207 .Va DISTDIR .
 208 This target is used while building a release; see
 209 .Xr release 7 .
 210 .It Cm installworld
 211 Install everything built by a preceding
 212 .Cm buildworld
 213 step into the directory hierarchy pointed to by
 214 .Xr make 1
 215 variable
 216 .Va DESTDIR .
 217 .Pp
 218 If installing onto an NFS file system and running
 219 .Xr make 1
 220 with the
 221 .Fl j
 222 option, make sure that
 223 .Xr rpc.lockd 8
 224 is running on both client and server.
 225 See
 226 .Xr rc.conf 5
 227 on how to make it start at boot time.
 228 .It Cm toolchain
 229 Create the build toolchain needed to build the rest of the system.
 230 For cross-architecture builds, this step creates a cross-toolchain.
 231 .It Cm universe
 232 For each architecture,
 233 execute a
 234 .Cm buildworld
 235 followed by a
 236 .Cm buildkernel
 237 for all kernels for that architecture,
 238 including
 239 .Pa LINT .
 240 This command takes a long time.
 241 .It Cm update
 242 Get updated sources as configured in
 243 .Xr make.conf 5 .
 244 .It Cm targets
 245 Print a list of supported
 246 .Va TARGET
 247 /
 248 .Va TARGET_ARCH
 249 pairs for world and kernel targets.
 250 .It Cm tinderbox
 251 Execute the same targets as
 252 .Cm universe .
 253 In addition print a summary of all failed targets at the end and
 254 exit with an error if there were any.
 255 .It Cm toolchains
 256 Create a build toolchain for each architecture supported by the build system.
 257 .El
 258 .Pp
 259 Kernel specific build targets in
 260 .Pa /usr/src
 261 are:
 262 .Bl -tag -width ".Cm distributekernel"
 263 .It Cm buildkernel
 264 Rebuild the kernel and the kernel modules.
 265 .It Cm installkernel
 266 Install the kernel and the kernel modules to directory
 267 .Pa ${DESTDIR}/boot/kernel ,
 268 renaming any pre-existing directory with this name to
 269 .Pa kernel.old
 270 if it contained the currently running kernel.
 271 The target directory under
 272 .Pa ${DESTDIR}
 273 may be modified using the
 274 .Va INSTKERNNAME
 275 and
 276 .Va KODIR
 277 .Xr make 1
 278 variables.
 279 .It Cm distributekernel
 280 Install the kernel to the directory
 281 .Pa ${DISTDIR}/kernel/boot/kernel .
 282 This target is used while building a release; see
 283 .Xr release 7 .
 284 .It Cm packagekernel
 285 Archive the results of
 286 .Cm distributekernel ,
 287 placing the results in
 288 .Va DISTDIR .
 289 This target is used while building a release; see
 290 .Xr release 7 .
 291 .It Cm kernel
 292 Equivalent to
 293 .Cm buildkernel
 294 followed by
 295 .Cm installkernel
 296 .It Cm kernel-toolchain
 297 Rebuild the tools needed for kernel compilation.
 298 Use this if you did not do a
 299 .Cm buildworld
 300 first.
 301 .It Cm reinstallkernel
 302 Reinstall the kernel and the kernel modules, overwriting the contents
 303 of the target directory.
 304 As with the
 305 .Cm installkernel
 306 target, the target directory can be specified using the
 307 .Xr make 1
 308 variable
 309 .Va INSTKERNNAME .
 310 .El
 311 .Pp
 312 Convenience targets for cleaning up the install destination directory
 313 denoted by variable
 314 .Va DESTDIR
 315 include:
 316 .Bl -tag -width ".Cm delete-old-libs"
 317 .It Cm check-old
 318 Print a list of old files and directories in the system.
 319 .It Cm delete-old
 320 Delete obsolete base system files and directories interactively.
 321 When
 322 .Li -DBATCH_DELETE_OLD_FILES
 323 is specified at the command line, the delete operation will be
 324 non-interactive.
 325 The variables
 326 .Va DESTDIR ,
 327 .Va TARGET_ARCH
 328 and
 329 .Va TARGET
 330 should be set as with
 331 .Dq Li "make installworld" .
 332 .It Cm delete-old-libs
 333 Delete obsolete base system libraries interactively.
 334 This target should only be used if no 3rd party software uses these
 335 libraries.
 336 When
 337 .Li -DBATCH_DELETE_OLD_FILES
 338 is specified at the command line, the delete operation will be
 339 non-interactive.
 340 The variables
 341 .Va DESTDIR ,
 342 .Va TARGET_ARCH
 343 and
 344 .Va TARGET
 345 should be set as with
 346 .Dq Li "make installworld" .
 347 .El
 348 .Sh ENVIRONMENT
 349 Variables that influence all builds include:
 350 .Bl -tag -width ".Va MAKEOBJDIRPREFIX"
 351 .It Va DEBUG_FLAGS
 352 Defines a set of debugging flags that will be used to build all userland
 353 binaries under
 354 .Pa /usr/src .
 355 When
 356 .Va DEBUG_FLAGS
 357 is defined, the
 358 .Cm install
 359 and
 360 .Cm installworld
 361 targets install binaries from the current
 362 .Va MAKEOBJDIRPREFIX
 363 without stripping,
 364 so that debugging information is retained in the installed binaries.
 365 .It Va DESTDIR
 366 The directory hierarchy prefix where built objects will be installed.
 367 If not set,
 368 .Va DESTDIR
 369 defaults to the empty string.
 370 .It Va MAKEOBJDIRPREFIX
 371 Defines the prefix for directory names in the tree of built objects.
 372 Defaults to
 373 .Pa /usr/obj
 374 if not defined.
 375 This variable should only be set in the environment and not via
 376 .Pa /etc/make.conf
 377 or the command line.
 378 .It Va NO_WERROR
 379 If defined, compiler warnings will not cause the build to halt,
 380 even if the makefile says otherwise.
 381 .It Va WITH_CTF
 382 If defined, the build process will run the DTrace CTF conversion
 383 tools on built objects.
 384 .El
 385 .Pp
 386 Additionally, builds in
 387 .Pa /usr/src
 388 are influenced by the following
 389 .Xr make 1
 390 variables:
 391 .Bl -tag -width ".Va SUBDIR_OVERRIDE"
 392 .It Va KERNCONF
 393 Overrides which kernel to build and install for the various kernel
 394 make targets.
 395 It defaults to
 396 .Cm GENERIC .
 397 .It Va KERNFAST
 398 If set, the build target
 399 .Cm buildkernel
 400 defaults to setting
 401 .Va NO_KERNELCLEAN ,
 402 .Va NO_KERNELCONFIG ,
 403 .Va NO_KERNELDEPEND
 404 and
 405 .Va NO_KERNELOBJ .
 406 When set to a value other than
 407 .Cm 1
 408 then
 409 .Va KERNCONF
 410 is set to the value of
 411 .Va KERNFAST .
 412 .It Va LOCAL_DIRS
 413 If set, this variable supplies a list of additional directories relative to
 414 the root of the source tree to build as part of the
 415 .Cm everything
 416 target.
 417 .It Va LOCAL_ITOOLS
 418 If set, this variable supplies a list of additional tools that are used by the
 419 .Cm installworld
 420 and
 421 .Cm distributeworld
 422 targets.
 423 .It Va LOCAL_LIB_DIRS
 424 If set, this variable supplies a list of additional directories relative to
 425 the root of the source tree to build as part of the
 426 .Cm libraries
 427 target.
 428 .It Va LOCAL_MTREE
 429 If set, this variable supplies a list of additional mtrees relative to the
 430 root of the source tree to use as part of the
 431 .Cm hierarchy
 432 target.
 433 .It Va LOCAL_TOOL_DIRS
 434 If set, this variable supplies a list of additional directories relative to
 435 the root of the source tree to build as part of the
 436 .Cm build-tools
 437 target.
 438 .It Va PORTS_MODULES
 439 A list of ports with kernel modules that should be built and installed
 440 as part of the
 441 .Cm buildkernel
 442 and
 443 .Cm installkernel
 444 process.
 445 .Bd -literal -offset indent
 446 make PORTS_MODULES=emulators/kqemu-kmod kernel
 447 .Ed
 448 .It Va STRIPBIN
 449 Command to use at install time when stripping binaries.
 450 Be sure to add any additional tools required to run
 451 .Va STRIPBIN
 452 to the
 453 .Va LOCAL_ITOOLS
 454 .Xr make 1
 455 variable before running the
 456 .Cm distributeworld
 457 or
 458 .Cm installworld
 459 targets.
 460 See
 461 .Xr install 1
 462 for more details.
 463 .It Va SUBDIR_OVERRIDE
 464 Override the default list of sub-directories and only build the
 465 sub-directory named in this variable.
 466 This variable is useful when debugging failed builds.
 467 .Bd -literal -offset indent
 468 make some-target SUBDIR_OVERRIDE=foo/bar
 469 .Ed
 470 .It Va TARGET
 471 The target hardware platform.
 472 This is analogous to the
 473 .Dq Nm uname Fl m
 474 output.
 475 This is necessary to cross-build some target architectures.
 476 For example, cross-building for PC98 machines requires
 477 .Va TARGET_ARCH Ns = Ns Li i386
 478 and
 479 .Va TARGET Ns = Ns Li pc98 .
 480 If not set,
 481 .Va TARGET
 482 defaults to the current hardware platform.
 483 .It Va TARGET_ARCH
 484 The target machine processor architecture.
 485 This is analogous to the
 486 .Dq Nm uname Fl p
 487 output.
 488 Set this to cross-build for a different architecture.
 489 If not set,
 490 .Va TARGET_ARCH
 491 defaults to the current machine architecture, unless
 492 .Va TARGET
 493 is also set, in which case it defaults to the appropriate
 494 value for that platform.
 495 Typically, one only needs to set
 496 .Va TARGET .
 497 .El
 498 .Pp
 499 Builds under directory
 500 .Pa /usr/src
 501 are also influenced by defining one or more of the following symbols,
 502 using the
 503 .Fl D
 504 option of
 505 .Xr make 1 :
 506 .Bl -tag -width ".Va -DNO_KERNELDEPEND"
 507 .It Va NO_CLEANDIR
 508 If set, the build targets that clean parts of the object tree use the
 509 equivalent of
 510 .Dq make clean
 511 instead of
 512 .Dq make cleandir .
 513 .It Va NO_CLEAN
 514 If set, no object tree files are cleaned at all.
 515 Setting
 516 .Va NO_CLEAN
 517 implies
 518 .Va NO_KERNELCLEAN ,
 519 so when
 520 .Va NO_CLEAN
 521 is set no kernel objects are cleaned either.
 522 .It Va NO_CTF
 523 If set, the build process does not run the DTrace CTF conversion tools
 524 on built objects.
 525 .It Va NO_SHARE
 526 If set, the build does not descend into the
 527 .Pa /usr/src/share
 528 subdirectory (i.e., manpages, locale data files, timezone data files and
 529 other
 530 .Pa /usr/src/share
 531 files will not be rebuild from their sources).
 532 .It Va NO_KERNELCLEAN
 533 If set, the build process does not run
 534 .Dq make clean
 535 as part of the
 536 .Cm buildkernel
 537 target.
 538 .It Va NO_KERNELCONFIG
 539 If set, the build process does not run
 540 .Xr config 8
 541 as part of the
 542 .Cm buildkernel
 543 target.
 544 .It Va NO_KERNELDEPEND
 545 If set, the build process does not run
 546 .Dq make depend
 547 as part of the
 548 .Cm buildkernel
 549 target.
 550 .It Va NO_KERNELOBJ
 551 If set, the build process does not run
 552 .Dq make obj
 553 as part of the
 554 .Cm buildkernel
 555 target.
 556 .It Va NO_DOCUPDATE
 557 If set, the update process does not update the source of the
 558 .Fx
 559 documentation as part of the
 560 .Dq make update
 561 target.
 562 .It Va NO_PORTSUPDATE
 563 If set, the update process does not update the Ports tree as part of the
 564 .Dq make update
 565 target.
 566 .It Va NO_WWWUPDATE
 567 If set, the update process does not update the www tree as part of the
 568 .Dq make update
 569 target.
 570 .El
 571 .Pp
 572 Builds under directory
 573 .Pa /usr/doc
 574 are influenced by the following
 575 .Xr make 1
 576 variables:
 577 .Bl -tag -width ".Va DOC_LANG"
 578 .It Va DOC_LANG
 579 If set, restricts the documentation build to the language subdirectories
 580 specified as its content.
 581 The default action is to build documentation for all languages.
 582 .El
 583 .Pp
 584 Builds using the
 585 .Cm universe
 586 target are influenced by the following
 587 .Xr make 1
 588 variables:
 589 .Bl -tag -width ".Va MAKE_JUST_KERNELS"
 590 .It Va JFLAG
 591 Pass the value of this variable to each
 592 .Xr make 1
 593 invocation used to build worlds and kernels.
 594 This can be used to enable multiple jobs within a single architecture's build
 595 while still building each architecture serially.
 596 .It Va MAKE_JUST_KERNELS
 597 Only build kernels for each supported architecture.
 598 .It Va MAKE_JUST_WORLDS
 599 Only build worlds for each supported architecture.
 600 .It Va UNIVERSE_TARGET
 601 Execute the specified
 602 .Xr make 1
 603 target for each supported architecture instead of the default action of
 604 building a world and one or more kernels.
 605 .El
 606 .Sh FILES
 607 .Bl -tag -width ".Pa /usr/share/examples/etc/make.conf" -compact
 608 .It Pa /usr/doc/Makefile
 609 .It Pa /usr/doc/share/mk/doc.project.mk
 610 .It Pa /usr/ports/Mk/bsd.port.mk
 611 .It Pa /usr/ports/Mk/bsd.sites.mk
 612 .It Pa /usr/share/examples/etc/make.conf
 613 .It Pa /usr/src/Makefile
 614 .It Pa /usr/src/Makefile.inc1
 615 .El
 616 .Sh EXAMPLES
 617 For an
 618 .Dq approved
 619 method of updating your system from the latest sources, please see the
 620 .Sx COMMON ITEMS
 621 section in
 622 .Pa src/UPDATING .
 623 .Pp
 624 The following sequence of commands can be used to cross-build the
 625 system for the sparc64 architecture on an i386 host:
 626 .Bd -literal -offset indent
 627 cd /usr/src
 628 make TARGET=sparc64 buildworld
 629 make TARGET=sparc64 DESTDIR=/clients/sparc64 installworld
 630 .Ed
 631 .Sh SEE ALSO
 632 .Xr cc 1 ,
 633 .Xr install 1 ,
 634 .Xr make 1 ,
 635 .Xr svn 1 ,
 636 .Xr make.conf 5 ,
 637 .Xr src.conf 5 ,
 638 .Xr ports 7 ,
 639 .Xr release 7 ,
 640 .Xr config 8 ,
 641 .Xr mergemaster 8 ,
 642 .Xr portsnap 8 ,
 643 .Xr reboot 8 ,
 644 .Xr shutdown 8
 645 .Sh AUTHORS
 646 .An Mike W. Meyer Aq mwm@mired.org .