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