First cut at 'how to make a release' doc. Please read, comment, and

either fix or send corrections

1 files changed, 386 insertions, 0 deletions

diff --git a/share/man/man8/release.8 b/share/man/man8/release.8
new file mode 100644
index 00000000000..1d210f4c89f
--- /dev/null
+++ b/share/man/man8/release.8
@@ -0,0 +1,386 @@
+\.\"	$OpenBSD: release.8,v 1.1 2000/07/07 18:00:58 marc Exp $
+.\"
+.\"	Copyright (c) 2000 Marco S. Hyman
+.\"
+.\"	Permission to copy all or part of this material for any purpose is
+.\"	granted provided that the above copyright notice and this paragraph
+.\"	are duplicated in all copies.  THIS SOFTWARE IS PROVIDED ``AS IS''
+.\"	AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT
+.\"	LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
+.\"	FOR A PARTICULAR PURPOSE.
+.\"
+.Dd July 6, 2000
+.Dt RELEASE 8
+.Os
+.Sh NAME
+.Nm release
+.Nd building an
+.Ox
+release
+.Sh DESCRIPTION
+There are several steps necessary to build a system release.   They are
+.Pp
+.Bl -enum -compact
+.It
+Update sources
+.It
+Build and install a new kernel
+.It
+Build a new system
+.It
+Make and validate the system release
+.It
+Build and install X11
+.It
+Make and validate the X11 release
+.It
+Make the third party packages
+.El
+.Pp
+The following sections describe each of the needed steps in detail.
+.Ss "1. Update sources"
+.Pp
+A release should always start from a known set of
+.Em coherent
+sources.  The easiest way to ensure that the sources are complete
+and coherent is to check the sources out using the
+.Tn CVS
+tag the
+.Ox
+developers add to the repository prior to making a release.   There
+are two tags, one which identifies the release as it exists on the
+.Tn CD\-ROM
+and another which identifes the
+.Em stable
+branch.   The
+.Em stable
+branch, starting with
+.Ox 2.7 ,
+contains the patches described in
+.Pa http://www.openbsd.org/errata.html .
+The tags are of the form:
+.Bl -tag -width OPENBSD_x_y_BASE
+.It Pa OPENBSD_x_y_BASE
+This tag marks the source as it exists on the release
+.Tn CD\-ROM
+where
+.Pa x
+is the major release number and
+.Pa y
+is the minor release number.
+.It Pa OPENBSD_x_y
+This tag is a moving target.  It marks the sources that belong to the
+stable branch.   This branch
+.Em only
+contains errata, no new features.
+.El
+To update your sources to the versions identified by one of the above
+tags use the commands:
+.Pp
+.Bl -bullet -compact -offset indent
+.It
+.Li "cd /usr/src && cvs up -r TAG -Pd"
+.It
+.Li "cd X11SRC && cvs up -r TAG -Pd"
+.It
+.Li "cd PORTSPATH && cvs up -r TAG -Pd"
+.El
+.Pp
+Replace
+.Pa X11SRC
+with the path to your
+.Tn X11R6
+sources.  Replace
+$PORTSPATH
+with the path to your ports tree sources, typically
+.Pa /usr/ports .
+The above command assume an existing source tree.   See
+.Pa http://www.openbsd.org/anoncvs.html
+for instructions on fetching the sources for the first time.
+.Bd -offset indent
+.Sy Warning :
+.Tn CVS
+tags are
+.Sq sticky .
+See
+.Xr cvs 1
+for more information.
+.Ed
+.Ss "2. Build and install a new kernel"
+.Pp
+For safety, you should 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.
+To build a kernel the steps are:
+.Pp
+.Bl -bullet -compact -offset indent
+.It
+.Li "cd /sys/arch/${ARCH}/conf"
+.br
+where
+.Va ${ARCH}
+is the architecture of your machine, e.g.
+.Li i386 .
+.It
+.Li "vi ${NAME}"
+.br
+where
+.Va ${NAME}
+is your kernel config file.   You should
+.Em not
+edit
+.Li GENERIC ,
+create your own kernel configuration if you need to make modifiations.
+If using
+.Li GENERIC
+you can skip this step.  And yes, you may use
+.Li emacs
+or any other editor you choose.
+.It
+.Li "config ${NAME}"
+.It
+.Li "cd ../compile/${NAME}"
+.It
+.Li "make clean && make depend && make"
+.br
+In this instance
+.Li "make clean"
+is your friend.
+.It
+.Li su
+.It
+.Li "mv /bsd /bsd.old && mv bsd / && chown root.wheel /bsd"
+.It
+.Li "sync; sync; reboot"
+.br
+You can also use
+.Bd -literal -compact -offset indent
+shutdown -r now
+.Ed
+.br
+for a more orderly shutdown if you're not in a hurry.
+.El
+.Pp
+If the system does not come up you can boot using
+.Pa bsd.old .
+.Ss "3. Build a new system"
+.Pp
+Now that you are running using your new kernel you can build a new system.
+It's safer (but slower) to remove and re-build your object directories
+and re-building them before the build.   The steps are:
+.Pp
+.Bl -bullet -compact -offset indent
+.It
+.Li "cd /usr/obj && mkdir -p .old && sudo mv * .old && sudo rm -rf .old &"
+.br
+This moves all your existing object out of the way and then removes them in
+the background.
+.It
+.Li "cd /usr/src && nice make obj"
+.br
+this re-builds your obj directories
+.It
+.Li su
+.It
+.Li "nice make build"
+.br
+If you've
+.Xr sudo 8
+set up you can combine this with the previous step using the command
+.Bd -literal -compact -offset indent
+nice make SUDO=sudo build
+.Ed
+.It
+Update
+.Pa /etc ,
+.Pa /var ,
+and
+.Pa /dev/MAKEDEV
+by hand.
+.El
+.Pp
+At this point your system is up-to-date and running the code that you
+are going to make into a release.
+.Ss "4. Make and validate the system release"
+.Pp
+The system release consist of a generic kernel, one
+.Tn CD\-ROM
+and two floppy bootable filesystems, the release
+.Sq tarballs ,
+installation instructions, and checksum files.
+.Pp
+The release process requires two work areas.  They are:
+.Bl -tag -width "RELEASEDIR "
+.It Pa DESTDIR
+This is the name of a directory which will be the root of a a complete
+.Ox
+installation, thus it must be on a disk partition large enough to
+store the entire operating system (less
+.Tn X11R6
+and any third party
+.Sq packages ) .
+The directory can be removed once the release is created.  In any case the
+release process ensures the directory is empty before starting.
+.It Pa RELEASEDIR
+This is the name of a directory where the release output files are
+stored.   The following process will create the directory if necessary.
+.El
+.Pp
+The floppy and
+.Tn CD\-ROM
+.Pa RAMDISK
+images require a special tool which is created first.   The release process
+is:
+.Bl -bullet -compact -offset indent
+.It
+.Li su
+.br
+you must be root to create a release
+.It
+.Li "cd /usr/src/distrib/crunch && make clean && make && make install"
+.br
+create the special tools needed to build the release
+.It
+.Li "export DESTDIR=your-destdir RELEASEDIR=your-releasedir"
+.It
+.Li "test -d ${DESTDIR} && mv ${DESTDIR} ${DESTDIR}- && rm -rf ${DESTDIR}- &"
+.It
+.Li "mkdir -p ${DESTDIR} ${RELEASEDIR}"
+.br
+these two steps ensure
+.Pa ${DESTDIR}
+exists an empty directory and
+.Pa ${RELEASEDIR}
+exists.
+.It
+.Li "cd /usr/src/etc && nice make release"
+.It
+.Li "cd /usr/src/distrib/sets && csh checkflist"
+.br
+this checks that the contents of
+.Pa ${DESTDIR}
+pretty much match the contents of the release
+.Sq tarballs .
+.It
+.Li "unset RELEASEDIR DESTDIR"
+.El
+.Pp
+At this point you have most of an
+.Ox
+release.   The only thing missing is
+.Pa X11R6
+(which is covered in the next section).
+.Ss "5. Build and install X11"
+.Pp
+The
+.Pa X11
+tree is primarily
+.Pa imake
+based and doesn't contain the
+.Pa obj
+directory mechanism that comes with Berkeley
+.Pa make .
+While the tree can be built in place, it's better to refrain from
+poluting the cvs sources.  An alternate build location needs to
+be selected, large enough to hold the
+.Tn X11R6
+object files, libraries, and binaries.  Call this location
+.Pa X11BLD .
+.Pa X11SRC
+is the path to your
+.Pa X11R6
+sources.  Once you've selected
+.Pa X11BLD the build process is:
+.Pp
+.Bl -bullet -compact -offset indent
+.It
+.Li su
+.It
+.Li "test -d X11BLD && mv X11BLD X11BLD- && rm -rf X11BLD- &"
+.It
+.Li "mkdir -p /usr2/X11"
+.It
+.Li "cd X11BLD && lndir X11SRC && nice make build"
+.El
+.Pp
+Once the build is done you've a new
+.Pa X11R6 ...
+almost.  The install phase of the build does
+.Em not
+overwrite
+.Pa /var/X11/xdm .
+That directory must be installed by hand.
+.Ss "6. Make and validate the X11 release"
+.Pp
+.Pa X11R6
+uses the same
+.Pa DESTDIR
+and
+.Pa RELEASEDIR
+mechanism noted in the section on building a system release, above.
+They may be the same values used above, but be warned that the
+contents of
+.Pa DESTDIR
+will be removed.   The steps to build the release are (assuming you
+are still root, and still in
+.Pa X11BLD ) :
+.Pp
+.Bl -bullet -compact -offset indent
+.It
+.Li "export DESTDIR=your-destdir RELEASEDIR=your-releasedir"
+.It
+.Li "test -d ${DESTDIR} && mv ${DESTDIR} ${DESTDIR}- && rm -rf ${DESTDIR}- &"
+.It
+.Li "mkdir -p ${DESTDIR} ${RELEASEDIR}"
+.It
+.Li "nice make release"
+.It
+.Li "unset RELEASEDIR DESTDIR"
+.El
+.Pp
+At this point you have both system and
+.Pa X11R6
+.Sq tarballs
+in your release directory.
+.Ss "7. Make the third party packages"
+.Pp
+The
+.Sq ports
+sub-system of contributed applications is described in
+.Xr ports 7 .  For ease of installation ports can be pre-compiled
+into
+.Sq packages
+which can them be installed onto machines using
+.Xr pkg_add 1 .
+Packages are created by:
+.Pp
+.Bl -bullet -compact -offset indent
+.It
+Select an application to build, we'll call it
+.Pa CATEGORY/PORT .
+.It
+.Li "cd /usr/ports/CATEGORY/PORT"
+.It
+.Li su
+.It
+.Li "make package"
+.El
+.Pp
+That's all there is to it.
+.\".Sh ENVIRONMENT
+.\".Sh FILES
+.\".Sh EXAMPLES
+.\".Sh DIAGNOSTICS
+.Sh SEE ALSO
+.Xr cvs 1 ,
+.Xr pkg_add 1 ,
+.Xr ports 7 ,
+.Xr sudo 8
+.Sh HISTORY
+This document first appeared just after the release of
+.Ox 2.7 .
+.Sh AUTHORS
+Written by Marco S. Hyman using information gleaned from the various
+.Ox
+mailing lists and e-mail conversions with Theo de Raadt, Niklas Hallqvist,
+Todd T. Fries, and Todd C. Miller.