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