--- article.sgml Mon Sep 6 14:00:00 2004 +++ changed_article.sgml Mon Sep 6 13:58:03 2004 @@ -62,42 +62,42 @@ Introduction &os; &release.5branchpoint; marks the beginning of a new - &os.stable; 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 + &os.stable; 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. - This article addresses a number of topics and issues that - are of interest to users updating from a &release.4x; release to + 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. + systems to &os; &release.5branchpoint;, from binaries or + from source. An Overview of the &os; Release Process - &os; employs a model of development that relies on multiple - development branches within the source code repository. The main branch is called + &os; employs a development model relying on multiple + branches within the source code repository. The main branch is called CURRENT, and is referred to in the CVS repository with the HEAD 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. Most &os; releases are made from one of several - STABLE branches. Features are only added to - these branches after some amount of testing in CURRENT. For the + STABLE 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 4-STABLE, and all of the &os; &release.4x; releases were based on it. This branch has the tag RELENG_4 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. 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. @@ -128,19 +128,20 @@ The past two stable branches (3-STABLE and 4-STABLE) were created very soon after their respective dot-oh 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. The next release from CURRENT will likely be 6.0-RELEASE, - created from CVS HEAD. As of the 5.3 release - date, there is no firm date for 6.0, although this release is + created from CVS HEAD. There is no firm date for 6.0, + as of the 5.3 release + date, although it is expected sometime in 2006. 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 @@ 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 @@ SMPng: The next generation 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 @@ 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 @@ 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. @@ -248,7 +249,7 @@ 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 @@ Notable Changes 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: @@ -277,9 +278,9 @@ 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 Perl (available in the &os; Ports Collection as - 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 + 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. - 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 + 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 a.out-style executables, Note that execution of a.out @@ -332,18 +334,17 @@ On the i386 and pc98 platforms, a UserConfig 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). MAKEDEV 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. @@ -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 to &man.newfs.8;, or on the disk labeling screen in @@ -368,27 +369,25 @@ - Due to the upgraded GCC - compiler, C++ programs generally need to be recompiled and - reinstalled. This requirement comes from changes in the C++ - ABI. + Changes in the C++ ABI in the upgraded GCC + generally require that C++ programs be recompiled and + reinstalled. - With the exception of C++ programs described above, it + 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 - compat4x distribution to be installed + under &release.5x;, if the + compat4x distribution is installed (this distribution can also be installed with the misc/compat4x 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 statfs + structure require the recompilation of the devel/gnomevfs2, mail/postfix, and security/cfs ports need to be - recompiled due to changes in the statfs - structure. + role="package">security/cfs ports. + @@ -396,10 +395,10 @@ The &xorg; 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, &xfree86; 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 The X Window System chapter in the &os; Handbook. @@ -446,9 +445,9 @@ advantage of new functionality (most notably, the UFS2 defaults). - As of this writing, the binary upgrade option in + 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. 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 GENERIC 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: boot.flp, kern1.flp, and kern2.flp. @@ -475,9 +474,8 @@ CDROM-based installations on the i386 architecture now use a no-emulation boot loader. This allows, among other things, the use of a GENERIC 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. @@ -487,42 +485,41 @@ Source Upgrades - In general, many users and developers have found it easier + 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. + (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. Users unfamiliar with the buildworld/installworld procedures for updating &os; from source should not - 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. - The source-based upgrade procedure relies on building and - installing a set of binaries, compiled from source on the + A source-based upgrade builds and + installs set of binaries compiled from source on the local machine. It is based on the buildworld/installworld 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). Reading src/UPDATING is absolutely essential. The section entitled To upgrade in-place from 4.x-stable to current contains a step-by-step update - procedure. This procedure must be followed exactly, without - making use of the shortcuts that some users + procedure which must be followed exactly, without + using of the shortcuts that some users occasionally employ. An annotated list of these steps is presented below: @@ -530,7 +527,7 @@ Make backups. - The importance of this step cannot be overstated. It + 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 @@ Fix /etc/fstab if required. - 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 compatibility - slices, where disk partition names could take the - form /dev/ad0a (without specifying a - slice name explicitly). These are no longer supported; + Compatibility slices, where disk + partition names can take the form /dev/ad0a + (without specifying a slice name explicitly) are no longer supported; disk partitions must be named according to the form - /dev/ad0s1a. + /dev/ad0s1a. This probably only affects very old &os;/i386 and + &os;/pc98 systems. Note that compatibility slices have generally not been used since &os; @@ -564,7 +558,7 @@ release and security fix branch, use the RELENG_5_3 tag. When using CVS to check out the source tree, it is important to pass the - flag to CVS so that it prunes away + flag to CVS so to prune away empty directories. @@ -576,7 +570,7 @@ If CPUTYPE is defined in /etc/make.conf, it should be defined - using the ?= operator, so that the + using the ?= operator, so the buildworld process can override this variable if necessary. @@ -591,11 +585,11 @@ the resulting kernel is compiled with the toolchain built in the buildworld 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. + attempting to build a kernel will not work. Although building (and later installing) a custom - kernel at this point is feasible, upgrading using the - GENERIC kernel and installing to a + kernel is feasible at this point, upgrading using the + GENERIC kernel and installing a custom kernel configuration later may be less error-prone. @@ -614,8 +608,8 @@ &prompt.root; cd /usr/src/sys/boot ; make STRIP="" install - While optional, this step is highly recommended. At this - point, it is also recommended to disable third-party + 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. @@ -650,7 +644,7 @@ &prompt.root; mergemaster -p - This step is necessary in order to give some new files + This step must be performed to give some new files the correct usernames and groupnames. @@ -659,8 +653,8 @@ &prompt.root; rm -rf /usr/include/g++ - This step is required so that future compilations do - not accidentally pick up old header files from the + This keeps future compilations from + accidentally picking up old header files from the GCC 2.95 C++ compiler. @@ -675,7 +669,7 @@ &prompt.root; mergemaster -i - This step is especially important. It is required to + This especially important step is required to make the startup and configuration files /etc consistent with the new kernel and world. @@ -688,8 +682,7 @@ After upgrading the base system, upgrades to some non-base-system components are generally - needed to restore normal functionality. As previously - mentioned, Perl is no longer a part + needed to restore normal functionality. Perl is no longer a part of the base system and should be installed from the Ports Collection (specifically, the lang/perl5.8 port) or from a @@ -705,8 +698,8 @@ As mentioned in a prior section, &xorg; 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 &xfree86; to &xorg;, refer to the Installing @@ -719,10 +712,10 @@ Summary - This article presented some of the more notable new features - in &os; &release.5x;, and listed some areas that of particular + 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.