1.\" $OpenBSD: release.8,v 1.64 2011/04/18 16:52:12 thib Exp $ 2.\" 3.\" Copyright (c) 2000 Marco S. Hyman 4.\" 5.\" Permission to copy all or part of this material for any purpose is 6.\" granted provided that the above copyright notice and this paragraph 7.\" are duplicated in all copies. THIS SOFTWARE IS PROVIDED ``AS IS'' 8.\" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT 9.\" LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS 10.\" FOR A PARTICULAR PURPOSE. 11.\" 12.Dd $Mdocdate: April 18 2011 $ 13.Dt RELEASE 8 14.Os 15.Sh NAME 16.Nm release 17.Nd building an 18.Ox 19release 20.Sh DESCRIPTION 21There are several steps necessary to build a system release. 22They are: 23.Pp 24.Bl -enum -compact -offset indent 25.It 26Update sources. 27.It 28Build and install a new kernel. 29.It 30Build a new system. 31.It 32Make and validate the system release. 33.It 34Build and install xenocara. 35.It 36Make and validate the xenocara release. 37.It 38Make the third party packages. 39.El 40.Pp 41The following sections describe each of the required steps in detail. 42.Pp 43Commands to be run as a user with write permissions on the source and 44ports trees 45.Pf ( Ns Pa /usr/src 46and 47.Pa /usr/ports 48respectively) 49are preceded by a dollar sign 50.Pq Sq $ . 51Commands that must be run as the superuser are preceded by a hash mark 52.Pq Sq # . 53.Ss 1. Update sources 54A 55.Nm 56should always start from a known set of 57.Em coherent 58sources. 59The easiest way to ensure that the sources are complete and coherent 60is to check them out using the 61.Tn CVS 62tag the 63.Ox 64developers add to the repository prior to making a release. 65There are two tags, one which identifies the release as it exists on the 66.Tn CD-ROM 67and another which identifies the 68.Em stable 69branch. 70The 71.Em stable 72branch, starting with 73.Ox 2.7 , 74contains the patches described in 75.Pa http://www.openbsd.org/errata.html . 76The tags are of the form: 77.Bl -tag -width OPENBSD_x_y_BASE 78.It Va OPENBSD_x_y_BASE 79This tag marks the source as it exists on the release 80.Tn CD-ROM 81where 82.Ar x 83is the major release number and 84.Ar y 85is the minor release number. 86.It Va OPENBSD_x_y 87This tag is a moving target. 88It marks the sources that belong to the stable branch. 89This branch 90.Em only 91contains errata, no new features. 92.El 93.Pp 94To update your sources to the versions identified by one of the above 95tags use the commands: 96.Bd -literal -offset indent 97$ cd /usr/src && cvs up -r TAG -Pd 98$ cd XSRCDIR && cvs up -r TAG -Pd 99$ cd PORTSPATH && cvs up -r TAG -Pd 100.Ed 101.Pp 102Replace 103.Va XSRCDIR 104with the path to your X Window System sources. 105Replace 106.Va PORTSPATH 107with the path to your ports tree sources, typically 108.Pa /usr/ports . 109The above commands assume an existing source tree. 110.Pp 111See 112.Pa http://www.openbsd.org/anoncvs.html 113for instructions on fetching the sources for the first time. 114.Pp 115.Sy Warning : 116.Tn CVS 117tags are 118.Sq sticky . 119See 120.Xr cvs 1 121for more information. 122.Ss 2. Build and install a new kernel 123For safety, you should always build and install a new kernel before 124building the programs that will use the kernel. 125This ensures that any new system calls, for example, will be present 126when needed. 127To build a kernel the steps are: 128.Pp 129Change the current working directory. 130.Va ${ARCH} 131is the architecture of your machine, e.g.\& 132.Li i386 . 133.Pp 134.Dl $ cd /sys/arch/${ARCH}/conf 135.Pp 136Edit the kernel configuration file. 137.Va ${NAME} 138is your kernel configuration file. 139You should 140.Em not 141edit 142.Li GENERIC ; 143create your own kernel configuration if you need to make modifications. 144If using 145.Li GENERIC 146you can skip this step. 147And yes, you may use 148.Xr vi 1 , 149.Xr mg 1 , 150or any other editor you choose. 151.Pp 152.Dl $ vi ${NAME} 153.Pp 154Build the kernel compilation directory and compile the kernel: 155.Bd -literal -offset indent 156$ config ${NAME} 157$ cd ../compile/${NAME} 158$ make clean && make 159.Ed 160.Pp 161(In this instance 162.Li "make clean" 163is your friend.) 164.Pp 165Replace the old kernel and reboot. 166The current kernel is copied to 167.Pa /obsd 168and the new kernel to 169.Pa /bsd . 170.Bd -literal -offset indent 171$ su 172# make install 173# shutdown -r now 174.Ed 175.Pp 176If the system does not come up you can boot using 177.Pa /obsd . 178.Ss 3. Build a new system 179Now that you are running your new kernel you can build a new system. 180It's safer (but slower) to remove your object directories and re-create 181them before the build. 182The steps are: 183.Pp 184Move all your existing object files out of the way and then remove 185them in the background: 186.Bd -literal -offset indent 187$ cd /usr/obj && mkdir -p .old && sudo mv * .old && \e 188 sudo rm -rf .old & 189.Ed 190.Pp 191Re-build your obj directories: 192.Pp 193.Dl $ cd /usr/src && make obj 194.Pp 195Create directories that might be missing: 196.Pp 197.Dl $ cd /usr/src/etc && env DESTDIR=/ sudo make distrib-dirs 198.Pp 199Begin the build: 200.Pp 201.Dl $ cd /usr/src && make SUDO=sudo build 202.Pp 203Update 204.Pa /etc , 205.Pa /var , 206and 207.Pa /dev/MAKEDEV , 208either by hand or using 209.Xr sysmerge 8 . 210.Pp 211At this point your system is up-to-date and running the code that you 212are going to make into a release. 213.Ss 4. Make and validate the system release 214The system release consists of at least one generic kernel, 215some installation media, the release 216.Sq tarballs , 217installation instructions, and checksum files. 218.Pp 219The release process requires two work areas. 220They are: 221.Bl -tag -width "RELEASEDIR " 222.It Va DESTDIR 223This is the name of a directory which will be the root of a complete 224.Ox 225installation, thus it must be on a disk partition large enough to store the 226entire operating system (less the X Window System and any third party 227.Sq packages ) . 228The directory can be removed once the release is created. 229In any case the release process ensures the directory is empty before starting. 230.It Va RELEASEDIR 231This is the name of a directory where the release output files are stored. 232The following process will create the directory if necessary. 233.It " " 234.Sy Warning : 235.Va DESTDIR 236and 237.Va RELEASEDIR 238must not refer to any directory with 239.Pa /mnt 240in its path, as 241.Pa /mnt 242is used in the release generation process. 243Additionally the first 244.Xr vnd 4 245device, vnd0, 246is also used and must not be configured. 247.El 248.Pp 249The release process is: 250.Pp 251Ensure 252.Va ${DESTDIR} 253exists as an empty directory and 254.Va ${RELEASEDIR} 255exists. 256.Va ${RELEASEDIR} 257need not be empty. 258You must be root to create a release: 259.Bd -literal -offset indent 260$ su 261# export DESTDIR=your-destdir; export RELEASEDIR=your-releasedir 262# test -d ${DESTDIR} && mv ${DESTDIR} ${DESTDIR}- && \e 263 rm -rf ${DESTDIR}- & 264# mkdir -p ${DESTDIR} ${RELEASEDIR} 265.Ed 266.Pp 267Make the release and check that the contents of 268.Va ${DESTDIR} 269pretty much match the contents of the release 270.Sq tarballs : 271.Bd -literal -offset indent 272# cd /usr/src/etc && make release 273# cd /usr/src/distrib/sets && sh checkflist 274# unset RELEASEDIR DESTDIR 275.Ed 276.Pp 277At this point you have most of an 278.Ox 279release. 280The only thing missing is the X Window System 281(which is covered in the next section). 282.Ss 5. Build and install xenocara 283.Va Xenocara 284is based on the X.Org modular build system. 285Xenocara sources are supposed to be in 286.Va XSRCDIR 287which defaults to 288.Pa /usr/xenocara . 289This variable should be set in 290.Xr mk.conf 5 291if a non-default value is used. 292The 293.Pa /usr/src 294tree is also needed while building xenocara. 295The following steps will build and install everything for the first time. 296.Bd -literal -offset indent 297$ su 298# cd XSRCDIR 299# make bootstrap 300# make obj 301# make build 302.Ed 303.Pp 304The X Window System is created and installed in 305.Pa /usr/X11R6 . 306.Ss 6. Make and validate the xenocara release 307.Va xenocara 308uses 309.Va DESTDIR 310and 311.Va RELEASEDIR 312as described above. 313While they may be set to the values used to build the rest of the 314system, be aware that the existing contents of 315.Va DESTDIR 316will be removed as part of the xenocara build (this is necessary for 317release checklist processing). 318.Pp 319The steps to build the release are (assuming you are still root, and still in 320.Va XSRCDIR ) : 321.Bd -literal -offset indent 322# export DESTDIR=your-destdir; export RELEASEDIR=your-releasedir 323# test -d ${DESTDIR} && mv ${DESTDIR} ${DESTDIR}- && \e 324 rm -rf ${DESTDIR}- & 325# mkdir -p ${DESTDIR} ${RELEASEDIR} 326# make release 327# unset RELEASEDIR DESTDIR 328.Ed 329.Pp 330At this point you have both 331.Ox 332system and X Window System 333.Sq tarballs 334in your release directory. 335.Ss 7. Make the third party packages 336The 337.Sq ports 338subsystem of contributed applications is described in 339.Xr ports 7 . 340For ease of installation ports can be pre-compiled into 341.Sq packages 342which can then be installed on multiple machines using 343.Xr pkg_add 1 . 344Packages are created by selecting an application to build 345(we'll call this one CATEGORY/PORT) and then running the following: 346as root: 347.Bd -literal -offset indent 348$ cd /usr/ports/CATEGORY/PORT 349$ su 350# make package 351.Ed 352.Pp 353That's all there is to it. 354.Sh SEE ALSO 355.Xr cvs 1 , 356.Xr pkg_add 1 , 357.Xr ports 7 , 358.Xr sudo 8 , 359.Xr sysmerge 8 360.Sh HISTORY 361This document first appeared in 362.Ox 2.8 . 363