From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from mailman by lists.gnu.org with archive (Exim 4.43) id 1OxoyC-0005BJ-1t for mharc-grub-devel@gnu.org; Mon, 20 Sep 2010 18:36:20 -0400 Received: from [140.186.70.92] (port=39083 helo=eggs.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1Oxoy8-0005B1-IL for grub-devel@gnu.org; Mon, 20 Sep 2010 18:36:18 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.69) (envelope-from ) id 1Oxoy5-0003ui-K2 for grub-devel@gnu.org; Mon, 20 Sep 2010 18:36:16 -0400 Received: from mail-pw0-f41.google.com ([209.85.160.41]:32964) by eggs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1Oxoy5-0003tH-A3 for grub-devel@gnu.org; Mon, 20 Sep 2010 18:36:13 -0400 Received: by pwj6 with SMTP id 6so3612806pwj.0 for ; Mon, 20 Sep 2010 15:36:11 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=gamma; h=domainkey-signature:received:received:message-id:date:from :user-agent:mime-version:to:subject:content-type; bh=g6xqKACjVFWy6CjubQAHFn+0KJbfin3MpCNjqGsJHss=; b=nJExUip87F+nADqUhS+gmeqJCWCPtcz5nO8DwbiyRjh7mAJUGaZaV3h9y7Yj0Xwy83 2Ae21t9vXuZcgwPyZxMinRkXwppA9h1wwpuTMrt80WzQoetJGb2ITBl+agV+Pa+UblxY +GyYngQpZXPFRBdKLIRUWcAh5w349Kd9544Bk= DomainKey-Signature: a=rsa-sha1; c=nofws; d=gmail.com; s=gamma; h=message-id:date:from:user-agent:mime-version:to:subject :content-type; b=Iir6IZT1nJJJHk1+CSUYwYKOXWBfsaQttIq1zXOzMBy/dqtVhTkgukfssCiUNdT3Vt aljaNjfbC3gWoU5uArtes7RFe+fbglytXznkQ456dRO3hs2JxZsUaezbcx6V08aOFRXR Vblps0LiLNpfCafobtPPVdfWwB8FQU8DxxaDI= Received: by 10.114.109.6 with SMTP id h6mr10917352wac.75.1285022171255; Mon, 20 Sep 2010 15:36:11 -0700 (PDT) Received: from [192.168.1.2] ([216.57.70.194]) by mx.google.com with ESMTPS id c24sm14280888wam.19.2010.09.20.15.36.07 (version=SSLv3 cipher=RC4-MD5); Mon, 20 Sep 2010 15:36:10 -0700 (PDT) Message-ID: <4C97E1D5.2000109@gmail.com> Date: Mon, 20 Sep 2010 15:36:05 -0700 From: Jordan Uggla User-Agent: Mozilla/5.0 (X11; U; Linux x86_64; en-US; rv:1.9.1.12) Gecko/20100915 Thunderbird/3.0.8 MIME-Version: 1.0 To: grub-devel@gnu.org Content-Type: multipart/mixed; boundary="------------050404050301010501070707" X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6 (newer, 2) Subject: [PATCH] Update grub-install documentation. X-BeenThere: grub-devel@gnu.org X-Mailman-Version: 2.1.5 Precedence: list Reply-To: The development of GNU GRUB List-Id: The development of GNU GRUB List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 20 Sep 2010 22:36:19 -0000 This is a multi-part message in MIME format. --------------050404050301010501070707 Content-Type: text/plain; charset=ISO-8859-1; format=flowed Content-Transfer-Encoding: 7bit The documentation for grub-install in docs/grub.texi is mostly just a leftover from the GRUB legacy documentation, and is therefore inaccurate in many ways with respect to GRUB2. Attached is a merge proposal that fixes most of the problems I found with the grub-install documentation. One problem that I did find that I don't know quite how to deal with (and haven't in this patch) is this paragraph: By the way, as noted above, it is quite difficult to guess BIOS drives correctly under a UNIX-like OS. Thus, grub-install will prompt you to check if it could really guess the correct mappings, after the installation. The format is defined in Device map. Please be quite careful. If the output is wrong, it is unlikely that your computer will be able to boot with no problem. The device.map is not needed in most cases, and GRUB2 for all but a few odd and uncommon cases is completely independent of device enumeration. Despite that, a user can create a device.map that would cause problems with grub-install, for instance "(hd0) /dev/md0". So some mention of device.map with regard to grub-install is probably needed, but I'll leave that to someone else to write. --------------050404050301010501070707 Content-Type: text/plain; name="update_grub-install_docs.txt" Content-Transfer-Encoding: 7bit Content-Disposition: attachment; filename="update_grub-install_docs.txt" # Bazaar merge directive format 2 (Bazaar 0.90) # revision_id: jordan.uggla@gmail.com-20100920210151-vdf1002s87z46my8 # target_branch: file:///home/jordan/grub-bzr/grub-trunk/ # testament_sha1: 672157381054a4b4f1842f87eb01970813e873c2 # timestamp: 2010-09-20 14:06:06 -0700 # base_revision_id: phcoder@gmail.com-20100920202430-j7zw8icehfwb7g25 # # Begin patch === modified file 'ChangeLog' --- ChangeLog 2010-09-20 20:24:30 +0000 +++ ChangeLog 2010-09-20 21:01:51 +0000 @@ -1,3 +1,8 @@ +2010-09-20 Jordan Uggla + + Update grub-install documetation to account for changes between + GRUB legacy and GRUB2. + 2010-09-20 Vladimir Serbinenko Make cutmem accept a region specification. === modified file 'docs/grub.texi' --- docs/grub.texi 2010-09-20 13:03:47 +0000 +++ docs/grub.texi 2010-09-20 21:01:51 +0000 @@ -523,13 +523,10 @@ from the source tarball, or as a package for your OS. After you have done that, you need to install the boot loader on a -drive (floppy or hard disk). There are two ways of doing that - either -using the utility @command{grub-install} (@pxref{Invoking -grub-install}) on a UNIX-like OS, or by running GRUB itself from a -floppy. These are quite similar, however the utility might probe a -wrong BIOS drive, so you should be careful. +drive using the utility @command{grub-install} (@pxref{Invoking +grub-install}) on a UNIX-like OS. -Also, if you install GRUB on a UNIX-like OS, please make sure that you +Before installing grub to your hard drive please make sure that you have an emergency boot disk ready, so that you can rescue your computer if, by any chance, your hard drive becomes unusable (unbootable). @@ -550,20 +547,11 @@ @node Installing GRUB using grub-install @section Installing GRUB using grub-install -@strong{Caution:} This procedure is definitely less safe, because -there are several ways in which your computer can become -unbootable. For example, most operating systems don't tell GRUB how to -map BIOS drives to OS devices correctly---GRUB merely @dfn{guesses} -the mapping. This will succeed in most cases, but not -always. Therefore, GRUB provides you with a map file called the -@dfn{device map}, which you must fix if it is wrong. @xref{Device -map}, for more details. - -If you still do want to install GRUB under a UNIX-like OS (such -as @sc{gnu}), invoke the program @command{grub-install} (@pxref{Invoking -grub-install}) as the superuser (@dfn{root}). - -The usage is basically very simple. You only need to specify one +To install GRUB under a UNIX-like OS (such as @sc{gnu}), invoke the program +@command{grub-install} (@pxref{Invoking grub-install}) as the superuser +(@dfn{root}). + +The usage is very simple. In most cases you only need to specify one argument to the program, namely, where to install the boot loader. The argument can be either a device file (like @samp{/dev/hda}) or a partition specified in GRUB's notation. For example, under Linux the @@ -579,7 +567,8 @@ # @kbd{grub-install /dev/hd0} @end example -If it is the first BIOS drive, this is the same as well: +If @samp{/dev/hd0} is mapped to @samp{(hd0)} in the @file{device.map}, this is +the same as well: @example # @kbd{grub-install '(hd0)'} @@ -591,7 +580,13 @@ # @kbd{grub-install hd0} @end example -But all the above examples assume that GRUB should use images under +Because device names specified using grub's internal notation are mapped to +device nodes as presented by the OS using the @xref{Device map}, which device +grub is actually installed to depends on the contents of the @file{device.map}. +To avoid ambiguity and the chance of writing to the wrong device use of the OS's +device naming is recommended. + +All the above examples assume that GRUB should use images under the root directory. If you want GRUB to use images under a directory other than the root directory, you need to specify the option @option{--root-directory}. The typical usage is that you create a GRUB @@ -601,19 +596,11 @@ @group # @kbd{mke2fs /dev/fd0} # @kbd{mount -t ext2 /dev/fd0 /mnt} -# @kbd{grub-install --root-directory=/mnt fd0} +# @kbd{grub-install --force --root-directory=/mnt /dev/fd0} # @kbd{umount /mnt} @end group @end example -Another example is when you have a separate boot partition -which is mounted at @file{/boot}. Since GRUB is a boot loader, it -doesn't know anything about mountpoints at all. Thus, you need to run -@command{grub-install} like this: - -@example -# @kbd{grub-install --root-directory=/boot /dev/hda} -@end example By the way, as noted above, it is quite difficult to guess BIOS drives correctly under a UNIX-like OS. Thus, @command{grub-install} will prompt @@ -626,8 +613,7 @@ real task is done by @command{grub-mkimage} and @command{grub-setup}. Therefore, you may run those commands directly to install GRUB, without using @command{grub-install}. Don't do that, however, unless you are very -familiar with the internals of GRUB. Installing a boot loader on a running -OS may be extremely dangerous. +familiar with the internals of GRUB. @node Making a GRUB bootable CD-ROM # Begin bundle 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 --------------050404050301010501070707--