From owner-svn-src-head@FreeBSD.ORG Sun Aug 11 18:57:27 2013 Return-Path: Delivered-To: svn-src-head@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) (using TLSv1 with cipher ADH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTP id 9F0734D4; Sun, 11 Aug 2013 18:57:27 +0000 (UTC) (envelope-from gjb@FreeBSD.org) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:1900:2254:2068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mx1.freebsd.org (Postfix) with ESMTPS id 8B10122D1; Sun, 11 Aug 2013 18:57:27 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.7/8.14.7) with ESMTP id r7BIvRhh080971; Sun, 11 Aug 2013 18:57:27 GMT (envelope-from gjb@svn.freebsd.org) Received: (from gjb@localhost) by svn.freebsd.org (8.14.7/8.14.5/Submit) id r7BIvRSq080970; Sun, 11 Aug 2013 18:57:27 GMT (envelope-from gjb@svn.freebsd.org) Message-Id: <201308111857.r7BIvRSq080970@svn.freebsd.org> From: Glen Barber Date: Sun, 11 Aug 2013 18:57:27 +0000 (UTC) To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org Subject: svn commit: r254224 - head/share/man/man7 X-SVN-Group: head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-src-head@freebsd.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: SVN commit messages for the src tree for head/-current List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sun, 11 Aug 2013 18:57:27 -0000 Author: gjb Date: Sun Aug 11 18:57:27 2013 New Revision: 254224 URL: http://svnweb.freebsd.org/changeset/base/254224 Log: - Update the wrapper script to 'release.sh', as used by the FreeBSD Release Engineering Team as of 9.2-RELEASE. - Document that a cross-build release is possible by setting the TARGET and TARGET_ARCH variables. - Include an example of using release.sh with and without the optional configuration file. - Document the supported release.sh configuration file variables. - Update the 'cdrom' target output file to disc1.iso. - Update the 'memstick' target output file to memstick.img. - Add attributions for the last major updates to this manual page. - Fix some mdoc(7) style nits: - Sentences should begin on a new line - Use .Pq to enclose full lines in parenthesis Modified: head/share/man/man7/release.7 Modified: head/share/man/man7/release.7 ============================================================================== --- head/share/man/man7/release.7 Sun Aug 11 18:05:20 2013 (r254223) +++ head/share/man/man7/release.7 Sun Aug 11 18:57:27 2013 (r254224) @@ -24,7 +24,7 @@ .\" .\" $FreeBSD$ .\" -.Dd February 3, 2013 +.Dd August 11, 2013 .Dt RELEASE 7 .Os .Sh NAME @@ -50,8 +50,9 @@ For some users, it may be desirable to p build environment, with no local modifications to the source tree or to .Xr make.conf 5 , and with clean checkouts of specific versions of the doc, src, and ports -trees. For this purpose, a script -.Pq Pa src/release/generate-release.sh +trees. +For this purpose, a script +.Pq Pa src/release/release.sh is provided to automate these checkouts and then execute .Dq Li "make release" in a clean @@ -70,86 +71,194 @@ and .Dq Li "make buildkernel" . This is necessary to provide the object files for the release or, when using -.Pa generate-release.sh , +.Pa release.sh , so that the object files for a complete system can be installed into a clean .Xr chroot 8 -environment. In this second case, the built world must be capable of running -on the build system (i.e. it must be for the same architecture and be -compatible with the installed kernel). +environment. +.Pp +If the target release build is for a different architecture or machine type, +the +.Va TARGET +and +.Va TARGET_ARCH +variables must be used. +See the supported +.Fa release.conf +variables for more information. +.Pp The release procedure on some architectures may also require that the .Xr md 4 (memory disk) device driver be present in the kernel -(either by being compiled in or available as a module). +.Pq either by being compiled in or available as a module . .Pp This document does not cover source code management, quality assurance, or other aspects of the release engineering process. .Sh CLEAN RELEASE GENERATION -Official releases of FreeBSD are produced in a totally clean environment to +Official releases of +.Fx +are produced in a totally clean environment to ensure consistency between the versions of the src, ports, and doc trees -and to avoid contamination from the host system (e.g. local patches, changes +and to avoid contamination from the host system +.Po such as local patches, changes to .Xr make.conf 5 , -etc.). This is accomplished using the wrapper script -.Pa src/release/generate-release.sh . -.Pp -.Ic generate-release.sh -svn-branch scratch-dir -.Pp -.Ic generate-release.sh -calls +etc. +.Pc . +This is accomplished using the wrapper script +.Pa src/release/release.sh . +.Pp +.Ic release.sh +.Op Fl c Ar release.conf +.Pp +.Ic release.sh +checks out the +.Li src/ , +.Li ports/ , +and +.Li doc/ +trees to +.Va CHROOTDIR , +then calls +.Dq Li "make buildworld" +and .Dq Li "make installworld" to generate a .Xr chroot 8 -environment in -.Ar scratch-dir . -It then checks out the src tree specified by -.Ar svn-branch -using -.Xr svn 1 . -Once the various source trees have been obtained, it executes +environment. +Next, .Dq Li "make release" -within the +is run within the .Xr chroot 8 environment and places the result in -.Pa $scratch-dir/R . -Note that because this uses a chroot, it cannot be used to cross-build -.Fx -release media. +.Pa $CHROOTDIR/R . .Pp -Optional environment variables: -.Bl -tag -width ".Cm WORLD_FLAGS" -.It Ev WORLD_FLAGS -This environment variable can be set to pass flags (e.g. -j) to -.Xr make 1 -when invoked to build a world by the script. -.It Ev KERNEL_FLAGS -This environment variable can be set to pass flags (e.g. -j) to -.Xr make 1 -when invoked to build a kernel by the script. -.It Ev SVNROOTBASE -The base part of URL of the FreeBSD SVN repositories. +The optional +.Fa release.conf +configuration file supports the following variables: +.Bl -tag -width Ev +.It Va CHROOTDIR +The directory within which the release will be built. +.It Va SVNROOT +The +.Xr svn 1 +host used to check out the various trees. Defaults to -.Pa svn://svn.freebsd.org . -.It Ev SVNROOTSRC -The URL of the FreeBSD SVN source repository. +.Pa svn://svn.FreeeBSD.org . +.It Va SRCBRANCH +The +.Li src/ +branch to use. Defaults to -.Pa ${SVNROOTBASE}/base . -.It Ev SVNROOTDOC -The URL of the FreeBSD SVN doc repository. +.Va head/ . +.It Va DOCBRANCH +The +.Li doc/ +branch to use. Defaults to -.Pa ${SVNROOTBASE}/doc . -.It Ev SVNROOTPORTS -The URL of the FreeBSD SVN ports repository. +.Va head/ . +.It Va PORTBRANCH +The +.Li ports/ +branch to use. Defaults to -.Pa ${SVNROOTBASE}/ports . -.It Ev BRANCHDOC -The branch name of the FreeBSD SVN doc repository. +.Va head/ . +.It Va SRCREVISION +The revision of the +.Li src/ +tree to use. +Defaults to the current top of tree revision. +.It Va DOCREVISION +The revision of the +.Li doc/ +tree to use. +Defaults to the current top of tree revision. +.It Va PORTREVISION +The revision of the +.Li ports/ +tree to use. +Defaults to the current top of tree revision. +.It Va TARGET +The target machine type for the release. +Defaults to the current machine type. +.It Va TARGET_ARCH +The target machine architecture for the release. +Defaults to the value of +.Va TARGET . +.Pp +For the supported list of +.Va TARGET +and +.Va TARGET_ARCH +combinations, consult the output of +.Dq make targets +as documented in +.Xr build 7 . +.It Va KERNEL +The target kernel configuration to use. Defaults to -.Pa head . -.It Ev BRANCHPORTS -The branch name of the FreeBSD SVN ports repository. +.Va GENERIC . +Multiple +.Va KERNEL +entries may be specified. +.It Va MAKE_CONF +The +.Xr make.conf 5 +to use for the release build. Defaults to -.Pa head . +.Fa /dev/null +to prevent polluting the release with local system changes. +.It Va SRC_CONF +The +.Xr src.conf 5 +to use for the release build. +Defaults to +.Fa /dev/null +to prevent polluting the release with local system changes. +.It Va MAKE_FLAGS +Additional flags to pass to +.Xr make 1 . +.It Va WORLD_FLAGS +Additional flags to pass to +.Xr make 1 +during the +.Dq buildworld +phase. +Defaults to setting the number of +.Xr make 1 +jobs +.Pq Ar -j +to the number of CPUs available on the system. +.It Va KERNEL_FLAGS +Additional flags to pass to +.Xr make 1 +during the +.Dq buildkernel +phase. +Defaults to setting the number of +.Xr make 1 +jobs +.Pq Ar -j +to half the number of CPUs available on the 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 +Set to a non-empty value to skip the +.Li ports/ +tree checkout. +When set, +.Va NOPORTS +will prevent the +.Fa ports.txz +distribution package from being created. +Setting this also sets +.Va NODOC . .El .Sh MAKEFILE TARGETS The release makefile @@ -175,18 +284,19 @@ This may require the (memory disk) device driver be present in the kernel (either by being compiled in or available as a module). This target produces files called -.Pa release.iso +.Pa disc1.iso and .Pa bootonly.iso as its output. .It Cm memstick Builds an installation memory stick image named -.Pa memstick . +.Pa memstick.img . Not applicable on all platforms. Requires that the .Xr md 4 -(memory disk) device driver be present in the kernel -(either by being compiled in or available as a module). +.Pq memory disk +device driver be present in the kernel +.Pq either by being compiled in or available as a module . .It Cm ftp Creates a directory named .Pa ftp @@ -197,7 +307,8 @@ and suitable for upload to an FTP mirror Major subtargets called by targets above: .Bl -tag -width ".Cm packagesystem" .It Cm packagesystem -Generates all the distribution archives (e.g. base, kernel, ports, doc) +Generates all the distribution archives +.Pq base, kernel, ports, doc applicable on this platform. .It Cm system Builds a bootable installation system containing all the distribution files @@ -211,8 +322,9 @@ targets. .It Cm reldoc Builds the release documentation. This includes the release notes, -hardware guide, and installation instructions. Other documentation (e.g. -the Handbook) is built during the +hardware guide, and installation instructions. +Other documentation, such as the Handbook, +is built during the .Cm base.txz target invoked by .Cm packagesystem . @@ -221,20 +333,24 @@ target invoked by Optional variables: .Bl -tag -width ".Ev TARGET_ARCH" .It Ev OSRELEASE -Optional base name for generated media images (e.g. FreeBSD-9.0-RC2-amd64). +Optional base name for generated media images +.Pq e.g., FreeBSD-9.0-RC2-amd64 . Defaults to the output of .Ic `uname -s`-`uname -r`-`uname -p` within the chroot. .It Ev WORLDDIR -Location of a directory containing the src tree. By default, the directory +Location of a directory containing the src tree. +By default, the directory above the one containing the makefile .Pq Pa src . .It Ev PORTSDIR -Location of a directory containing the ports tree. By default, +Location of a directory containing the ports tree. +By default, .Pa /usr/ports . 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, +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 @@ -291,7 +407,8 @@ Typically, one only needs to set .It Pa /usr/src/Makefile .It Pa /usr/src/Makefile.inc1 .It Pa /usr/src/release/Makefile -.It Pa /usr/src/release/generate-release.sh +.It Pa /usr/src/release/release.sh +.It Pa /usr/src/release/release.conf.sample .El .Sh EXAMPLES The following sequence of commands can be used to build a @@ -316,12 +433,27 @@ The following sequence of commands can b in a clean environment, including ports and documentation: .Bd -literal -offset indent cd /usr/src/release -sh generate-release.sh head /local3/release +sh release.sh +.Ed +.Pp +Optionally, a configuration file can be used customize the release build, +such as the subversion revision to use, the branch of the subversion tree for +.Li src/ , +.Li ports/ , +and +.Li doc/ . +.Bd -literal -offset indent +cd /usr/src/release +sh release.sh -c $HOME/release.conf .Ed .Pp After running these commands, all prepared release files are available in the -.Pa /local3/release/R +.Pa /scratch directory. +The target directory can be changed by specifying the +.Va CHROOTDIR +variable in +.Li release.conf . .Sh SEE ALSO .Xr cc 1 , .Xr install 1 , @@ -372,6 +504,16 @@ was overhauled and the wrapper script .Pa src/release/generate-release.sh introduced to support the introduction of a new installer. .Pp +For the +.Fx 9.2 +release, +.Pa src/release/release.sh +was introduced to support per-build configuration files. +.Pa src/release/release.sh +is heavily based on the +.Pa src/release/generate-release.sh +script. +.Pp At near 1000 revisions spread over multiple branches, the .Xr svn 1 log of @@ -386,5 +528,22 @@ was originally written by .An Jordan Hubbard , and .An Poul-Henning Kamp . -This manual page was written by +.Pp +This manual page was originally written by .An Murray Stokely Aq murray@FreeBSD.org . +.Pp +It was updated by +.An Nathan Whitehorn Aq nwhitehorn@FreeBSD.org +to include the +.Fa generate-release.sh +script used for the +.Fx 9.0 +release cycle. +.Pp +It was later updated by +.An Glen Barber Aq gjb@FreeBSD.org +to include the +.Fa release.sh +script used for the +.Fx 9.2 +release cycle.