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