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 June 27, 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 or
  45 .Xr svn 1 .
  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 installworld
 204 Install everything built by a preceding
 205 .Cm buildworld
 206 step into the directory hierarchy pointed to by
 207 .Xr make 1
 208 variable
 209 .Va DESTDIR .
 210 .Pp
 211 If installing onto an NFS file system and running
 212 .Xr make 1
 213 with the
 214 .Fl j
 215 option, make sure that
 216 .Xr rpc.lockd 8
 217 is running on both client and server.
 218 See
 219 .Xr rc.conf 5
 220 on how to make it start at boot time.
 221 .It Cm toolchain
 222 Create the build toolchain needed to build the rest of the system.
 223 For cross-architecture builds, this step creates a cross-toolchain.
 224 .It Cm universe
 225 For each architecture,
 226 execute a
 227 .Cm buildworld
 228 followed by a
 229 .Cm buildkernel
 230 for all kernels for that architecture,
 231 including
 232 .Pa LINT .
 233 This command takes a long time.
 234 .It Cm update
 235 Get updated sources as configured in
 236 .Xr make.conf 5 .
 237 .It Cm tinderbox
 238 Execute the same targets as
 239 .Cm universe .
 240 In addition print a summary of all failed targets at the end and
 241 exit with an error if there were any.
 242 .It Cm toolchains
 243 Create a build toolchain for each architecture supported by the build system.
 244 .El
 245 .Pp
 246 Kernel specific build targets in
 247 .Pa /usr/src
 248 are:
 249 .Bl -tag -width ".Cm reinstallkernel"
 250 .It Cm buildkernel
 251 Rebuild the kernel and the kernel modules.
 252 .It Cm installkernel
 253 Install the kernel and the kernel modules to directory
 254 .Pa ${DESTDIR}/boot/kernel ,
 255 renaming any pre-existing directory with this name to
 256 .Pa kernel.old
 257 if it contained the currently running kernel.
 258 The target directory under
 259 .Pa ${DESTDIR}
 260 may be modified using the
 261 .Va INSTKERNNAME
 262 and
 263 .Va KODIR
 264 .Xr make 1
 265 variables.
 266 .It Cm kernel
 267 Equivalent to
 268 .Cm buildkernel
 269 followed by
 270 .Cm installkernel
 271 .It Cm kernel-toolchain
 272 Rebuild the tools needed for kernel compilation.
 273 Use this if you did not do a
 274 .Cm buildworld
 275 first.
 276 .It Cm reinstallkernel
 277 Reinstall the kernel and the kernel modules, overwriting the contents
 278 of the target directory.
 279 As with the
 280 .Cm installkernel
 281 target, the target directory can be specified using the
 282 .Xr make 1
 283 variable
 284 .Va INSTKERNNAME .
 285 .El
 286 .Pp
 287 Convenience targets for cleaning up the install destination directory
 288 denoted by variable
 289 .Va DESTDIR
 290 include:
 291 .Bl -tag -width ".Cm delete-old-libs"
 292 .It Cm check-old
 293 Print a list of old files and directories in the system.
 294 .It Cm delete-old
 295 Delete obsolete base system files and directories interactively.
 296 When
 297 .Li -DBATCH_DELETE_OLD_FILES
 298 is specified at the command line, the delete operation will be
 299 non-interactive.
 300 The variables
 301 .Va DESTDIR ,
 302 .Va TARGET_ARCH
 303 and
 304 .Va TARGET
 305 should be set as with
 306 .Dq Li "make installworld" .
 307 .It Cm delete-old-libs
 308 Delete obsolete base system libraries interactively.
 309 This target should only be used if no 3rd party software uses these
 310 libraries.
 311 When
 312 .Li -DBATCH_DELETE_OLD_FILES
 313 is specified at the command line, the delete operation will be
 314 non-interactive.
 315 The variables
 316 .Va DESTDIR ,
 317 .Va TARGET_ARCH
 318 and
 319 .Va TARGET
 320 should be set as with
 321 .Dq Li "make installworld" .
 322 .El
 323 .Sh ENVIRONMENT
 324 Variables that influence all builds include:
 325 .Bl -tag -width ".Va MAKEOBJDIRPREFIX"
 326 .It Va DEBUG_FLAGS
 327 Defines a set of debugging flags that will be used to build all userland
 328 binaries under
 329 .Pa /usr/src .
 330 When
 331 .Va DEBUG_FLAGS
 332 is defined, the
 333 .Cm install
 334 and
 335 .Cm installworld
 336 targets install binaries from the current
 337 .Va MAKEOBJDIRPREFIX
 338 without stripping,
 339 so that debugging information is retained in the installed binaries.
 340 .It Va DESTDIR
 341 The directory hierarchy prefix where built objects will be installed.
 342 If not set,
 343 .Va DESTDIR
 344 defaults to the empty string.
 345 .It Va MAKEOBJDIRPREFIX
 346 Defines the prefix for directory names in the tree of built objects.
 347 Defaults to
 348 .Pa /usr/obj
 349 if not defined.
 350 This variable should only be set in the environment and not via
 351 .Pa /etc/make.conf
 352 or the command line.
 353 .It Va NO_WERROR
 354 If defined, compiler warnings will not cause the build to halt,
 355 even if the makefile says otherwise.
 356 .El
 357 .Pp
 358 Additionally, builds in
 359 .Pa /usr/src
 360 are influenced by the following
 361 .Xr make 1
 362 variables:
 363 .Bl -tag -width ".Va SUBDIR_OVERRIDE"
 364 .It Va KERNCONF
 365 Overrides which kernel to build and install for the various kernel
 366 make targets.
 367 It defaults to
 368 .Cm GENERIC .
 369 .It Va KERNFAST
 370 If set, the build target
 371 .Cm buildkernel
 372 defaults to setting
 373 .Va NO_KERNELCLEAN ,
 374 .Va NO_KERNELCONFIG ,
 375 .Va NO_KERNELDEPEND
 376 and
 377 .Va NO_KERNELOBJ .
 378 When set to a value other than
 379 .Cm 1
 380 then
 381 .Va KERNCONF
 382 is set to the value of
 383 .Va KERNFAST .
 384 .It Va LOCAL_DIRS
 385 If set, this variable supplies a list of additional directories to
 386 build, relative to the root of the source tree.
 387 .It Va PORTS_MODULES
 388 A list of ports with kernel modules that should be built and installed
 389 as part of the
 390 .Cm buildkernel
 391 and
 392 .Cm installkernel
 393 process.
 394 .Bd -literal -offset indent
 395 make PORTS_MODULES=emulators/kqemu-kmod kernel
 396 .Ed
 397 .It Va SUBDIR_OVERRIDE
 398 Override the default list of sub-directories and only build the
 399 sub-directory named in this variable.
 400 This variable is useful when debugging failed builds.
 401 .Bd -literal -offset indent
 402 make some-target SUBDIR_OVERRIDE=foo/bar
 403 .Ed
 404 .It Va TARGET
 405 The target hardware platform.
 406 This is analogous to the
 407 .Dq Nm uname Fl m
 408 output.
 409 This is necessary to cross-build some target architectures.
 410 For example, cross-building for PC98 machines requires
 411 .Va TARGET_ARCH Ns = Ns Li i386
 412 and
 413 .Va TARGET Ns = Ns Li pc98 .
 414 If not set,
 415 .Va TARGET
 416 defaults to the current hardware platform.
 417 .It Va TARGET_ARCH
 418 The target machine processor architecture.
 419 This is analogous to the
 420 .Dq Nm uname Fl p
 421 output.
 422 Set this to cross-build for a different architecture.
 423 If not set,
 424 .Va TARGET_ARCH
 425 defaults to the current machine architecture, unless
 426 .Va TARGET
 427 is also set, in which case it defaults to the appropriate
 428 value for that platform.
 429 Typically, one only needs to set
 430 .Va TARGET .
 431 .El
 432 .Pp
 433 Builds under directory
 434 .Pa /usr/src
 435 are also influenced by defining one or more of the following symbols,
 436 using the
 437 .Fl D
 438 option of
 439 .Xr make 1 :
 440 .Bl -tag -width ".Va -DNO_KERNELDEPEND"
 441 .It Va NO_CLEANDIR
 442 If set, the build targets that clean parts of the object tree use the
 443 equivalent of
 444 .Dq make clean
 445 instead of
 446 .Dq make cleandir .
 447 .It Va NO_CLEAN
 448 If set, no object tree files are cleaned at all.
 449 Setting
 450 .Va NO_CLEAN
 451 implies
 452 .Va NO_KERNELCLEAN ,
 453 so when
 454 .Va NO_CLEAN
 455 is set no kernel objects are cleaned either.
 456 .It Va NO_CTF
 457 If set, the build process does not run the DTrace CTF conversion tools
 458 on built objects.
 459 .It Va NO_SHARE
 460 If set, the build does not descend into the
 461 .Pa /usr/src/share
 462 subdirectory (i.e., manpages, locale data files, timezone data files and
 463 other
 464 .Pa /usr/src/share
 465 files will not be rebuild from their sources).
 466 .It Va NO_KERNELCLEAN
 467 If set, the build process does not run
 468 .Dq make clean
 469 as part of the
 470 .Cm buildkernel
 471 target.
 472 .It Va NO_KERNELCONFIG
 473 If set, the build process does not run
 474 .Xr config 8
 475 as part of the
 476 .Cm buildkernel
 477 target.
 478 .It Va NO_KERNELDEPEND
 479 If set, the build process does not run
 480 .Dq make depend
 481 as part of the
 482 .Cm buildkernel
 483 target.
 484 .It Va NO_KERNELOBJ
 485 If set, the build process does not run
 486 .Dq make obj
 487 as part of the
 488 .Cm buildkernel
 489 target.
 490 .It Va NO_DOCUPDATE
 491 If set, the update process does not update the source of the
 492 .Fx
 493 documentation as part of the
 494 .Dq make update
 495 target.
 496 .It Va NO_PORTSUPDATE
 497 If set, the update process does not update the Ports tree as part of the
 498 .Dq make update
 499 target.
 500 .El
 501 .Pp
 502 Builds under directory
 503 .Pa /usr/doc
 504 are influenced by the following
 505 .Xr make 1
 506 variables:
 507 .Bl -tag -width ".Va DOC_LANG"
 508 .It Va DOC_LANG
 509 If set, restricts the documentation build to the language subdirectories
 510 specified as its content.
 511 The default action is to build documentation for all languages.
 512 .El
 513 .Pp
 514 Builds using the
 515 .Cm universe
 516 target are influenced by the following
 517 .Xr make 1
 518 variables:
 519 .Bl -tag -width ".Va MAKE_JUST_KERNELS"
 520 .It Va JFLAG
 521 Pass the value of this variable to each
 522 .Xr make 1
 523 invocation used to build worlds and kernels.
 524 This can be used to enable multiple jobs within a single architecture's build
 525 while still building each architecture serially.
 526 .It Va MAKE_JUST_KERNELS
 527 Only build kernels for each supported architecture.
 528 .It Va MAKE_JUST_WORLDS
 529 Only build worlds for each supported architecture.
 530 .It Va UNIVERSE_TARGET
 531 Execute the specified
 532 .Xr make 1
 533 target for each supported architecture instead of the default action of
 534 building a world and one or more kernels.
 535 .El
 536 .Sh FILES
 537 .Bl -tag -width ".Pa /usr/share/examples/etc/make.conf" -compact
 538 .It Pa /usr/doc/Makefile
 539 .It Pa /usr/doc/share/mk/doc.project.mk
 540 .It Pa /usr/ports/Mk/bsd.port.mk
 541 .It Pa /usr/ports/Mk/bsd.sites.mk
 542 .It Pa /usr/share/examples/etc/make.conf
 543 .It Pa /usr/src/Makefile
 544 .It Pa /usr/src/Makefile.inc1
 545 .El
 546 .Sh EXAMPLES
 547 For an
 548 .Dq approved
 549 method of updating your system from the latest sources, please see the
 550 .Sx COMMON ITEMS
 551 section in
 552 .Pa src/UPDATING .
 553 .Pp
 554 The following sequence of commands can be used to cross-build the
 555 system for the sparc64 architecture on an i386 host:
 556 .Bd -literal -offset indent
 557 cd /usr/src
 558 make TARGET=sparc64 buildworld
 559 make TARGET=sparc64 DESTDIR=/clients/sparc64 installworld
 560 .Ed
 561 .Sh SEE ALSO
 562 .Xr cc 1 ,
 563 .Xr csup 1 ,
 564 .Xr install 1 ,
 565 .Xr make 1 ,
 566 .Xr svn 1 ,
 567 .Xr make.conf 5 ,
 568 .Xr src.conf 5 ,
 569 .Xr ports 7 ,
 570 .Xr release 7 ,
 571 .Xr config 8 ,
 572 .Xr mergemaster 8 ,
 573 .Xr reboot 8 ,
 574 .Xr shutdown 8
 575 .Sh AUTHORS
 576 .An Mike W. Meyer Aq mwm@mired.org .