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 December 5, 2005 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.It Cm toolchain 207Create the build toolchain needed to build the rest of the system. 208For cross-architecture builds, this step creates a cross-toolchain. 209.It Cm universe 210Execute a 211.Cm buildworld 212and 213.Cm buildkernel 214for all kernels including 215.Pa LINT , 216for each architecture supported by the build system. 217This command takes a long time. 218.It Cm update 219Get updated sources as configured in 220.Xr make.conf 5 . 221.El 222.Pp 223Kernel specific build targets in 224.Pa /usr/src 225are: 226.Bl -tag -width ".Cm reinstallkernel" 227.It Cm buildkernel 228Rebuild the kernel and the kernel modules. 229.It Cm installkernel 230Install the kernel and the kernel modules to directory 231.Pa ${DESTDIR}/boot/kernel , 232renaming any pre-existing directory with this name to 233.Pa kernel.old 234if it contained the currently running kernel. 235The target directory under 236.Pa ${DESTDIR} 237may be modified using the 238.Va INSTKERNNAME 239and 240.Va KODIR 241.Xr make 1 242variables. 243.It Cm kernel 244Equivalent to 245.Cm buildkernel 246followed by 247.Cm installkernel 248.It Cm kernel-toolchain 249Rebuild the tools needed for kernel compilation. 250Use this if you did not do a 251.Cm buildworld 252first. 253.It Cm reinstallkernel 254Reinstall the kernel and the kernel modules, overwriting the contents 255of the target directory. 256As with the 257.Cm installkernel 258target, the target directory can be specified using the 259.Xr make 1 260variable 261.Va INSTKERNNAME . 262.El 263.Pp 264Convenience targets for cleaning up the install destination directory 265denoted by variable 266.Va DESTDIR 267include: 268.Bl -tag -width ".Cm delete-old-libs" 269.It Cm check-old 270Print a list of old files and directores in the system. 271.It Cm delete-old 272Delete obsolete base system files and directories interactively. 273When 274.Li -DBATCH_DELETE_OLD_FILES 275is specified at the command line, the delete operation will be 276non-interactive. 277The variables 278.Va DESTDIR , 279.Va TARGET_ARCH 280and 281.Va TARGET 282should be set as with 283.Dq Li "make installworld" . 284.It Cm delete-old-libs 285Delete obsolete base system libraries interactively. 286This target should only be used if no 3rd party software uses these 287libraries. 288When 289.Li -DBATCH_DELETE_OLD_FILES 290is specified at the command line, the delete operation will be 291non-interactive. 292The variables 293.Va DESTDIR , 294.Va TARGET_ARCH 295and 296.Va TARGET 297should be set as with 298.Dq Li "make installworld" . 299.El 300.Sh ENVIRONMENT 301Variables that influence all builds include: 302.Bl -tag -width ".Va MAKEOBJDIRPREFIX" 303.It Va DESTDIR 304The directory hierarchy prefix where built objects will be installed. 305If not set, 306.Va DESTDIR 307defaults to the empty string. 308.It Va MAKEOBJDIRPREFIX 309Defines the prefix for directory names in the tree of built objects. 310Defaults to 311.Pa /usr/obj 312if not defined. 313This variable should only be set in the environment and not via 314.Pa /etc/make.conf 315or the command line. 316.It Va NO_WERROR 317If defined, compiler warnings will not cause the build to halt, 318even if the makefile says otherwise. 319.El 320.Pp 321Additionally, builds in 322.Pa /usr/src 323are influenced by the following 324.Xr make 1 325variables: 326.Bl -tag -width ".Va SUBDIR_OVERRIDE" 327.It Va LOCAL_DIRS 328If set, this variable supplies a list of additional directories to 329build, relative to the root of the source tree. 330.It Va SUBDIR_OVERRIDE 331Override the default list of sub-directories and only build the 332sub-directory named in this variable. 333This variable is useful when debugging failed builds. 334.Bd -literal -offset indent 335make some-target SUBDIR_OVERRIDE=foo/bar 336.Ed 337.It Va TARGET 338The target hardware platform. 339This is analogous to the 340.Dq Nm uname Fl m 341output. 342This is necessary to cross-build some target architectures. 343For example, cross-building for PC98 machines requires 344.Va TARGET_ARCH Ns = Ns Li i386 345and 346.Va TARGET Ns = Ns Li pc98 . 347If not set, 348.Va TARGET 349defaults to the current hardware platform. 350.It Va TARGET_ARCH 351The target machine processor architecture. 352This is analogous to the 353.Dq Nm uname Fl p 354output. 355Set this to cross-build for a different architecture. 356If not set, 357.Va TARGET_ARCH 358defaults to the current machine architecture. 359.El 360.Pp 361Builds under directory 362.Pa /usr/doc 363are influenced by the following 364.Xr make 1 365variables: 366.Bl -tag -width ".Va DOC_LANG" 367.It Va DOC_LANG 368If set, restricts the documentation build to the language subdirectories 369specified as its content. 370The default action is to build documentation for all languages. 371.El 372.Sh FILES 373.Bl -tag -width ".Pa /usr/share/examples/etc/make.conf" -compact 374.It Pa /usr/doc/Makefile 375.It Pa /usr/doc/share/mk/doc.project.mk 376.It Pa /usr/ports/Mk/bsd.port.mk 377.It Pa /usr/ports/Mk/bsd.sites.mk 378.It Pa /usr/share/examples/etc/make.conf 379.It Pa /usr/src/Makefile 380.It Pa /usr/src/Makefile.inc1 381.El 382.Sh EXAMPLES 383For an 384.Dq approved 385method of updating your system from the latest sources, please see the 386.Sx COMMON ITEMS 387section in 388.Pa src/UPDATING . 389.Pp 390The following sequence of commands can be used to cross-build the 391system for the Alpha architecture on an i386 host: 392.Bd -literal -offset indent 393cd /usr/src 394make TARGET_ARCH=alpha buildworld 395make TARGET_ARCH=alpha DESTDIR=/clients/axp installworld 396.Ed 397.Sh SEE ALSO 398.Xr cc 1 , 399.Xr install 1 , 400.Xr make 1 , 401.Xr make.conf 5 , 402.Xr ports 7 , 403.Xr release 7 , 404.Xr config 8 , 405.Xr mergemaster 8 , 406.Xr reboot 8 , 407.Xr shutdown 8 408.Sh AUTHORS 409.An Mike W. Meyer Aq mwm@mired.org . 410