Bug 101460 – Gentoo Linux AMD64 Handbook lists incorrect make.profile for platform

• Product: [OLD] Docs-user
• Status: RESOLVED FIXED

[Description Blair Heiserman 2005-08-05 10:38:54 UTC]

Section 6.a  has multiple code listings that reference the standard x86 
platform instead of the amd64 platform. This will cause user confusion, unless 
they are specifically paying attention to the exact profile.  
 
Code Listing 7: Verifying system profile 
  # ls -FGg /etc/make.profile lrwxrwxrwx  1 48 Apr  8 18:51 /etc/make.profile 
-> ../usr/portage/profiles/default-linux/x86/2005.0/ 
 
Should be 
 
Code Listing 7: Verifying system profile 
  # ls -FGg /etc/make.profile lrwxrwxrwx  1 48 Apr  8 18:51 /etc/make.profile 
-> ../usr/portage/profiles/default-linux/amd64/2005.0/ 
 
or at least <your-arch> instead of x86. 
 
Problem can also be found in code listing 8 and 9 as well. 
 
I'm not too proud to say that I managed to bork a perfectly useable AMD64 
installation while trying to upgrade to 2005.0. Entirely because I simply 
didn't notice the x86 reference. 
 
If the platform specific references can be changed so that in most cases they 
either read <your-arch> or amd64 (as appropriate) it will either make users 
think while reading the documentation or stop to make the appropriate 
selection. 
 
It took me a while to figure out this problem. I broke the system with the 
wrong profile, because I was in a hurry and quickly trying to upgrade to 
2005.0, and it took me forever to realize that the problem was in the 
make.profile link... and it was too late to do anything other then rebuild. 

Reproducible: Always
Steps to Reproduce:
1.
2.
3.

[Comment 1 Xavier Neys (RETIRED) 2005-08-06 08:48:01 UTC]

"""
However, x86, hppa and alpha users can choose between two profiles, one for a
2.4 kernel and one for a 2.6 kernel. This requirement has been imposed to
improve the integration of the 2.6 kernels.
"""
amd64 is not listed (I quote again, 'x86, hppa and alpha') and amd64 users have
no reason to change their profile at that point of the installation procedure.

To upgrade an existing amd64 installation, you should read
http://www.gentoo.org/proj/en/base/amd64/howtos/index.xml?part=1&chap=1

[Comment 2 Blair Heiserman 2005-08-08 10:13:02 UTC]

My apologies. I should have left my upgrade horror story out. 
 
My main point is that in the base documentation for an install of an x86_64 
system. The Code Listings for where you select your make.profile incorrectly 
list x86 instead of amd64 or <your-arch>. 
 
If you use the installation docs as a reference for when you are having 
issues, it is critical for the code listings to reference the correct 
architecture, otherwise it is far simpler for the user to simply have a single 
installation documention, with separate tech notes. 

[Comment 3 Shyam Mani (RETIRED) 2005-08-09 10:52:41 UTC]

(In reply to comment #2)

> My main point is that in the base documentation for an install of an x86_64 
> system. The Code Listings for where you select your make.profile incorrectly 
> list x86 instead of amd64 or <your-arch>. 

Which is incorrect. For amd64, you don't touch make.profile at all as Xavier
pointed out. There are no multiple profiles for amd64. If you went and changed
your make.profile for amd64, you didn't read the handbook correctly.

Now, I do agree that Code listing 7 might be a wee bit confusing.....and I think
that needs to be made amd64 specific or generic so as to not cause confusion.  

[Comment 4 Shyam Mani (RETIRED) 2005-08-09 11:00:38 UTC]

(In reply to comment #3)
> Now, I do agree that Code listing 7 might be a wee bit confusing.....and I think
> that needs to be made amd64 specific or generic so as to not cause confusion. 

Since this a common file, I think we can add a note asking users to verify arch. 

[Comment 5 Xavier Neys (RETIRED) 2005-08-21 16:17:56 UTC]

Some bits have been changed with the 2005.1 release.

FYI, it's explained at the very beginning of the handbook that some foreign
arches can be mentioned.
Switching profiles does not apply to AMD64. It clearly says "x86, hppa and alpha".

"On x86, we can do this with the following command:"
 and
"the example below is for x86)
# ln -snf /usr/portage/profiles/default-linux/x86/2005.1/2.4 /etc/make.profile</i>"
should make it clear enough that the examples are for x86.