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