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