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