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