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 January 28, 2017 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 LOCAL_XTOOL_DIRS 466If set, this variable supplies a list of additional directories relative to 467the root of the source tree to build as part of the 468.Cm cross-tools 469target. 470.It Va PORTS_MODULES 471A list of ports with kernel modules that should be built and installed 472as part of the 473.Cm buildkernel 474and 475.Cm installkernel 476process. 477.Bd -literal -offset indent 478make PORTS_MODULES=emulators/kqemu-kmod kernel 479.Ed 480.It Va STRIPBIN 481Command to use at install time when stripping binaries. 482Be sure to add any additional tools required to run 483.Va STRIPBIN 484to the 485.Va LOCAL_ITOOLS 486.Xr make 1 487variable before running the 488.Cm distributeworld 489or 490.Cm installworld 491targets. 492See 493.Xr install 1 494for more details. 495.It Va SUBDIR_OVERRIDE 496Override the default list of sub-directories and only build the 497sub-directory named in this variable. 498If combined with 499.Cm buildworld 500then all libraries and includes, and some of the build tools will still build 501as well. 502When combined with 503.Cm buildworld 504it is necesarry to override 505.Va LOCAL_LIB_DIRS 506with any custom directories containing libraries. 507This allows building a subset of the system in the same way as 508.Cm buildworld 509does using its sysroot handling. 510This variable can also be useful when debugging failed builds. 511.Bd -literal -offset indent 512make some-target SUBDIR_OVERRIDE=foo/bar 513.Ed 514.It Va TARGET 515The target hardware platform. 516This is analogous to the 517.Dq Nm uname Fl m 518output. 519This is necessary to cross-build some target architectures. 520For example, cross-building for ARM64 machines requires 521.Va TARGET_ARCH Ns = Ns Li aarch64 522and 523.Va TARGET Ns = Ns Li arm64 . 524If not set, 525.Va TARGET 526defaults to the current hardware platform. 527.It Va TARGET_ARCH 528The target machine processor architecture. 529This is analogous to the 530.Dq Nm uname Fl p 531output. 532Set this to cross-build for a different architecture. 533If not set, 534.Va TARGET_ARCH 535defaults to the current machine architecture, unless 536.Va TARGET 537is also set, in which case it defaults to the appropriate 538value for that platform. 539Typically, one only needs to set 540.Va TARGET . 541.El 542.Pp 543Builds under directory 544.Pa /usr/src 545are also influenced by defining one or more of the following symbols, 546using the 547.Fl D 548option of 549.Xr make 1 : 550.Bl -tag -width ".Va -DNO_KERNELCONFIG" 551.It Va NO_CLEANDIR 552If set, the build targets that clean parts of the object tree use the 553equivalent of 554.Dq make clean 555instead of 556.Dq make cleandir . 557.It Va NO_CLEAN 558If set, no object tree files are cleaned at all. 559This is the default when 560.Va WITH_META_MODE 561is used with 562.Xr filemon 4 563loaded. 564See 565.Xr src.conf 5 566for more details. 567Setting 568.Va NO_CLEAN 569implies 570.Va NO_KERNELCLEAN , 571so when 572.Va NO_CLEAN 573is set no kernel objects are cleaned either. 574.It Va NO_CTF 575If set, the build process does not run the DTrace CTF conversion tools 576on built objects. 577.It Va NO_SHARE 578If set, the build does not descend into the 579.Pa /usr/src/share 580subdirectory (i.e., manual pages, locale data files, timezone data files and 581other 582.Pa /usr/src/share 583files will not be rebuild from their sources). 584.It Va NO_KERNELCLEAN 585If set, the build process does not run 586.Dq make clean 587as part of the 588.Cm buildkernel 589target. 590.It Va NO_KERNELCONFIG 591If set, the build process does not run 592.Xr config 8 593as part of the 594.Cm buildkernel 595target. 596.It Va NO_KERNELOBJ 597If set, the build process does not run 598.Dq make obj 599as part of the 600.Cm buildkernel 601target. 602.It Va NO_DOCUPDATE 603If set, the update process does not update the source of the 604.Fx 605documentation as part of the 606.Dq make update 607target. 608.It Va NO_PORTSUPDATE 609If set, the update process does not update the Ports tree as part of the 610.Dq make update 611target. 612.It Va NO_WWWUPDATE 613If set, the update process does not update the www tree as part of the 614.Dq make update 615target. 616.El 617.Pp 618Builds under directory 619.Pa /usr/doc 620are influenced by the following 621.Xr make 1 622variables: 623.Bl -tag -width ".Va DOC_LANG" 624.It Va DOC_LANG 625If set, restricts the documentation build to the language subdirectories 626specified as its content. 627The default action is to build documentation for all languages. 628.El 629.Pp 630Builds using the 631.Cm universe 632target are influenced by the following 633.Xr make 1 634variables: 635.Bl -tag -width ".Va MAKE_JUST_KERNELS" 636.It Va JFLAG 637Pass the value of this variable to each 638.Xr make 1 639invocation used to build worlds and kernels. 640This can be used to enable multiple jobs within a single architecture's build 641while still building each architecture serially. 642.It Va MAKE_JUST_KERNELS 643Only build kernels for each supported architecture. 644.It Va MAKE_JUST_WORLDS 645Only build worlds for each supported architecture. 646.It Va UNIVERSE_TARGET 647Execute the specified 648.Xr make 1 649target for each supported architecture instead of the default action of 650building a world and one or more kernels. 651.El 652.Sh FILES 653.Bl -tag -width ".Pa /usr/share/examples/etc/make.conf" -compact 654.It Pa /usr/doc/Makefile 655.It Pa /usr/doc/share/mk/doc.project.mk 656.It Pa /usr/ports/Mk/bsd.port.mk 657.It Pa /usr/ports/Mk/bsd.sites.mk 658.It Pa /usr/share/examples/etc/make.conf 659.It Pa /usr/src/Makefile 660.It Pa /usr/src/Makefile.inc1 661.El 662.Sh EXAMPLES 663For an 664.Dq approved 665method of updating your system from the latest sources, please see the 666.Sx COMMON ITEMS 667section in 668.Pa src/UPDATING . 669.Pp 670The following sequence of commands can be used to cross-build the 671system for the sparc64 architecture on an i386 host: 672.Bd -literal -offset indent 673cd /usr/src 674make TARGET=sparc64 buildworld 675make TARGET=sparc64 DESTDIR=/clients/sparc64 installworld 676.Ed 677.Sh SEE ALSO 678.Xr cc 1 , 679.Xr install 1 , 680.Xr make 1 , 681.Xr svn 1 , 682.Xr make.conf 5 , 683.Xr src.conf 5 , 684.Xr ports 7 , 685.Xr release 7 , 686.Xr config 8 , 687.Xr mergemaster 8 , 688.Xr portsnap 8 , 689.Xr reboot 8 , 690.Xr shutdown 8 , 691.Xr tests 7 692.Sh AUTHORS 693.An Mike W. Meyer Aq Mt mwm@mired.org 694