Step 26 (Installation Complete). I expected the boot-up to look like the live CD. Instead I got a blast of boot messages and some indications of problems, even though when I logged in, everything seemed to be working. If the installation is complete, I expect to see no errors or warnings. However, that was not the case. Following is a list of errors that showed up in the system. Some of these are probably significant, but there is nothing in the documentation or on the website (that I could find) that gives me a clue as to what they mean or how to get rid of them. a. When booting, after the "* Cleaning /var/lock, /var/run ..." boot message, I see on the screen "xargs: environment is too large for exec" (so what do I do?) b. After the "* Starting USB and PCI hotplugging..." message, I see "insmod: /lib/modules/.../drivers/net/8139cp.o" init_modules: No such device". This is followed by more of these same insmod failed messages for the 8139cp.o device. I did not install this device as a module, it is compiled into the kernel, and the network seems to work, so what are all these error message telling me? c. I looked at "dmesg" and got another set of error messages (all of these are also in /var/log/everything/current). c.1 After "ICH4: IDE Controller on PCI bus 00 dev f9", "PCI: Device 00:1f.1 not available because of resource collisions ICH4: BIOS setup was incomplete" (Is there an error here? am I supposed to do something?) c.2 "kmod: failed to exec /sbin/modprobe -s -k scsi_hostadapter, errno=2" (messages repeated 3 times). c.3 "scsi: <fdomain> Detectioin failed (no card) "Failed initialization of WD-7000 SCSI card!" (I don't have a SCSI card, so why is there a failure reported?) c.4 "Trying to move old root to /initrd ... failed" (so what? am I supposed to do something?) c.5 "8139cp: 10/100 PCI Ethernet driver v0.3.0 (Sep 29, 2002)" (This message was repeated 9 more times in the log file, why?) My suggestion is to have an error-free boot after completing all of the steps in the installation guide. If that is not possible, then at least have something on the web-site that lists the error messages and indicates what to do about it (ignore it, fix it, etc.).
An error-free boot-up is indeed something we should go towards. However, the more we explain in the installation guide, the longer it takes before you have a working Gentoo installation. I don't know about all errors, but possible issues are: - About the xargs problem: this has been solved in version 1.8.6.10-r1 of the baselayout package. No documentation issue. - About the insmod errors: check /etc/modules.autoload.d/kernel-2.4 and /etc/modules.d/aliases and /etc/modules.conf. I have heard this issue several times, but never found an adequate answer. - c.1 is a kernel-configuration mistake - c.2 is a kernel-configuration mistake - c.3 is a kernel-configuration mistake - c.4 is new to me. You said you compiled your kernel manually, did you set initrd information in grub.conf anyway? - c.5 is new to me too, but I cannot tell you why...
Need more info to go on with this...
I would not expect the installation guide to explain all of the possibilities. I was thinking more like a (new) step 27 that says something like "You should now have an error-free boot when rebooting the system. Look at the initial screen on startup, then login to root and run "dmesg" to verify that there are no problems with the boot. If errors show up in either of these places, go to http://gentoo.org/somewhere to locate the source of the problem and a possible solution." Then gentoo would need to collect any error messages (such as the ones I included as examples) and the solutions and make them available to others who have the same problems. This type of approach has been used for many years in the documentation for mini-computer systems, compilers, loaders, etc.
The problem is that *if* there are issues, then we should resolve those one by one. I rather have the users place bugreports so we know what the common pitfalls are. Then we can group those together and perhaps write a separate guide, for instance "Tips 'n Tricks", which could contain hints on what to do when something doesn't work out right. However, in most cases the issues are very individual or short-lived. For instance your (a) has been fixed in a later version of the baselayout package. (b) is an issue I've seen pop up from time to time but never found an adequate answer, (c) has mostly to do with wrong kernel configuration which is *very* individual and very difficult to explain. We try to inform the user about what to do/where to look when things go wrong at the beginning of the installation: http://www.gentoo.org/doc/en/handbook/handbook.xml?part=1&chap=1#doc_chap1_sect3 I'll be more than happy to reference this once again at the final chapter of the first part...
... but I won't. Duplicating information isn't good, and the information is already in the guide (and in the best place: at the beginning). If you have issues, please report those one by one. Don't summon up the issues as most of them are totally unrelated and therefore should be assigned to different herds/developers.