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