swift 05/05/23 18:35:47 Modified: xml/htdocs/doc/en kernel-upgrade.xml Log: #93289 - Improve explanation on upgrade path. Thanks to Jimi Ayodele for the patch.
Revision Changes Path 1.4 +54 -43 xml/htdocs/doc/en/kernel-upgrade.xml file : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/kernel-upgrade.xml?rev=1.4&content-type=text/x-cvsweb-markup&cvsroot=gentoo plain: http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/kernel-upgrade.xml?rev=1.4&content-type=text/plain&cvsroot=gentoo diff : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/kernel-upgrade.xml.diff?r1=1.3&r2=1.4&cvsroot=gentoo Index: kernel-upgrade.xml =================================================================== RCS file: /var/cvsroot/gentoo/xml/htdocs/doc/en/kernel-upgrade.xml,v retrieving revision 1.3 retrieving revision 1.4 diff -u -r1.3 -r1.4 --- kernel-upgrade.xml 6 Apr 2005 14:36:19 -0000 1.3 +++ kernel-upgrade.xml 23 May 2005 18:35:47 -0000 1.4 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="UTF-8"?> -<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/kernel-upgrade.xml,v 1.3 2005/04/06 14:36:19 neysx Exp $ --> +<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/kernel-upgrade.xml,v 1.4 2005/05/23 18:35:47 swift Exp $ --> <!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> <guide link="/doc/en/kernel-upgrade.xml"> @@ -17,8 +17,8 @@ <!-- See http://creativecommons.org/licenses/by-sa/2.0 --> <license/> -<version>0.1.2</version> -<date>2005-04-06</date> +<version>0.1.3</version> +<date>2005-05-23</date> <chapter> <title>Introduction</title> @@ -33,7 +33,7 @@ </p> <p> -Although this guide is targetted at users upgrading from one kernel release +Although this guide is targeted at users upgrading from one kernel release to another, it will also be useful for users migrating from one kernel package to another. </p> @@ -48,15 +48,16 @@ </chapter> <chapter> -<title>Why upgrade kernel?</title> +<title>Why upgrade the kernel?</title> <section> <body> <p> Generally, upgrading from one minor kernel release to the next won't bring any -major differences. Reasons for upgrading kernel are generally either to take -advantage of a specific new feature or driver, to be protected against a -security vulnerability, or just to maintain an up-to-date and healthy system. +major differences. There are several reasons to upgrade the kernel. One is to +take advantage of a specific new feature or driver; another is to be protected +against a security vulnerability, or just to maintain an up-to-date and healthy +system. </p> <p> @@ -104,7 +105,7 @@ <p> The kernel sources will then be installed into a subdirectory of -<path>/usr/src</path>. In the above example, my new kernel sources will be +<path>/usr/src</path>. In the above example, the new kernel sources will be installed at <path>/usr/src/linux-2.6.9-gentoo-r2</path>. </p> @@ -124,7 +125,7 @@ </p> <p> -In this case, we need to update the symbolic link to point at the kernel +In any case, we need to update the symbolic link to point at the kernel sources that we are about to upgrade to. Continuing our example: </p> @@ -146,7 +147,7 @@ For either of these options, you should refer to the instructions given in the <uri link="http://www.gentoo.org/doc/en/handbook/index.xml";>Gentoo Handbook</uri> relating to <e>Configuring the Kernel</e> and <e>Configuring -the Bootloader</e>. A quick summary is provided here. +the Bootloader</e>. Below is an outline of the required actions: </p> </body> @@ -182,7 +183,10 @@ <p> For more info, follow the <uri link="http://www.gentoo.org/doc/en/genkernel.xml";>Gentoo Linux Genkernel -Guide</uri>, or refer to the handbook. +Guide</uri>, or refer to the <uri link="/doc/en/handbook/index.xml">Gentoo +Handbook</uri>. Many of the options can be set in the configuration file for +<uri link="/doc/en/genkernel.xml">genkernel</uri>, +<path>/etc/genkernel.conf</path>. </p> </body> @@ -201,15 +205,19 @@ </pre> <p> -Select the options required for your hardware and operating environment. Refer -to the <e>Gentoo Handbook</e> for additional guidance on this. +Select the options required for your hardware and operating environment. For +additional information on kernel configuration, refer to the chapter entitled +<e>Configuring the Kernel</e> of the <uri +link="/doc/en/handbook/index.xml">Gentoo Handbook</uri>. </p> <p> Next, compile your kernel and copy it over to your boot partition. Again, -follow the handbook instructions here, but don't forget to mount your /boot -partition first! In the initial installation, you would have already mounted -this at a much earlier stage. +follow the <uri link="/doc/en/handbook/index.xml">Gentoo Handbook</uri> +instructions outlined in the chapter on <e>Configuring the Bootloader</e>. If +<path>/boot</path> is a separate partition, ensure it is mounted before copying +the compiled kernel to this directory! Failing to do so would keep you from +booting the system with your new kernel. </p> <pre caption="Compiling and installing the new kernel"> @@ -222,8 +230,9 @@ <p> Finally, you should update your bootloader config, adding an entry for the new kernel (don't delete the old one just yet!) and unmount the -<path>/boot</path> partition. Again, refer to the handbook for instructions -here. +<path>/boot</path> partition. Again, refer to the +<uri link="/doc/en/handbook/index.xml">Gentoo Handbook</uri> +for detailed instructions on this procedure. </p> </body> @@ -237,14 +246,15 @@ <p> If you use any kernel modules that are not included in the kernel source tree -but are provided elsewhere in portage (e.g. Nvidia or ATI graphics drivers), -then you must reinstall these on every kernel upgrade. This is as simple as -re-merging the packages involved. Refer again to the -<uri link="http://www.gentoo.org/doc/en/handbook/index.xml";>Gentoo -Handbook</uri> <e>Configuring the Kernel</e> chapter for more info here. -Re-merging these packages will ensure they build against the source tree at -<path>/usr/src/linux</path> - therefore they will actually being installed -for the kernel we just compiled. +but are provided elsewhere in portage (e.g. NVIDIA or ATI graphics drivers), +then you must reinstall these after upgrading the kernel. This is as simple as +re-merging the packages involved. For more information, refer to the chapter on +<e>Configuring the Kernel</e> in the <uri +link="/doc/en/handbook/index.xml">Gentoo Handbook</uri>. +To ensure these packages will build against the source tree at +<path>/usr/src/linux</path>, first uninstall the packages, then re-emerge them. +If old sources for these packages are kept by portage, this uninstall/re-emerge +procedure will make sure that they are rebuilt to work with the new kernel. </p> </body> @@ -258,23 +268,24 @@ <p> Next, close all applications and reboot your system. If you followed the above -instructions correctly, you will see an entry for your new kernel on your -bootloader. Select the new kernel and let the system boot. +instructions correctly, the bootloader menu should include an entry for the +new kernel. Select the new kernel and let the system boot. </p> <p> -Hopefully, your system will boot without problem and you can log in and start -working as usual. If everything is working, then the upgrade is complete at -this stage. +Hopefully, your system successfully boots with the new kernel, and you can log +in to resume whatever you were doing. If this is the case, then the upgrade is +complete. </p> <p> -If you have made a mistake and your system will not boot into the new kernel, -then you can simply reboot and boot into your previous working kernel. You can -then restart from the <uri link="#install">Configuring, compiling, and -installing the new kernel</uri> stage - making the appropriate changes to -correct your mistake. In some cases (e.g. you just missed a network driver) -then you might not even need to reboot to do this. +If you made a mistake and the system fails to boot with the new kernel, reboot +the system and select the entry from the bootloader that corresponds to the +last known working kernel. You can then restart from the <uri link="#install"> +Configuring, compiling, and installing the new kernel</uri> stage -- making +the appropriate changes to correct your mistake. In some cases, you might not +even need to reboot to do this (e.g. you missed a driver for an audio device, +ethernet adapter, etc.) </p> </body> @@ -288,7 +299,7 @@ <p> You may have noticed, that when installing the sources for your newer kernel, -the sources for your existing kernel were not removed. This is by-design and +the sources for your existing kernel were not removed. This is by design -- it allows you to easily switch between running different kernels. <<Truncated>> -- [email protected] mailing list
