Date: Mon, 6 Sep 2004 14:27:30 -0400 From: Len Zettel <zettel@acm.org> To: freebsd-doc@freebsd.org Cc: freebsd-current@freebsd.org Subject: Re: RFC: 5.3 Migration Guide Message-ID: <200409061427.30634.zettel@acm.org> In-Reply-To: <1094426835.767.50.camel@localhost> References: <1094426835.767.50.camel@localhost>
next in thread | previous in thread | raw e-mail | index | archive | help
--Boundary-00=_SwKPBJAGFNOId5W Content-Type: text/plain; charset="iso-8859-1" Content-Transfer-Encoding: 7bit Content-Disposition: inline On Sunday 05 September 2004 07:27 pm, Bruce A. Mah wrote: > Howdy-- > > I've volunteered to rework the 5.X Early Adopters Guide into a Migration > Guide. The focus of this document is less about discouraging unwary > users and more about what kinds of changes users might encounter when > they move from 4.X to 5.X. > > I'd like to solicit a pre-commit review on the document at: > > http://people.freebsd.org/~bmah/pub/article.html > OK, you asked :-). Attached are suggested cosmetic changes to the English. If this is premature, my apologies to all for wasting the bandwidth. -LenZ- > A PDF rendering, as well as SGML source, also live in the same > directory. > > The area I'm the most shaky on is the source upgrade procedure, which is > basically an annotated version of the procedure in src/UPDATING. I > haven't done this procedure in a *long* time, and I'm kind of short on > scratch systems (=> none) at the moment for testing the procedure. In > retrospect, I didn't actually plan on including this section, and I > might have been less eager to take on this task if I'd know it was > coming. :-) > > trhodes and scottl provided some helpful feedback on an earlier draft of > this document. > > Thanks for any comments... > > Bruce. > > PS. This document will basically replace the EAG for 5.3. On HEAD, we > should probably disable or kill the EAG. It's served its purpose (I > think) and when it comes back in time for 6.0, it probably won't bear > much resemblance to its current incarnation. --Boundary-00=_SwKPBJAGFNOId5W Content-Type: text/x-diff; charset="iso-8859-1"; name="article.diff" Content-Transfer-Encoding: 7bit Content-Disposition: attachment; filename="article.diff" --- article.sgml Mon Sep 6 14:00:00 2004 +++ changed_article.sgml Mon Sep 6 13:58:03 2004 @@ -62,42 +62,42 @@ <title>Introduction</title> <para>&os; &release.5branchpoint; marks the beginning of a new - <quote>&os.stable;</quote> series of releases. From this point - forward, releases in the &release.5x; series will be targeted - towards production usage, in much the same way as the prior + <quote>&os.stable;</quote> series of releases. After this, + releases in the &release.5x; series will be targeted + towards production usage in much the same way as the prior &release.4x; series of releases.</para> - <para>This article addresses a number of topics and issues that - are of interest to users updating from a &release.4x; release to + <para>This article addresses a number of topics and issues + of interest to users updating from a &release.4x; release to &release.5branchpoint;. It begins with a brief overview of current release engineering practices and then describes some of the new features available with the &os; &release.5x; series. - Perhaps the most crucial section of this document lists issues + Perhaps the most important section lists issues where major changes have taken place, user-visible behavior has changed, or external software interfaces have been modified. Last are some notes on upgrading existing &os; &release.4x; - systems to &os; &release.5branchpoint;, both from binaries or - source.</para> + systems to &os; &release.5branchpoint;, from binaries or + from source.</para> </sect1> <sect1 id="release-overview"> <title>An Overview of the &os; Release Process</title> - <para>&os; employs a model of development that relies on multiple - development branches within the source code repository. The main branch is called + <para>&os; employs a development model relying on multiple + branches within the source code repository. The main branch is called <quote>CURRENT</quote>, and is referred to in the CVS repository with the <literal>HEAD</literal> tag. New features are - committed first to this branch; although this means that CURRENT - is the first to see new functionality, it also means that it + committed first to this branch; although CURRENT + is the first to see new functionality, it also occasionally suffers from breakages as new features are added and debugged.</para> <para>Most &os; releases are made from one of several - <quote>STABLE</quote> branches. Features are only added to - these branches after some amount of testing in CURRENT. For the + <quote>STABLE</quote> branches. Features are added to + these branches omly after some amount of testing in CURRENT. For the past two years, - the only STABLE branch was under active development + the only STABLE branch under active development was known as <quote>4-STABLE</quote>, and all of the &os; &release.4x; releases were based on it. This branch has the tag <literal>RELENG_4</literal> in the @@ -115,12 +115,12 @@ (specifically, during the 5.3 release cycle). This delay gave time for the development team to complete needed architectural changes, stabilize the system, finalize various interfaces, and - in general create a good starting point for the remaining + create a good starting point for the remaining &release.5x; releases.</para> <para>Aside from general improvements and bug fixes, a major - priority for development on the 5-STABLE development branch is - the preservation of ABI/API compatibility. Any changes that + priority on the 5-STABLE development branch is + the preservation of ABI (Application Binary Interface)/API (Application Program Interface) compatibility. Any changes that could break backward compatibility (including kernel or library interfaces) are strongly discouraged, and will not be permitted except as a last-resort solution to a critical problem.</para> @@ -128,19 +128,20 @@ <para>The past two stable branches (3-STABLE and 4-STABLE) were created very soon after their respective <quote>dot-oh</quote> releases (their branchpoints were 3.1 and 4.0, respectively). In hindsight, this - practice did not give sufficient time for either CURRENT + did not give sufficient time for either CURRENT to stabilize before the new branches were created. This in turn resulted in wasted effort porting bug - fixes between branches, as well as some architectural changes + fixes between branches, as well as creating some architectural changes that could not be ported between branches at all.</para> <para>The next release from CURRENT will likely be 6.0-RELEASE, - created from CVS <literal>HEAD</literal>. As of the 5.3 release - date, there is no firm date for 6.0, although this release is + created from CVS <literal>HEAD</literal>. There is no firm date for 6.0, + as of the 5.3 release + date, although it is expected sometime in 2006.</para> <para>A limited amount of development will continue on the - 4-STABLE development branch. At least one more release (4.11) is + 4-STABLE development branch, with at least one more release (4.11) planned at some point after 5.3-RELEASE. For especially conservative users, it may be reasonable to continue using the &release.4x; releases for a time. The @@ -164,7 +165,7 @@ <para>A large attraction of &os; &release.5x; is a number of new features, generally involving - large architectural changes that were not feasible to port back to + large architectural changes it was not feasible to port back to the &os; 4-STABLE development branch. (By contrast, many self-contained enhancements, such as new device drivers or userland utilities, have already been ported.) A brief, but not @@ -173,7 +174,7 @@ <itemizedlist> <listitem> <para>SMPng: The <quote>next generation</quote> support for - SMP machines (work in progress). + SMP (Shared Memory Multiprocessor) machines (work in progress). Ongoing work aims to perform fine-grained locking of various kernel subsystems to increase the number of threads of execution that can be running in the kernel. Particular @@ -216,7 +217,7 @@ <listitem> <para>GEOM: A flexible, modular framework for transformation of disk I/O requests. This system supports a number of features - related to disks and volumes, such as: Recognition of disk + related to disks and volumes, including: Recognition of disk partitions, the &man.gbde.4; disk encryption facility, various levels of RAID functionality, network export of disk devices (with &man.ggated.8 and related utilities), and @@ -233,7 +234,7 @@ <para>UFS2: A new UFS2 on-disk format has been added, which supports extended per-file attributes and larger file sizes. UFS2 is now the default format for &man.newfs.8;. - On all platforms except for pc98, filesystems created from + On all platforms except pc98, filesystems created from within &man.sysinstall.8; will use UFS2 by default.</para> </listitem> @@ -248,7 +249,7 @@ <listitem> <para>New hardware support: Support for more hardware devices, such as Cardbus and Bluetooth devices and IEEE 802.11a/b/g - network interfaces based on Atheros chipsets. In addition, + network interfaces based on Atheros chipsets. Also, on the i386 architecture, some network devices not explicitly supported by &os; drivers may be supported using vendor drivers for µsoft; &windows; and the @@ -265,10 +266,10 @@ <title>Notable Changes</title> <para>Some of the differences between &os; &release.4x; and - &release.5x; deserve some special mention, because they involve + &release.5x; deserve special mention because they involve major architectural changes, or break backwards compatibility in some way. While these changes are unlikely to cause a loss of - data, they may cause some confusion for the unwary. Some + data, they could cause some confusion for the unwary. Some notable examples are:</para> <itemizedlist> @@ -277,9 +278,9 @@ <listitem> <para>Several parts of &os;'s base system functionality have - been removed to the &os; Ports Collection, typically because + been moved to the &os; Ports Collection, usually because they are easier to maintain in that form or because they - were not really found to be essential parts of the system. + were not really essential parts of the system. The most noticeable example of this is <application>Perl</application> (available in the &os; Ports Collection as <filename @@ -301,21 +302,22 @@ <!-- Kernel ABI changes --> <listitem> - <para>Because of changes in kernel data structures and - ABIs/APIs, many third-party binary device drivers require - modifications to work correctly under &os; &release.5x;. In + <para>Changes in kernel data structures and APBs/APIs meant + many third-party binary device drivers had to be modified before they would + work correctly under &os; &release.5x; + In some (hopefully rare) cases, user-visible data structures - have changed, requiring recompiling of applications or - reinstallation of ports/packages. As with the case for the + have changed, requiring recompilation of applications or + reinstallation of ports/packages. As with the &release.4x; release train, the &os; development team has - made it a goal not to allow incompatible changes in future + the goal of not to allowing incompatible changes in future releases on the &release.5x; branch.</para> </listitem> <listitem> - <para>Some parts of the &os; base system have fallen into a - state of disrepair due to a lack of users and maintainers. - These have been removed. Specific examples include the + <para>A shortage of users and maintainers caused some parts of the &os; + base system to fall into disrepair. + These have been removed. Examples include the generation of <filename>a.out</filename>-style executables, <footnote> <para>Note that execution of <filename>a.out</filename> @@ -332,18 +334,17 @@ <listitem> <para>On the i386 and pc98 platforms, a <application>UserConfig</application> utility - exists on &release.4x; to allow boot-time configuration of + exists on &release.4x; allowing boot-time configuration of ISA devices when booting from installation media. Under &os; &release.5x;, this functionality has been replaced in - part by the &man.device.hints.5; mechanism (it allows - specifying the same parameters, but with a very different + part by the &man.device.hints.5; mechanism (the same parameters, can be specified, but with a very different interface).</para> </listitem> <listitem> <para><filename>MAKEDEV</filename> is no longer available, nor is it required. FreeBSD &release.5x; uses a device - filesystem, which automatically creates device nodes on + filesystem, automatically creating device nodes on demand. More information can be found in the &man.devfs.5; manual page.</para> </listitem> @@ -354,7 +355,7 @@ it is also the default for file systems created using the disk labeling screen within &man.sysinstall.8;. Because &os; &release.4x; only understands UFS1 (not UFS2), disk - partitions that need to be accessed by both &release.5x; and + partitions that must be accessed by both &release.5x; and &release.4x; must be created with UFS1. This can be specified using the <option>-O1</option> option to &man.newfs.8;, or on the disk labeling screen in @@ -368,27 +369,25 @@ <!-- Userland --> <listitem> - <para>Due to the upgraded <application>GCC</application> - compiler, C++ programs generally need to be recompiled and - reinstalled. This requirement comes from changes in the C++ - ABI.</para> + <para>Changes in the C++ ABI in the upgraded <application>GCC</application> + generally require that C++ programs be recompiled and + reinstalled. </listitem> <listitem> - <para>With the exception of C++ programs described above, it + <para>With the exception of C++ programs as described above, it is generally possible to run old &release.4x; executables - under &release.5x;, but this requires the - <filename>compat4x</filename> distribution to be installed + under &release.5x;, if the + <filename>compat4x</filename> distribution is installed (this distribution can also be installed with the <filename role="package">misc/compat4x</filename> port or package). - This statement extends to the case of ports and packages as - well, although there are a number of known cases of backward - incompatibility. As an example, the <filename + This extends to ports and packages, although there a number of cases of backward + incompatibility are known. As an example,changes in the <literal>statfs</literal> + structure require the recompilation of the <filename role="package">devel/gnomevfs2</filename>, <filename role="package">mail/postfix</filename>, and <filename - role="package">security/cfs</filename> ports need to be - recompiled due to changes in the <literal>statfs</literal> - structure.</para> + role="package">security/cfs</filename> ports. + </para> </listitem> <!-- Ports --> @@ -396,10 +395,10 @@ <listitem> <para>The <application>&xorg;</application> implementation of the X Window System is the default for &os; &release.5x; - beginning with 5.3-RELEASE. As of this writing, + beginning with 5.3-RELEASE. At this writing, <application>&xfree86;</application> remains the default for &os; &release.4x;. More information on the differences - between these different versions, as well as upgrade + between these versions, as well as upgrade information for existing systems, can be found in the <ulink url="&url.books.handbook;/x11.html">The X Window System</ulink> chapter in the &os; Handbook.</para> @@ -446,9 +445,9 @@ advantage of new functionality (most notably, the UFS2 defaults).</para> - <para>As of this writing, the binary upgrade option in + <para>At this writing, the binary upgrade option in &man.sysinstall.8; has not been well-tested for - cross-major-version upgrades. Using this feature is not + cross-major-version upgrades. Use of this feature is not recommended.</para> <para>Several changes may be of interest to those users @@ -456,18 +455,18 @@ Installation floppies (on platforms that support them, such i386 and pc98), are organized somewhat differently than on prior releases. On &release.4x; releases, the floppy set - contained a stripped-down kernel that contained - enough functionality to install the system. This arrangement - was necessary to allow the kernel to fit on a single floppy - disk, but the kernel lacked the device drivers required by - certain hardware configurations. Beginning with &os; + contained a stripped-down kernel with + enough functionality to install the system. This + allowed the kernel to fit on a single floppy + disk, but it lacked the device drivers required by + some hardware configurations. Beginning with &os; 5.3-RELEASE, the installation floppies contain a standard <literal>GENERIC</literal> kernel segmented across multiple - disks. This kernel has a much more complete set of drivers + disks. it has a much more complete set of drivers and features. The boot loader prompts for the insertion of additional disks as required. Users downloading floppy images - (perhaps to perform a network-based installation) should take - note of the fact the the floppy disk set now includes three + (perhaps to perform a network-based installation) should + note that the the floppy disk set now includes three disks: <filename>boot.flp</filename>, <filename>kern1.flp</filename>, and <filename>kern2.flp</filename>.</para> @@ -475,9 +474,8 @@ <para>CDROM-based installations on the i386 architecture now use a <quote>no-emulation</quote> boot loader. This allows, among other things, the use of a <literal>GENERIC</literal> kernel, - rather than the stripped-down kernels used on the floppy - images in previous versions. In - general, any system capable of booting the µsoft; + rather than the stripped-down kernels of floppy + images of previous versions. Generally,any system that can boot the µsoft; &windowsnt; 4, &windows2k;, or &windowsxp; installation CDROMs should be able to boot the &os; &release.5x; CDROMs.</para> @@ -487,42 +485,41 @@ <title>Source Upgrades</title> <note> - <para>In general, many users and developers have found it easier + <para>Many users and developers have found it easier to backup all their data and configuration files (a wise precaution in any case), perform a binary installation - (such as from CDROM), and restore their data. Compared to a - source upgrade, the binary upgrade removes the need to deal - with leftover files and programs on the disk, and allows the - system to take advantage of new filesystem features such as the - UFS2 filesystem layout.</para> + (such as from CDROM), and restore their data. This allows + the system to take advantage of new files systems features + like the UFS2 filesystem layout. Unlike a source upgrade, + there is no need to deal with leftover files and programs + on the disk.</para> <para>Users unfamiliar with the <literal>buildworld</literal>/<literal>installworld</literal> procedures for updating &os; from source should <emphasis>not</emphasis> - attempt this procedure, but should instead perform a binary + attempt a source upgrade, but should instead perform a binary installation after backing up all data.</para> </note> - <para>The source-based upgrade procedure relies on building and - installing a set of binaries, compiled from source on the + <para>A source-based upgrade builds and + installs set of binaries compiled from source on the local machine. It is based on the <literal>buildworld</literal>/<literal>installworld</literal> procedure often used by advanced &os; users to track changes along a development branch (such as &os.stable; or - &os.current;). In general, this procedure involves more - effort than the binary upgrade procedure listed in the - previous system, but may be useful when a system's + &os.current;). In general, this involves more + effort than the binary upgrade procedure, but may be useful when a system's configuration files are complex or have been highly - customized. Another scenario where this procedure is useful - is that of a remote system where an administrator has remote + customized. Source upgrade can also be useful + when there is a remote system where an administrator has remote console access but no physical access (and therefore cannot insert installation media).</para> <para>Reading <filename>src/UPDATING</filename> is absolutely essential. The section entitled <quote>To upgrade in-place from 4.x-stable to current</quote> contains a step-by-step update - procedure. This procedure must be followed exactly, without - making use of the <quote>shortcuts</quote> that some users + procedure which must be followed <emphasis>exactly</emphasis>, without + using of the <quote>shortcuts</quote> that some users occasionally employ. An annotated list of these steps is presented below:</para> @@ -530,7 +527,7 @@ <listitem> <para>Make backups.</para> - <para>The importance of this step cannot be overstated. It + <para>The importance of this cannot be overstated. It is important to make backups of all user data and configuration files. Level zero dumps with &man.dump.8; are an excellent way to do this, although there are of @@ -540,15 +537,12 @@ <listitem> <para>Fix <filename>/etc/fstab</filename> if required.</para> - <para>This item probably only affects very old &os;/i386 and - &os;/pc98 systems. - On systems that use MBR-style disk slices (such as the - i386), &os; used to support <quote>compatibility - slices</quote>, where disk partition names could take the - form <filename>/dev/ad0a</filename> (without specifying a - slice name explicitly). These are no longer supported; + <para><quote>Compatibility slices</quote>, where disk + partition names can take the form <filename>/dev/ad0a</filename> + (without specifying a slice name explicitly) are no longer supported; disk partitions must be named according to the form - <filename>/dev/ad0s1a</filename>.</para> + <filename>/dev/ad0s1a</filename>. This probably only affects very old &os;/i386 and + &os;/pc98 systems.</para> <para>Note that <quote>compatibility slices</quote> have generally not been used since &os; @@ -564,7 +558,7 @@ release and security fix branch, use the <literal>RELENG_5_3</literal> tag. When using CVS to check out the source tree, it is important to pass the - <option>-P</option> flag to CVS so that it prunes away + <option>-P</option> flag to CVS so to prune away empty directories.</para> </listitem> @@ -576,7 +570,7 @@ <para>If <varname>CPUTYPE</varname> is defined in <filename>/etc/make.conf</filename>, it should be defined - using the <literal>?=</literal> operator, so that the + using the <literal>?=</literal> operator, so the <literal>buildworld</literal> process can override this variable if necessary.</para> </listitem> @@ -591,11 +585,11 @@ the resulting kernel is compiled with the toolchain built in the <literal>buildworld</literal> step above. Manually using &man.config.8; to set up a kernel build area and - attempting to build a kernel will not work in this case.</para> + attempting to build a kernel will not work.</para> <para>Although building (and later installing) a custom - kernel at this point is feasible, upgrading using the - <literal>GENERIC</literal> kernel and installing to a + kernel is feasible at this point, upgrading using the + <literal>GENERIC</literal> kernel and installing a custom kernel configuration later may be less error-prone.</para> </listitem> @@ -614,8 +608,8 @@ <screen><command>&prompt.root; cd /usr/src/sys/boot ; make STRIP="" install</command></screen> - <para>While optional, this step is highly recommended. At this - point, it is also recommended to disable third-party + <para>This step, though optional, is highly recommended. + We also recommend disabling third-party modules (such as those for VMware) to prevent crashes caused by changes in kernel ABIs or other incompatibilities.</para> @@ -650,7 +644,7 @@ <screen><command>&prompt.root; mergemaster -p</command></screen> - <para>This step is necessary in order to give some new files + <para>This step must be performed to give some new files the correct usernames and groupnames.</para> </listitem> @@ -659,8 +653,8 @@ <screen><command>&prompt.root; rm -rf /usr/include/g++</command></screen> - <para>This step is required so that future compilations do - not accidentally pick up old header files from the + <para>This keeps future compilations from + accidentally picking up old header files from the <application>GCC</application> 2.95 C++ compiler.</para> </listitem> @@ -675,7 +669,7 @@ <screen><command>&prompt.root; mergemaster -i</command></screen> - <para>This step is especially important. It is required to + <para>This especially important step is required to make the startup and configuration files <filename>/etc</filename> consistent with the new kernel and world.</para> @@ -688,8 +682,7 @@ <para>After upgrading the base system, upgrades to some non-base-system components are generally - needed to restore normal functionality. As previously - mentioned, <application>Perl</application> is no longer a part + needed to restore normal functionality. <application>Perl</application> is no longer a part of the base system and should be installed from the Ports Collection (specifically, the <filename role="package">lang/perl5.8</filename> port) or from a @@ -705,8 +698,8 @@ <para>As mentioned in a prior section, <application>&xorg;</application> is the default implementation of the X Window System. The Ports Collection - (as well as packages) rely on this change for the purpose of - satisfying dependencies. To convert the installed windowing + (and packages) rely on this change to satisfy dependencies. + To convert the installed windowing system from <application>&xfree86;</application> to <application>&xorg;</application>, refer to the <ulink url="&url.books.handbook;/x-install.html">Installing @@ -719,10 +712,10 @@ <title>Summary</title> - <para>This article presented some of the more notable new features - in &os; &release.5x;, and listed some areas that of particular + <para>This article presents some of the more notable new features + in &os; &release.5x;, and lists some areas of particular concern to those users upgrading existing &os; &release.4x; - systems. It also presented two sets of upgrade instructions, + systems. It also presents two sets of upgrade instructions, one using binaries from installation media and one based on recompiling the base system from source code.</para> --Boundary-00=_SwKPBJAGFNOId5W--
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?200409061427.30634.zettel>