Page MenuHomeFreeBSD
Files F142248874

D48693.diff
No OneTemporary
Actions

D48693.diff
View Options

diff --git a/share/man/man7/build.7 b/share/man/man7/build.7
--- a/share/man/man7/build.7
+++ b/share/man/man7/build.7
@@ -1,4 +1,4 @@
-.\"-
+.\"
.\" SPDX-License-Identifier: BSD-2-Clause
.\"
.\" Copyright (c) 2000
@@ -25,7 +25,7 @@
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
-.Dd September 13, 2025
+.Dd September 24, 2025
.Dt BUILD 7
.Os
.Sh NAME
@@ -36,34 +36,28 @@
.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
-Git
-.Po installed from packages with
-.Xr pkg 7
-or from
-.Xr ports 7 Pc .
-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 .
+system and its applications are contained in three directories,
+normally:
+.Bl -tag -width "/usr/ports"
+.It Pa /usr/src
+.Dq base system ,
+loosely defined as everything required to build the system
+to a useful state
+.It Pa /usr/doc
+system documentation, excluding manual pages
+.It Pa /usr/ports
+third-party software, with a consistent interface for building and
+installing them; see
+.Xr ports 7
+.El
+.Pp
+These directories may be initially empty or non-existent until updated
+with Git
+.Po Pa devel/git
+from the
+.Fx
+Ports Collection
+.Pc .
.Pp
The
.Xr make 1
@@ -92,7 +86,9 @@
.Cm buildworld
target below.
.Pp
-The build may be controlled by defining
+The
+.Nm
+may be controlled by defining
.Xr make 1
variables described in the
.Sx ENVIRONMENT
@@ -406,7 +402,7 @@
.Pa ${DESTDIR}
may be modified using the
.Va INSTKERNNAME
-and
+or
.Va KODIR
.Xr make 1
variables.
@@ -563,6 +559,9 @@
LLVM toolchain packages use the name llvm<major version>.
GCC toolchains provide separate packages for each architecture and use the
name ${MACHINE_ARCH}-gcc<major version>.
+.It Va INSTKERNNAME
+If set, specify an alternative name to build and install for the various
+kernel make targets.
.It Va KERNCONF
Overrides which kernel to build and install for the various kernel
make targets.
@@ -597,6 +596,9 @@
.Va KERNCONF
is set to the value of
.Va KERNFAST .
+.It Va KODIR
+If set,
+this variable specifies an alternative directory to install the kernel.
.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
@@ -945,26 +947,159 @@
.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
+.Xr make 1
+infrastructure for each tree
+.It Pa /usr/ports/UPDATING
+.It Pa /usr/src/UPDATING
+notable changes in each tree
+.It Pa /usr/share/examples/etc/make.conf
+example
+.Xr make.conf 5
+.It Pa /etc/src.conf
+src build configuration, see
+.Xr src.conf 5
.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 .
+This section describes best practices for common situations.
+When manual intervention is necessary, it will be mentioned in
+.Pa UPDATING .
+Make sure you have full backups before proceeding!
+.Ss Example 1: Build and upgrade system in place
+If using installed drivers such as graphics or virtual machine guest
+drivers, check out the
+.Xr ports 7
+tree, and specify the drivers in
+.Xr src.conf 5
+so they are built and installed automatically after the kernel:
+.Bd -literal -offset indent
+git clone https://git.FreeBSD.org/ports.git /usr/ports
+cat << EOF >> /etc/src.conf
+PORTS_MODULES+=graphics/drm-kmod emulators/virtualbox-ose-kmod
+EOF
+.Ed
+.Pp
+Check out the CURRENT branch, build it, and install,
+overwriting the current system:
+.Bd -literal -offset indent
+git clone https://git.FreeBSD.org/src.git /usr/src
+cd /usr/src
+make buildworld buildkernel
+make installkernel
+shutdown -r now
+.Ed
.Pp
-The following sequence of commands can be used to cross-build the system for
-the arm64 (aarch64) architecture on a different host architecture, such as
-amd64:
+For major version upgrades, boot into single-user mode.
+After restarting, install userspace, and merge configurations.
+After verifying that you do not need them, delete old files
+and libraries:
.Bd -literal -offset indent
cd /usr/src
-make TARGET=arm64 buildworld buildkernel
-make TARGET=arm64 DESTDIR=/clients/arm64 installworld installkernel
+etcupdate -p
+make installworld
+etcupdate -B
+make delete-old delete-old-libs
+shutdown -r now
+.Ed
+.Ss Example 2: Build and upgrade a custom kernel in place
+Create a custom kernel configuration,
+.Va MYKERNEL ,
+by including an existing configuration and using
+.Cm device Ns / Ns Cm nodevice
+and
+.Cm options Ns / Ns Cm nooption
+to select and configure components:
+.Bd -literal -offset indent
+cd /usr/src
+cat << EOF > sys/amd64/conf/MYKERNEL
+include GENERIC
+ident MYKERNEL
+nodevice sound
+EOF
+.Ed
+.Pp
+After creating the new kernel configuration, build a fresh toolchain,
+build the kernel, and install it, moving the old kernel to
+.Pa /boot/kernel.old/ :
+.Bd -literal -offset indent
+make kernel-toolchain
+make -DALWAYS_CHECK_MAKE buildkernel KERNCONF=MYKERNEL
+make -DALWAYS_CHECK_MAKE installkernel KERNCONF=MYKERNEL
+shutdown -r now
.Ed
+.Pp
+To build the kernel to an alternate location, use the
+.Va INSTKERNNAME
+variable and boot it once to test via
+.Xr nextboot 8 :
+.Bd -literal -offset indent
+make installkernel KERNCONF=MYKERNEL INSTKERNNAME=testkernel
+nextboot -k testkernel
+shutdown -r now
+.Ed
+.Ss Example 3: Build and upgrade a single piece of userspace
+Rebuild and reinstall a single piece of userspace, in this case
+.Xr ls 1 :
+.Bd -literal -offset indent
+cd /usr/src/bin/ls
+make clean all
+make install
+.Ed
+.Ss Example 4: Build and upgrade a loadable kernel module
+Rebuild and reinstall a single loadable kernel module, in this case
+.Xr sound 4 :
+.Bd -literal -offset indent
+cd /usr/src/sys/modules/sound
+make all install clean cleandepend KMODDIR=/boot/kernel
+.Ed
+.Ss Example 5: Quickly rebuild a kernel in place
+Quickly rebuild and reinstall the kernel, only recompiling the files
+changed since last build; note that this will only work if the full
+kernel build has been completed in the past, not on a fresh source tree:
+.Bd -literal -offset indent
+cd /usr/src
+make kernel KERNFAST=1
+.Ed
+.Ss Example 6: Cross-compiling for different architectures
+To rebuild parts of
+.Fx
+for another CPU architecture,
+first prepare your source tree by building the cross-toolchain:
+.Bd -literal -offset indent
+cd src
+make toolchain TARGET_ARCH=aarch64
+.Ed
+.Pp
+The following sequence of commands can be used to cross-build the system
+for the arm64 (aarch64) architecture on a different host architecture,
+such as amd64:
+.Bd -literal -offset indent
+cd /usr/src
+make TARGET_ARCH=aarch64 buildworld buildkernel
+make TARGET_ARCH=aarch64 DESTDIR=/armclient installworld installkernel
+.Ed
+.Pp
+Afterwards, to build and install a single piece of userspace, use:
+.Bd -literal -offset indent
+cd src/bin/ls
+make buildenv TARGET_ARCH=aarch64
+make clean all install DESTDIR=/armclient
+.Ed
+.Pp
+Likewise, to quickly rebuild and reinstall the kernel, use:
+.Bd -literal -offset indent
+cd src
+make buildenv TARGET_ARCH=aarch64
+make kernel KERNFAST=1 DESTDIR=/armclient
+.Ed
+.Sh DIAGNOSTICS
+.Bl -diag
+.It Bad system call (core dumped)
+.It rescue/sh check failed, installation aborted
+.Pp
+The kernel was not updated due to incorrect build procedure.
+Study the examples above.
.Sh SEE ALSO
.Xr cc 1 ,
.Xr install 1 ,
@@ -979,7 +1114,7 @@
.Xr tests 7 ,
.Xr config 8 ,
.Xr etcupdate 8 ,
-.Xr reboot 8 ,
+.Xr nextboot 8 ,
.Xr shutdown 8
.Sh HISTORY
The
@@ -988,3 +1123,23 @@
.Fx 4.3 .
.Sh AUTHORS
.An Mike W. Meyer Aq Mt mwm@mired.org
+.Sh CAVEATS
+Old objects can cause obscure build problems; try
+.Ql make cleandir cleandir .
+.Pp
+Environment poisioning can cause obscure build problems; try prefixing
+.Xr make 1
+commands with
+.Ql env -i
+.Pp
+When doing a major release upgrade,
+booting into single user mode for
+.Cm installworld
+is required.
+.Pp
+Updating the boot
+.Xr loader 8
+is architecture specific.
+Consult
+.Xr boot 8
+for your architecture for more details.
diff --git a/share/man/man7/development.7 b/share/man/man7/development.7
--- a/share/man/man7/development.7
+++ b/share/man/man7/development.7
@@ -1,4 +1,4 @@
-.\"-
+.\"
.\" SPDX-License-Identifier: BSD-2-Clause
.\"
.\" Copyright (c) 2018 Edward Tomasz Napierala <trasz@FreeBSD.org>
@@ -24,7 +24,7 @@
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
-.Dd January 19, 2025
+.Dd September 24, 2025
.Dt DEVELOPMENT 7
.Os
.Sh NAME
@@ -75,13 +75,14 @@
The
.Ql main
Git branch represents CURRENT;
-all changes are first committed to CURRENT and then usually cherry-picked
-back to STABLE, which refers to Git branches such as
-.Ql stable/13 .
+all changes are first committed to CURRENT and then usually
+cherry-picked back to STABLE, which refers to Git branches such as
+.Ql stable/14 .
Every few years a new STABLE is branched from CURRENT,
with an incremented major version number.
-Releases are then branched off STABLE and numbered with consecutive minor
-numbers.
+Releases are then branched off STABLE and numbered with consecutive
+minor numbers such as
+.Ql releng/14.3
.Pp
The layout of the source tree is described in its
.Pa README.md
@@ -107,12 +108,16 @@
To get your patches integrated into the main
.Fx
repository use Phabricator;
-it is a code review tool that allows other developers to review the changes,
-suggest improvements, and, eventually, allows them to pick up the change and
-commit it:
+it is a code review tool that allows other developers to
+review the changes, suggest improvements, and, eventually,
+allows them to pick up the change and commit it:
.Pp
.Lk https://reviews.FreeBSD.org
.Pp
+Or Github:
+.Pp
+.Lk https://github.com/freebsd
+.Pp
To check the latest
.Fx
build and test status of CURRENT and STABLE branches,
@@ -120,77 +125,41 @@
.Pp
.Lk https://ci.FreeBSD.org
.Sh FILES
-.Bl -compact -tag -width "/usr/src/tools/tools/git/git-arc.sh"
+.Bl -tag -compact -width "/usr/ports/devel/freebsd-git-devtools"
.It Pa /usr/src/CONTRIBUTING.md
.Fx
contribution guidelines
.It Pa /usr/src/tools/tools/git/git-arc.sh
Phabricator review tooling
+.It Pa /usr/ports/devel/freebsd-git-devtools
+Phabricator review tooling as a port
.El
.Sh EXAMPLES
-Check out the CURRENT branch, build it, and install, overwriting the current
-system:
-.Bd -literal -offset indent
-git clone https://git.FreeBSD.org/src.git src
-cd src
-make -sj8 buildworld buildkernel installkernel
-shutdown -r now
-.Ed
-.Pp
-After reboot:
-.Bd -literal -offset indent
-cd src
-make -j8 installworld
-reboot
-.Ed
-.Pp
-Rebuild and reinstall a single piece of userspace, in this
-case
-.Xr ls 1 :
-.Bd -literal -offset indent
-cd src/bin/ls
-make clean all install
-.Ed
-.Pp
-Rebuild and reinstall a single loadable kernel module, in this case
-.Xr sound 4 :
-.Bd -literal -offset indent
-cd src/sys/modules/sound
-make all install clean cleandepend KMODDIR=/boot/kernel
-.Ed
-.Pp
-Quickly rebuild and reinstall the kernel, only recompiling the files
-changed since last build; note that this will only work if the full kernel
-build has been completed in the past, not on a fresh source tree:
-.Bd -literal -offset indent
-cd src
-make -sj8 kernel KERNFAST=1
-.Ed
-.Pp
-To rebuild parts of
-.Fx
-for another CPU architecture,
-first prepare your source tree by building the cross-toolchain:
-.Bd -literal -offset indent
-cd src
-make -sj8 toolchain TARGET_ARCH=aarch64
-.Ed
-.Pp
-Afterwards, to build and install a single piece of userspace, use:
-.Bd -literal -offset indent
-cd src/bin/ls
-make buildenv TARGET_ARCH=aarch64
-make clean all install DESTDIR=/clients/arm
-.Ed
-.Pp
-Likewise, to quickly rebuild and reinstall the kernel, use:
-.Bd -literal -offset indent
-cd src
-make buildenv TARGET_ARCH=aarch64
-make -sj8 kernel KERNFAST=1 DESTDIR=/clients/arm
-.Ed
+Apply a patch from Github pull #1234, using
+.Pa devel/gh :
+.Pp
+.Dl gh pr checkout 1234
+.Pp
+Apply a patch from Phabricator review D1234, using
+.Xr git-arc 1 :
+.Pp
+.Dl git arc patch -c D1234
+.Pp
+Apply a manually downloaded
+.Xr git-format-patch 1 ,
+.Pa draft.patch ,
+from Bugzilla or mail:
+.Pp
+.Dl git am draft.patch
+.Pp
+Apply a manually downloaded patch,
+.Pa draft.diff ,
+from Bugzilla or mail:
+.Pp
+.Dl git apply draft.diff
.Sh SEE ALSO
.Xr git 1 ,
+.Xr git-arc 1 ,
.Xr witness 4 ,
.Xr build 7 ,
.Xr hier 7 ,

File Metadata

Mime Type
text/plain
Expires
Sun, Jan 18, 7:18 PM (1 h, 29 m)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
27716113
Default Alt Text
D48693.diff (12 KB)

Event Timeline