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