Date: Wed, 24 Sep 2025 20:23:17 GMT From: Alexander Ziaee <ziaee@FreeBSD.org> To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-main@FreeBSD.org Subject: git: 275f61111f43 - main - build/development.7: System building examples Message-ID: <202509242023.58OKNHGg061940@gitrepo.freebsd.org>
next in thread | raw e-mail | index | archive | help
The branch main has been updated by ziaee: URL: https://cgit.FreeBSD.org/src/commit/?id=275f61111f43507a01eef064efc660f1fa72b6a9 commit 275f61111f43507a01eef064efc660f1fa72b6a9 Author: Alexander Ziaee <ziaee@FreeBSD.org> AuthorDate: 2025-09-24 20:06:56 +0000 Commit: Alexander Ziaee <ziaee@FreeBSD.org> CommitDate: 2025-09-24 20:22:28 +0000 build/development.7: System building examples Consolidate examples to build the system in the build(7) manual where the details about the syntax involved is documented. Remove them from development(7), instead adding examples for patching the trees. They are left in UPDATING for now, to hopefully be removed eventually. Reduce documentation proliferation and create consistent, maintainable doc about building the system, eventually removing the COMMMON ITEMS section of UPDATING so there is a single source of truth in the cannon and well-integrated location, the in-band system reference manual. + Example 1: Build and upgrade system in place + Example 2: Build and upgrade a custom kernel in place + Example 3: Build and upgrade a single piece of userspace + Example 4: Build and upgrade a loadable kernel module + Example 5: Quickly rebuild a kernel in place + Example 6: Cross-compiling for different architectures The examples section of development(7) now contains examples for applying patches to the trees. There is certainy much more to do here, but it needs to be chunked. MFC after: 3 days Reviewed by: imp (previous version), ivy (previous version) Discussed with: emaste, imp, jhb, ivy Differential Revision: https://reviews.freebsd.org/D48693 --- share/man/man7/build.7 | 245 +++++++++++++++++++++++++++++++++++-------- share/man/man7/development.7 | 113 ++++++++------------ 2 files changed, 241 insertions(+), 117 deletions(-) diff --git a/share/man/man7/build.7 b/share/man/man7/build.7 index 45a3034843d8..bfe464d4448e 100644 --- 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 @@ 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 -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 @@ The canonical object directory is described in the documentation for the .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 @@ The target directory under .Pa ${DESTDIR} may be modified using the .Va INSTKERNNAME -and +or .Va KODIR .Xr make 1 variables. @@ -563,6 +559,9 @@ should be set to the name of the package. 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 @@ then .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 @@ fringe uses that do not have a wide appeal. .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 @@ make TARGET=arm64 DESTDIR=/clients/arm64 installworld installkernel .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 @@ manpage first appeared in .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 index 1b875fb14bda..348302a50ee7 100644 --- 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 @@ There is also a list of public, read-only Git mirrors at: 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 @@ such as freebsd-arch@ and freebsd-hackers@: 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 @@ the continuous integration system is at: .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 ,
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?202509242023.58OKNHGg061940>