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