Attached is my proposed diff for /usr/src/share/man/man8/release.8
that adds instructions on how to build the install${VERSION}.{fs,iso}
images. I have incorporated off-list feedback from Theo Buehler in
this diff.
Any feedback would be welcome.
Please find attached an updated diff with some additional off-list
feedback from a second Theo (de Raadt this time). He asked me to clean
up the use of the second person language in this man page as well.
Any other feedback?
Index: release.8
===================================================================
RCS file: /home/cvs/src/share/man/man8/release.8,v
retrieving revision 1.72
diff -u -p -r1.72 release.8
--- release.8 14 Sep 2015 20:06:59 -0000 1.72
+++ release.8 21 Jun 2016 14:22:52 -0000
@@ -34,6 +34,8 @@ Build and install xenocara.
Make and validate the xenocara release.
.It
Make the third party packages.
+.It
+Create boot and installation disk images.
.El
.Pp
The following sections describe each of the required steps in detail.
@@ -89,8 +91,8 @@ This branch
contains errata, no new features.
.El
.Pp
-To update your sources to the versions identified by one of the above
-tags use the commands:
+To update to the versions identified by one of the above tags use
+the commands:
.Bd -literal -offset indent
$ cd /usr/src && cvs up -r TAG -Pd
$ cd XSRCDIR && cvs up -r TAG -Pd
@@ -99,10 +101,10 @@ $ cd PORTSPATH && cvs up -r TAG -Pd
.Pp
Replace
.Va XSRCDIR
-with the path to your X Window System sources.
+with the path to the desired X Window System sources.
Replace
.Va PORTSPATH
-with the path to your ports tree sources, typically
+with the path to the desired ports tree sources, typically
.Pa /usr/ports .
The above commands assume an existing source tree.
.Pp
@@ -118,7 +120,7 @@ See
.Xr cvs 1
for more information.
.Ss 2. Build and install a new kernel
-For safety, you should always build and install a new kernel before
+For safety, always build and install a new kernel before
building the programs that will use the kernel.
This ensures that any new system calls, for example, will be present
when needed.
@@ -126,26 +128,26 @@ To build a kernel the steps are:
.Pp
Change the current working directory.
.Va ${ARCH}
-is the architecture of your machine, e.g.\&
+is the architecture of the machine, e.g.\&
.Li i386 .
.Pp
.Dl $ cd /usr/src/sys/arch/${ARCH}/conf
.Pp
Edit the kernel configuration file.
.Va ${NAME}
-is your kernel configuration file.
-You should
+is the desired kernel configuration file.
+It is
.Em not
-edit
+recommended to edit
.Li GENERIC ;
-create your own kernel configuration if you need to make modifications.
-If using
+instaed create a new kernel configuration if modifications are
+desired. If using
.Li GENERIC
-you can skip this step.
-And yes, you may use
+the following step can be skipped.
+And yes,
.Xr vi 1 ,
.Xr mg 1 ,
-or any other editor you choose.
+or any other text editor can be used.
.Pp
.Dl $ vi ${NAME}
.Pp
@@ -158,7 +160,7 @@ $ make clean && make
.Pp
(In this instance
.Li "make clean"
-is your friend.)
+is one's friend.)
.Pp
Replace the old kernel and reboot.
The current kernel is copied to
@@ -171,22 +173,22 @@ $ su
# shutdown -r now
.Ed
.Pp
-If the system does not come up you can boot using
+If the system does not come up, it can be booted using
.Pa /obsd .
.Ss 3. Build a new system
-Now that you are running your new kernel you can build a new system.
-It's safer (but slower) to remove your object directories and re-create
+Now that the new kernel is running, it is time to build a new system.
+It's safer (but slower) to remove the object directories and re-create
them before the build.
The steps are:
.Pp
-Move all your existing object files out of the way and then remove
+Move all existing object files out of the way and then remove
them in the background:
.Bd -literal -offset indent
$ cd /usr/obj && mkdir -p .old && doas mv * .old && \e
doas rm -rf .old &
.Ed
.Pp
-Re-build your obj directories:
+Re-build the local obj directories:
.Pp
.Dl $ cd /usr/src && make obj
.Pp
@@ -206,8 +208,8 @@ and
either by hand or using
.Xr sysmerge 8 .
.Pp
-At this point your system is up-to-date and running the code that you
-are going to make into a release.
+At this point the system is up-to-date and running the code that
+will be used to make into a release.
.Ss 4. Make and validate the system release
The system release consists of at least one generic kernel,
some installation media, the release
@@ -253,10 +255,10 @@ exists as an empty directory and
exists.
.Va ${RELEASEDIR}
need not be empty.
-You must be root to create a release:
+It is required to be logged in as root to create a release:
.Bd -literal -offset indent
$ su
-# export DESTDIR=your-destdir; export RELEASEDIR=your-releasedir
+# export DESTDIR=the-destdir; export RELEASEDIR=the-releasedir
# test -d ${DESTDIR} && mv ${DESTDIR} ${DESTDIR}- && \e
rm -rf ${DESTDIR}- &
# mkdir -p ${DESTDIR} ${RELEASEDIR}
@@ -272,10 +274,10 @@ pretty much match the contents of the re
# unset RELEASEDIR DESTDIR
.Ed
.Pp
-At this point you have most of an
+At this point most of n
.Ox
-release.
-The only thing missing is the X Window System
+release has been built.
+The only missing piece is the X Window System
(which is covered in the next section).
.Ss 5. Build and install xenocara
.Va Xenocara
@@ -314,10 +316,11 @@ system, be aware that the existing conte
will be removed as part of the xenocara build (this is necessary for
release checklist processing).
.Pp
-The steps to build the release are (assuming you are still root, and still in
+The steps to build the release are (this assumes the user is
+still root, and still in
.Va XSRCDIR ) :
.Bd -literal -offset indent
-# export DESTDIR=your-destdir; export RELEASEDIR=your-releasedir
+# export DESTDIR=the-destdir; export RELEASEDIR=the-releasedir
# test -d ${DESTDIR} && mv ${DESTDIR} ${DESTDIR}- && \e
rm -rf ${DESTDIR}- &
# mkdir -p ${DESTDIR} ${RELEASEDIR}
@@ -325,11 +328,11 @@ The steps to build the release are (assu
# unset RELEASEDIR DESTDIR
.Ed
.Pp
-At this point you have both
+At this point both the
.Ox
system and X Window System
.Sq tarballs
-in your release directory.
+are present in the local release directory.
.Ss 7. Make the third party packages
The
.Sq ports
@@ -338,6 +341,30 @@ subsystem of contributed applications is
for installation, either individually or in bulk.
This is described in
.Xr ports 7 .
+.Ss 8. Create boot and installation disk images
+.Pp
+At this point,
+.Va RELEASEDIR
+contains the
+.Ox
+.Sq tarballs
+necessary to install the system by hand or upgrade an existing system.
+.Pp
+The following steps will create the boot and installation images
+install${VERSION}.{fs,iso} suitable for installs without network
+connectivity. These images contain the
+.Sq tarballs
+and ports built in the previous steps.
+.Bd -literal -offset indent
+# export RELDIR=the-releasedir
+# export RELXDIR=the-xenocara-releasedir
+# cd /usr/src/distrib/${ARCH}/iso && make
+# make install
+# unset RELDIR RELXDIR
+.Ed
+.Pp
+The two installer images are now stored in the local release
+directory.
.Sh SEE ALSO
.Xr cvs 1 ,
.Xr doas 1 ,
