Differential D28881 Diff 84571 share/man/man7/release.7

Changeset View

Standalone View

share/man/man7/release.7

	Show All 18 Lines
	.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)			.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
	.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT			.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
	.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY			.\" 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			.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
	.\" SUCH DAMAGE.			.\" SUCH DAMAGE.
	.\"			.\"
	.\" $FreeBSD$			.\" $FreeBSD$
	.\"			.\"
	.Dd September 1, 2020			.Dd February 23, 2021
	.Dt RELEASE 7			.Dt RELEASE 7
	.Os			.Os
	.Sh NAME			.Sh NAME
	.Nm release			.Nm release
	.Nd "release building infrastructure"			.Nd "release building infrastructure"
	.Sh DESCRIPTION			.Sh DESCRIPTION
	.Fx			.Fx
	provides a complete build environment suitable for users to make			provides a complete build environment suitable for users to make
	▲ Show 20 Lines • Show All 102 Lines • ▼ Show 20 Lines
	.Bl -tag -width Ev			.Bl -tag -width Ev
	.It Va CHROOTDIR			.It Va CHROOTDIR
	The directory within which the release will be built.			The directory within which the release will be built.
	.It Va CHROOT_MAKEENV			.It Va CHROOT_MAKEENV
	Additional			Additional
	.Xr make 1			.Xr make 1
	arguments to pass through, which directly affect the			arguments to pass through, which directly affect the
	tuning of the build chroot.			tuning of the build chroot.
	.It Va SVNROOT			.It Va GITROOT
	The			The
	.Xr svn 1			.Xr git 1
	host used to check out the various trees.			host used to check out the various trees.
	Defaults to			Defaults to
	.Pa svn://svn.FreeeBSD.org .			.Pa https://git.FreeeBSD.org .
	.It Va SRCBRANCH			.It Va SRCBRANCH
	The			The
	.Li src/			.Li src/
	branch to use.			branch to use.
	Defaults to			Defaults to
	.Va head/@rHEAD .			.Fl b Va main .
	.It Va DOCBRANCH
	The
	.Li doc/
	branch to use.
	Defaults to
	.Va head/@rHEAD .
	.It Va PORTBRANCH			.It Va PORTBRANCH
	The			The
	.Li ports/			.Li ports/
	branch to use.			branch to use.
	Defaults to			Defaults to
	.Va head/@rHEAD .			.Va head/@rHEAD .
	.It Va TARGET			.It Va TARGET
	The target machine type for cross-building a release.			The target machine type for cross-building a release.
	▲ Show 20 Lines • Show All 49 Lines • ▼ Show 20 Lines
	during the			during the
	.Dq buildkernel			.Dq buildkernel
	phase.			phase.
	Defaults to setting the number of			Defaults to setting the number of
	.Xr make 1			.Xr make 1
	jobs			jobs
	.Pq Ar -j			.Pq Ar -j
	to half the number of CPUs available on a SMP-capable system.			to half the number of CPUs available on a SMP-capable system.
	.It Va NODOC
	Set to a non-empty value to skip the
	.Li doc/
	tree checkout.
	When set,
	.Va NODOC
	will prevent the
	.Fa doc.txz
	distribution package from being created.
	.It Va NOPORTS			.It Va NOPORTS
	Set to a non-empty value to skip the			Set to a non-empty value to skip the
	.Li ports/			.Li ports/
	tree checkout.			tree checkout.
	When set,			When set,
	.Va NOPORTS			.Va NOPORTS
	will prevent the			will prevent the
	.Fa ports.txz			.Fa ports.txz
	distribution package from being created.			distribution package from being created.
	Setting this also sets
	.Va NODOC .
	.It Va WITH_DVD			.It Va WITH_DVD
	Set to a non-empty value to include the			Set to a non-empty value to include the
	.Cm dvdrom			.Cm dvdrom
	target.			target.
	.It Va WITH_COMPRESSED_IMAGES			.It Va WITH_COMPRESSED_IMAGES
	Set to a non-empty value to compress the release images with			Set to a non-empty value to compress the release images with
	.Xr xz 1 .			.Xr xz 1 .
	The original			The original
	.Pq uncompressed			.Pq uncompressed
	images are not removed.			images are not removed.
	.It Va XZ_THREADS Pq Vt int			.It Va XZ_THREADS Pq Vt int
	Set to the number of threads			Set to the number of threads
	.Xr xz 1			.Xr xz 1
	should use when compressing images.			should use when compressing images.
	By default,			By default,
	.Va XZ_THREADS			.Va XZ_THREADS
	is set to			is set to
	.Va 0 ,			.Va 0 ,
	which uses all available cores on the system.			which uses all available cores on the system.
	.It Va VCSCMD			.It Va VCSCMD
	The command run to obtain the source trees.			The command run to obtain the source trees.
	Defaults to			Defaults to
	.Qq Cm svn checkout .			.Qq Cm git clone Fl q .
	.It Va CHROOTBUILD_SKIP			.It Va CHROOTBUILD_SKIP
	If defined, the			If defined, the
	.Li buildworld ,			.Li buildworld ,
	.Li installworld ,			.Li installworld ,
	and			and
	.Li distribution			.Li distribution
	stages of the			stages of the
	.Xr chroot 8			.Xr chroot 8
	build environment setup are skipped.			build environment setup are skipped.
	This is intended solely for cases where the			This is intended solely for cases where the
	.Xr chroot 8			.Xr chroot 8
	userland are provided by alternate means.			userland are provided by alternate means.
	.It Va SRC_UPDATE_SKIP			.It Va SRC_UPDATE_SKIP
	Set to a non-empty value to prevent checkout or update of			Set to a non-empty value to prevent checkout or update of
	.Fa /usr/src			.Fa /usr/src
	within the			within the
	.Xr chroot 8 .			.Xr chroot 8 .
	This is intended for use only when			This is intended for use only when
	.Fa /usr/src			.Fa /usr/src
	is expected to exist by alternative means.			is expected to exist by alternative means.
	.It Va DOC_UPDATE_SKIP
	Set to a non-empty value to prevent checkout or update of
	.Fa /usr/doc
	within the
	.Xr chroot 8 .
	This is intended for use only when
	.Fa /usr/doc
	is expected to exist by alternative means.
	.It Va PORTS_UPDATE_SKIP			.It Va PORTS_UPDATE_SKIP
	Set to a non-empty value to prevent checkout or update of			Set to a non-empty value to prevent checkout or update of
	.Fa /usr/ports			.Fa /usr/ports
	within the			within the
	.Xr chroot 8 .			.Xr chroot 8 .
	This is intended for use only when			This is intended for use only when
	.Fa /usr/ports			.Fa /usr/ports
	is expected to exist by alternative means.			is expected to exist by alternative means.
	.El			.El
	.Sh EMBEDDED BUILDS			.Sh EMBEDDED BUILDS
	The following			The following
	.Fa release.conf			.Fa release.conf
	variables are relevant only to release builds for embedded systems:			variables are relevant only to release builds for embedded systems:
	.Bl -tag -width Ev			.Bl -tag -width Ev
	.It Va EMBEDDEDBUILD			.It Va EMBEDDEDBUILD
	Set to a non-null value to enable functionality for embedded device			Set to a non-null value to enable functionality for embedded device
	release builds.			release builds.
	.Pp			.Pp
	When set,			When set,
	.Va WITH_DVD			.Va WITH_DVD
	is unset, and			is unset.
	.Va NODOC
	is defined.
	Additionally,			Additionally,
	.Va EMBEDDED_TARGET			.Va EMBEDDED_TARGET
	and			and
	.Va EMBEDDED_TARGET_ARCH			.Va EMBEDDED_TARGET_ARCH
	must also be defined.			must also be defined.
	When the build environment is created,			When the build environment is created,
	.Fa release.sh			.Fa release.sh
	runs a separate build script located in an architecture-specific			runs a separate build script located in an architecture-specific
	▲ Show 20 Lines • Show All 251 Lines • ▼ Show 20 Lines
	By default, the directory			By default, the directory
	above the one containing the makefile			above the one containing the makefile
	.Pq Pa src .			.Pq Pa src .
	.It Ev PORTSDIR			.It Ev PORTSDIR
	Location of a directory containing the ports tree.			Location of a directory containing the ports tree.
	By default,			By default,
	.Pa /usr/ports .			.Pa /usr/ports .
	If it is unset or cannot be found, ports will not be included in the release.			If it is unset or cannot be found, ports will not be included in the release.
	.It Ev DOCDIR
	Location of a directory containing the doc tree.
	By default,
	.Pa /usr/doc .
	If it is unset or cannot be found, most documentation will not be included in
	the release; see
	.Ev NODOC
	below.
	.It Ev NOPORTS			.It Ev NOPORTS
	If defined, the Ports Collection will be omitted from the release.			If defined, the Ports Collection will be omitted from the release.
	.It Ev NOSRC			.It Ev NOSRC
	If set, do not include system source code in the release.			If set, do not include system source code in the release.
	.It Ev NODOC
	If defined, the XML-based documentation from the
	.Fx
	Documentation Project will not be built.
	However, the
	.Dq doc
	distribution will still be created with the minimal documentation set
	provided in
	.Pa src/share/doc .
	.It Ev TARGET			.It Ev TARGET
	The target hardware platform.			The target hardware platform.
	This is analogous to the			This is analogous to the
	.Dq Nm uname Fl m			.Dq Nm uname Fl m
	output.			output.
	This is necessary to cross-build some target architectures.			This is necessary to cross-build some target architectures.
	For example, cross-building for ARM64 machines requires			For example, cross-building for ARM64 machines requires
	.Ev TARGET_ARCH Ns = Ns Li aarch64			.Ev TARGET_ARCH Ns = Ns Li aarch64
	Show All 33 Lines
	.It Pa /usr/src/release/tools/*.conf			.It Pa /usr/src/release/tools/*.conf
	.It Pa /usr/src/release/tools/vmimage.subr			.It Pa /usr/src/release/tools/vmimage.subr
	.El			.El
	.Sh EXAMPLES			.Sh EXAMPLES
	The following sequence of commands can be used to build a			The following sequence of commands can be used to build a
	.Dq "-CURRENT snapshot":			.Dq "-CURRENT snapshot":
	.Bd -literal -offset indent			.Bd -literal -offset indent
	cd /usr			cd /usr
	svn co svn://svn.freebsd.org/base/head src			git clone https://git.freebsd.org/src.git src
				gjbUnsubmitted Not Done Inline Actions This should reference '-b main', as the svn equivalent would checkout from head as written. gjb: This should reference '-b main', as the svn equivalent would checkout from head as written.
	cd src			cd src
	make buildworld buildkernel			make buildworld buildkernel
	cd release			cd release
	make obj			make obj
	make release			make release
	make install DESTDIR=/var/freebsd-snapshot			make install DESTDIR=/var/freebsd-snapshot
	.Ed			.Ed
	.Pp			.Pp
	Show All 40 Lines
	.Pp			.Pp
	After running these commands, all prepared release files are available in the			After running these commands, all prepared release files are available in the
	.Pa /scratch			.Pa /scratch
	directory.			directory.
	The target directory can be changed by specifying the			The target directory can be changed by specifying the
	.Va CHROOTDIR			.Va CHROOTDIR
	variable in			variable in
	.Li release.conf .			.Li release.conf .
				.Sh COMPATIBILITY
				The reldoc target was removed in commit f61e92ca5a23, and
				lwhsuUnsubmitted Done Inline Actions I suggest using the output of `git rev-parse --short`, which will detect how long the short hash is enough. So `f61e92ca5a23`. lwhsu: I suggest using the output of `git rev-parse --short`, which will detect how long the short…
				lwhsuUnsubmitted Done Inline Actions The hash length is still 8, what src repo uses is 12. lwhsu: The hash length is still 8, what src repo uses is 12.
				.Ev DOCDIR ,
				.Ev DOCBRANCH ,
				.Ev DOC_UPDATE_SKIP ,
				and
				.Ev NODOC
				are therefore no longer supported.
	.Sh SEE ALSO			.Sh SEE ALSO
	.Xr cc 1 ,			.Xr cc 1 ,
				.Xr git 1 Pq Pa ports/devel/git ,
				yuripvUnsubmitted Done Inline Actions bad sort order yuripv: bad sort order
	.Xr install 1 ,			.Xr install 1 ,
	.Xr make 1 ,			.Xr make 1 ,
	.Xr svn 1 Pq Pa ports/devel/subversion ,
	.Xr uname 1 ,			.Xr uname 1 ,
	.Xr md 4 ,			.Xr md 4 ,
	.Xr make.conf 5 ,			.Xr make.conf 5 ,
	.Xr build 7 ,			.Xr build 7 ,
	.Xr ports 7 ,			.Xr ports 7 ,
	.Xr chroot 8 ,			.Xr chroot 8 ,
	.Xr mtree 8 ,			.Xr mtree 8 ,
	.Xr sysctl 8			.Xr sysctl 8
	Show All 36 Lines
	.Pa src/release/release.sh			.Pa src/release/release.sh
	was introduced to support per-build configuration files.			was introduced to support per-build configuration files.
	.Pa src/release/release.sh			.Pa src/release/release.sh
	is heavily based on the			is heavily based on the
	.Pa src/release/generate-release.sh			.Pa src/release/generate-release.sh
	script.			script.
	.Pp			.Pp
	At near 1000 revisions spread over multiple branches, the			At near 1000 revisions spread over multiple branches, the
	.Xr svn 1			.Xr git 1
	log of			log of
	.Pa src/release/Makefile			.Pa src/release/Makefile
	contains a vivid historical record of some			contains a vivid historical record of some
	of the hardships release engineers go through.			of the hardships release engineers go through.
	.Sh AUTHORS			.Sh AUTHORS
	.Pa src/release/Makefile			.Pa src/release/Makefile
	was originally written by			was originally written by
	.An -nosplit			.An -nosplit
	Show All 23 Lines