diff options
Diffstat (limited to 'share/man/man7/build.7')
| -rw-r--r-- | share/man/man7/build.7 | 631 |
1 files changed, 631 insertions, 0 deletions
diff --git a/share/man/man7/build.7 b/share/man/man7/build.7 new file mode 100644 index 0000000..a2172ed --- /dev/null +++ b/share/man/man7/build.7 @@ -0,0 +1,631 @@ +.\" Copyright (c) 2000 +.\" Mike W. Meyer +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd June 25, 2014 +.Dt BUILD 7 +.Os +.Sh NAME +.Nm build +.Nd information on how to build the system +.Sh DESCRIPTION +The sources for the +.Fx +system and its applications are contained in three different directories, +normally +.Pa /usr/src , +.Pa /usr/doc , +and +.Pa /usr/ports . +These directories may be initially empty or non-existent until updated with +.Xr svn 1 +or +.Xr portsnap 8 . +Directory +.Pa /usr/src +contains the +.Dq "base system" +sources, which is loosely defined as the things required to rebuild +the system to a useful state. +Directory +.Pa /usr/doc +contains the source for the system documentation, excluding the manual +pages. +Directory +.Pa /usr/ports +contains a tree that provides a consistent interface for building and +installing third party applications. +For more information about the ports build process, see +.Xr ports 7 . +.Pp +The +.Xr make 1 +command is used in each of these directories to build and install the +things in that directory. +Issuing the +.Xr make 1 +command in any directory or +subdirectory of those directories has the same effect as issuing the +same command in all subdirectories of that directory. +With no target specified, the things in that directory are just built. +.Pp +A source tree is allowed to be read-only. +As described in +.Xr make 1 , +objects are usually built in a separate object directory hierarchy +specified by the environment variable +.Va MAKEOBJDIRPREFIX , +or under +.Pa /usr/obj +if variable +.Va MAKEOBJDIRPREFIX +is not set. +For a given source directory, its canonical object directory +would be +.Pa ${MAKEOBJDIRPREFIX}${.CURDIR} +if +.Xr make 1 +variable +.Va MAKEOBJDIRPREFIX +is set, or +.Pa /usr/obj${.CURDIR} +if this variable is not set. +Cross-builds set the object directory as described in the +documentation for the +.Cm buildworld +target below. +.Pp +The build may be controlled by defining +.Xr make 1 +variables described in the +.Sx ENVIRONMENT +section below, and by the variables documented in +.Xr make.conf 5 . +.Pp +The following list provides the names and actions for the targets +supported by the build system: +.Bl -tag -width ".Cm cleandepend" +.It Cm clean +Remove any files created during the build process. +.It Cm cleandepend +Remove the file +.Pa ${.OBJDIR}/${DEPENDFILE} +generated by a prior +.Dq Li "make depend" +step. +.It Cm cleandir +Remove the canonical object directory if it exists, or perform +actions equivalent to +.Dq Li "make clean cleandepend" +if it does not. +This target will also remove an +.Pa obj +link in +.Pa ${.CURDIR} +if that exists. +.Pp +It is advisable to run +.Dq Li "make cleandir" +twice: the first invocation will remove the canonical object directory +and the second one will clean up +.Pa ${.CURDIR} . +.It Cm depend +Generate a list of build dependencies in file +.Pa ${.OBJDIR}/${DEPENDFILE} . +.It Cm install +Install the results of the build to the appropriate location in the +installation directory hierarchy specified in variable +.Va DESTDIR . +.It Cm obj +Create the canonical object directory associated with the current +directory. +.It Cm objlink +Create a symbolic link to the canonical object directory in +.Pa ${.CURDIR} . +.It Cm tags +Generate a tags file using the program specified in the +.Xr make 1 +variable +.Va CTAGS . +The build system supports +.Xr ctags 1 +and +.Nm "GNU Global" . +.El +.Pp +The other supported targets under directory +.Pa /usr/src +are: +.Bl -tag -width ".Cm distributeworld" +.It Cm buildenv +Spawn an interactive shell with environment variables set up for +cross-building the system. +The target architecture needs to be specified with +.Xr make 1 +variables +.Va TARGET_ARCH +and +.Va TARGET . +.Pp +This target is only useful after a complete cross-toolchain including +the compiler, linker, assembler, headers and libraries has been +built; see the +.Cm toolchain +target below. +.It Cm buildworld +Build everything but the kernel, configure files in +.Pa etc , +and +.Pa release . +The actual build location prefix used is +.Pa ${MAKEOBJDIRPREFIX}${.CURDIR} +for native builds, and +.Pa ${MAKEOBJDIRPREFIX}/${TARGET}${.CURDIR} +for cross builds and native builds with variable +.Va CROSS_BUILD_TESTING +set. +.It Cm cleanworld +Attempt to clean up targets built by a preceding +.Cm buildworld +step. +.It Cm distributeworld +Distribute everything compiled by a preceding +.Cm buildworld +step. +Files are placed in the directory hierarchy specified by +.Xr make 1 +variable +.Va DISTDIR . +This target is used while building a release; see +.Xr release 7 . +.It Cm packageworld +Archive the results of +.Cm distributeworld , +placing the results in +.Va DISTDIR . +This target is used while building a release; see +.Xr release 7 . +.It Cm installworld +Install everything built by a preceding +.Cm buildworld +step into the directory hierarchy pointed to by +.Xr make 1 +variable +.Va DESTDIR . +.Pp +If installing onto an NFS file system and running +.Xr make 1 +with the +.Fl j +option, make sure that +.Xr rpc.lockd 8 +is running on both client and server. +See +.Xr rc.conf 5 +on how to make it start at boot time. +.It Cm toolchain +Create the build toolchain needed to build the rest of the system. +For cross-architecture builds, this step creates a cross-toolchain. +.It Cm universe +For each architecture, +execute a +.Cm buildworld +followed by a +.Cm buildkernel +for all kernels for that architecture, +including +.Pa LINT . +This command takes a long time. +.It Cm update +Get updated sources as configured in +.Xr make.conf 5 . +.It Cm targets +Print a list of supported +.Va TARGET +/ +.Va TARGET_ARCH +pairs for world and kernel targets. +.It Cm tinderbox +Execute the same targets as +.Cm universe . +In addition print a summary of all failed targets at the end and +exit with an error if there were any. +.It Cm toolchains +Create a build toolchain for each architecture supported by the build system. +.El +.Pp +Kernel specific build targets in +.Pa /usr/src +are: +.Bl -tag -width ".Cm distributekernel" +.It Cm buildkernel +Rebuild the kernel and the kernel modules. +.It Cm installkernel +Install the kernel and the kernel modules to directory +.Pa ${DESTDIR}/boot/kernel , +renaming any pre-existing directory with this name to +.Pa kernel.old +if it contained the currently running kernel. +The target directory under +.Pa ${DESTDIR} +may be modified using the +.Va INSTKERNNAME +and +.Va KODIR +.Xr make 1 +variables. +.It Cm distributekernel +Install the kernel to the directory +.Pa ${DISTDIR}/kernel/boot/kernel . +This target is used while building a release; see +.Xr release 7 . +.It Cm packagekernel +Archive the results of +.Cm distributekernel , +placing the results in +.Va DISTDIR . +This target is used while building a release; see +.Xr release 7 . +.It Cm kernel +Equivalent to +.Cm buildkernel +followed by +.Cm installkernel +.It Cm kernel-toolchain +Rebuild the tools needed for kernel compilation. +Use this if you did not do a +.Cm buildworld +first. +.It Cm reinstallkernel +Reinstall the kernel and the kernel modules, overwriting the contents +of the target directory. +As with the +.Cm installkernel +target, the target directory can be specified using the +.Xr make 1 +variable +.Va INSTKERNNAME . +.El +.Pp +Convenience targets for cleaning up the install destination directory +denoted by variable +.Va DESTDIR +include: +.Bl -tag -width ".Cm delete-old-libs" +.It Cm check-old +Print a list of old files and directories in the system. +.It Cm delete-old +Delete obsolete base system files and directories interactively. +When +.Li -DBATCH_DELETE_OLD_FILES +is specified at the command line, the delete operation will be +non-interactive. +The variables +.Va DESTDIR , +.Va TARGET_ARCH +and +.Va TARGET +should be set as with +.Dq Li "make installworld" . +.It Cm delete-old-libs +Delete obsolete base system libraries interactively. +This target should only be used if no 3rd party software uses these +libraries. +When +.Li -DBATCH_DELETE_OLD_FILES +is specified at the command line, the delete operation will be +non-interactive. +The variables +.Va DESTDIR , +.Va TARGET_ARCH +and +.Va TARGET +should be set as with +.Dq Li "make installworld" . +.El +.Sh ENVIRONMENT +Variables that influence all builds include: +.Bl -tag -width ".Va MAKEOBJDIRPREFIX" +.It Va DEBUG_FLAGS +Defines a set of debugging flags that will be used to build all userland +binaries under +.Pa /usr/src . +When +.Va DEBUG_FLAGS +is defined, the +.Cm install +and +.Cm installworld +targets install binaries from the current +.Va MAKEOBJDIRPREFIX +without stripping, +so that debugging information is retained in the installed binaries. +.It Va DESTDIR +The directory hierarchy prefix where built objects will be installed. +If not set, +.Va DESTDIR +defaults to the empty string. +.It Va MAKEOBJDIRPREFIX +Defines the prefix for directory names in the tree of built objects. +Defaults to +.Pa /usr/obj +if not defined. +This variable should only be set in the environment and not via +.Pa /etc/make.conf +or the command line. +.It Va NO_WERROR +If defined, compiler warnings will not cause the build to halt, +even if the makefile says otherwise. +.It Va WITH_CTF +If defined, the build process will run the DTrace CTF conversion +tools on built objects. +.El +.Pp +Additionally, builds in +.Pa /usr/src +are influenced by the following +.Xr make 1 +variables: +.Bl -tag -width ".Va SUBDIR_OVERRIDE" +.It Va KERNCONF +Overrides which kernel to build and install for the various kernel +make targets. +It defaults to +.Cm GENERIC . +.It Va KERNFAST +If set, the build target +.Cm buildkernel +defaults to setting +.Va NO_KERNELCLEAN , +.Va NO_KERNELCONFIG , +.Va NO_KERNELDEPEND +and +.Va NO_KERNELOBJ . +When set to a value other than +.Cm 1 +then +.Va KERNCONF +is set to the value of +.Va KERNFAST . +.It Va LOCAL_DIRS +If set, this variable supplies a list of additional directories relative to +the root of the source tree to build as part of the +.Cm everything +target. +.It Va LOCAL_ITOOLS +If set, this variable supplies a list of additional tools that are used by the +.Cm installworld +and +.Cm distributeworld +targets. +.It Va LOCAL_LIB_DIRS +If set, this variable supplies a list of additional directories relative to +the root of the source tree to build as part of the +.Cm libraries +target. +.It Va LOCAL_MTREE +If set, this variable supplies a list of additional mtrees relative to the +root of the source tree to use as part of the +.Cm hierarchy +target. +.It Va LOCAL_TOOL_DIRS +If set, this variable supplies a list of additional directories relative to +the root of the source tree to build as part of the +.Cm build-tools +target. +.It Va PORTS_MODULES +A list of ports with kernel modules that should be built and installed +as part of the +.Cm buildkernel +and +.Cm installkernel +process. +.Bd -literal -offset indent +make PORTS_MODULES=emulators/kqemu-kmod kernel +.Ed +.It Va SUBDIR_OVERRIDE +Override the default list of sub-directories and only build the +sub-directory named in this variable. +This variable is useful when debugging failed builds. +.Bd -literal -offset indent +make some-target SUBDIR_OVERRIDE=foo/bar +.Ed +.It Va TARGET +The target hardware platform. +This is analogous to the +.Dq Nm uname Fl m +output. +This is necessary to cross-build some target architectures. +For example, cross-building for PC98 machines requires +.Va TARGET_ARCH Ns = Ns Li i386 +and +.Va TARGET Ns = Ns Li pc98 . +If not set, +.Va TARGET +defaults to the current hardware platform. +.It Va TARGET_ARCH +The target machine processor architecture. +This is analogous to the +.Dq Nm uname Fl p +output. +Set this to cross-build for a different architecture. +If not set, +.Va TARGET_ARCH +defaults to the current machine architecture, unless +.Va TARGET +is also set, in which case it defaults to the appropriate +value for that platform. +Typically, one only needs to set +.Va TARGET . +.El +.Pp +Builds under directory +.Pa /usr/src +are also influenced by defining one or more of the following symbols, +using the +.Fl D +option of +.Xr make 1 : +.Bl -tag -width ".Va -DNO_KERNELDEPEND" +.It Va NO_CLEANDIR +If set, the build targets that clean parts of the object tree use the +equivalent of +.Dq make clean +instead of +.Dq make cleandir . +.It Va NO_CLEAN +If set, no object tree files are cleaned at all. +Setting +.Va NO_CLEAN +implies +.Va NO_KERNELCLEAN , +so when +.Va NO_CLEAN +is set no kernel objects are cleaned either. +.It Va NO_CTF +If set, the build process does not run the DTrace CTF conversion tools +on built objects. +.It Va NO_SHARE +If set, the build does not descend into the +.Pa /usr/src/share +subdirectory (i.e., manpages, locale data files, timezone data files and +other +.Pa /usr/src/share +files will not be rebuild from their sources). +.It Va NO_KERNELCLEAN +If set, the build process does not run +.Dq make clean +as part of the +.Cm buildkernel +target. +.It Va NO_KERNELCONFIG +If set, the build process does not run +.Xr config 8 +as part of the +.Cm buildkernel +target. +.It Va NO_KERNELDEPEND +If set, the build process does not run +.Dq make depend +as part of the +.Cm buildkernel +target. +.It Va NO_KERNELOBJ +If set, the build process does not run +.Dq make obj +as part of the +.Cm buildkernel +target. +.It Va NO_DOCUPDATE +If set, the update process does not update the source of the +.Fx +documentation as part of the +.Dq make update +target. +.It Va NO_PORTSUPDATE +If set, the update process does not update the Ports tree as part of the +.Dq make update +target. +.It Va NO_WWWUPDATE +If set, the update process does not update the www tree as part of the +.Dq make update +target. +.El +.Pp +Builds under directory +.Pa /usr/doc +are influenced by the following +.Xr make 1 +variables: +.Bl -tag -width ".Va DOC_LANG" +.It Va DOC_LANG +If set, restricts the documentation build to the language subdirectories +specified as its content. +The default action is to build documentation for all languages. +.El +.Pp +Builds using the +.Cm universe +target are influenced by the following +.Xr make 1 +variables: +.Bl -tag -width ".Va MAKE_JUST_KERNELS" +.It Va JFLAG +Pass the value of this variable to each +.Xr make 1 +invocation used to build worlds and kernels. +This can be used to enable multiple jobs within a single architecture's build +while still building each architecture serially. +.It Va MAKE_JUST_KERNELS +Only build kernels for each supported architecture. +.It Va MAKE_JUST_WORLDS +Only build worlds for each supported architecture. +.It Va UNIVERSE_TARGET +Execute the specified +.Xr make 1 +target for each supported architecture instead of the default action of +building a world and one or more kernels. +.El +.Sh FILES +.Bl -tag -width ".Pa /usr/share/examples/etc/make.conf" -compact +.It Pa /usr/doc/Makefile +.It Pa /usr/doc/share/mk/doc.project.mk +.It Pa /usr/ports/Mk/bsd.port.mk +.It Pa /usr/ports/Mk/bsd.sites.mk +.It Pa /usr/share/examples/etc/make.conf +.It Pa /usr/src/Makefile +.It Pa /usr/src/Makefile.inc1 +.El +.Sh EXAMPLES +For an +.Dq approved +method of updating your system from the latest sources, please see the +.Sx COMMON ITEMS +section in +.Pa src/UPDATING . +.Pp +The following sequence of commands can be used to cross-build the +system for the sparc64 architecture on an i386 host: +.Bd -literal -offset indent +cd /usr/src +make TARGET=sparc64 buildworld +make TARGET=sparc64 DESTDIR=/clients/sparc64 installworld +.Ed +.Sh SEE ALSO +.Xr cc 1 , +.Xr install 1 , +.Xr make 1 , +.Xr svn 1 , +.Xr make.conf 5 , +.Xr src.conf 5 , +.Xr ports 7 , +.Xr release 7 , +.Xr config 8 , +.Xr mergemaster 8 , +.Xr portsnap 8 , +.Xr reboot 8 , +.Xr shutdown 8 +.Sh AUTHORS +.An Mike W. Meyer Aq Mt mwm@mired.org |
