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