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