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