[gentoo-user] Ideas for a mini-FAQ/HOWTO

[Walter Dnes]

I've been using Gentoo for several months now, and I've learned,
sometimes "the hard way", what to do and not to do.  Here's the first
draft of a mini-FAQ/HOWTO.  It can stand alone.  If there's another FAQ
out there already, maybe the ideas here can be included in it...

========================================================================
  The secret of a fast and stable Gentoo is knowing what *NOT* to do, as
much as knowing what to do.  To use an automotive analogy, any idiot can
floor the gas pedal, and keep it pressed down.  But if you don't let off
the gas pedal as the tachometer approaches the red line, your engine
will blow up on you.  In addition to hints about what to do, this
document will point out some red lines that should not be crossed.
Please remember, when I say do *NOT* do something, I have a reason.

  Commonsense disclaimer... cpu tweaks are *NOT* going to speed up a
program that pounds away on the hard drive.  But for cpu-intensive apps,
the speedup can be significant.  Properly optimizing Gentoo is a
fill-in-the-blanks excercise.  First, I'll deal with generic
optimizations that are applicable to all architectures.

  1) In /etc/make.conf set the following entry...
MAKEOPTS="-j1"
     Do *NOT*, I repeat, do *NOT* use higher numbers.  You are begging
for problems if you do so.  This is one place where I diverge from
official recommendation, ie.
http://www.gentoo.org/doc/en/handbook/handbook-x86.xml?full=1#book_part1_chap5__chap5_sect3
which says
> With MAKEOPTS you define how many parallel compilations should occur
> when you install a package. A good choice is the number of CPUs in
> your system plus one, but this guideline isn't always perfect.

  Actually, that statement of fact is correct.  The guideline is *NOT*
always perfect.  CPUs+1 *USUALLY* works, but "usually" isn't good
enough.  I have had compiles blow up on me on an old PII where I had set
MAKEOPTS="-j2".  Setting MAKEOPTS="-j1" solved the problem.  I've seen
reports of the same problem and solution on an AMD64.  The root cause of
the problem is that the combo of autoconf/make/gcc is not parallel-safe
today.  Future versions might be, but it will require major re-writes.
Parallel programming is a world of its own.  Parallel processes, by
definition, are not guaranteed to finish in a specific order.  In a
situation where module "b" depends on module "a", you get stuff like the
process which is supposed to delete module "a" executes before the
compilation of module "b" begins... oops.

  Future versions may be declared parallel-safe, but for now, stick with
j1.  It slows down *THE COMPILATION PROCESS*.  However, it does *NOT*
slow down *THE COMPILED PROGRAM*.

  2) The generic portion of CFLAGS consists of those flags that do not
begin with "-m".  For that part, use "-O2 -pipe -fomit-frame-pointer"

  Please, do *NOT* use "-O3" (or higher!!!) or try to unroll every last
loop or use every last exotic generic optimization.  Your programs will
*USUALLY* work, but they'll probably be flakier.  They may be faster, or
they may be slower.  However, people will point their fingers at you and
laugh.  Developers will ignore you when a program blows up and you file
a bug report.  The only exception is if a developer specifically OK's
special optimizations for specific modules or programs, and is willing
to support those modules or programs with extra optimization.  Things
may change in future versions of gcc, but the 3.4.x series works best
with the settings I've given.



  And now for the machine-specific flags in CFLAGS.  I'll use my machine
because it happens to be handy.  *YOUR MACHINE WILL HAVE DIFFERENT FLAGS
UNLESS YOU HAVE THE EXACT SAME MODEL AS ME*.  Try to follow the logic I
use, and apply it to your situation.

  Boot your machine with any linux distro, and execute...

cat /proc/cpuinfo

  The two output lines we're interested in are "model name" and "flags".
On my machine, they're...

model name	: Intel(R) Pentium(R) 4 CPU 1.80GHz

  That tells me what my CPU is. 

flags		: fpu vme de pse tsc msr pae mce cx8 apic sep mtrr pge mca cmov pat pse36 clflush dts acpi mmx fxsr sse sse2 ss ht tm

  This one involves a bit of looking up.  First execute "gcc --version"
to find out which version of gcc you're running.  Check the docs for your
version at http://gcc.gnu.org/onlinedocs and look under "Hardware Models
and Configurations" *FOR YOUR CPU*.  Look for anything in there that
matches anything in your flags line.  For my machine that's
"-march=pentium4 -mfpmath=sse -mmmx -msse -msse2".  This gives me a the
following combined CFLAGS line...

CFLAGS="-O2 -fomit-frame-pointer -pipe -march=pentium4 -mfpmath=sse -mmmx -msse -msse2"

  Some of the flags are also valid in the USE variable as well.  Check
your flags line against the list in /usr/portage/profiles/use.desc (or
online at http://www.gentoo.org/dyn/use-index.xml ).  In my case, mmx
and sse and sse2 are usable.  My USE variable looks like so (I'll explain
the "-*" later)...

USE="-* a52 aac alsa apm audiofile dio encode exif ffmpeg flac foomatic fortran gb gif gstreamer gtk2 ieee1394 jpeg maildir mikmod mmap mmx mng ncurses offensive ogg opengl plotutil png posix quicktime sdl slang sse theora threads tiff truetype vorbis win32codecs wmf xv"

  Some programs have additional flags that don't show up in the main
list.  They're listed in /usr/portage/profiles/use.local.desc, e.g.
mplayer has various additional flags.  If you're running mplayer on an
AMD64, the following entry in /etc/portage/package.use will help...

media-video/mplayer custom-cflags i8x0 real sse2 3dnowext mmxext

  You can add these flags to your main USE variable, but it'll end up
getting quite long.

Additional Hints
================

  Things to make life easier when switching to Gentoo

  1) The flags line for my cpu mentions that I have "apic mtrr acpi".
While these aren't for CFLAG or USE, knowing of them will be useful when
you build your kernel, and need to know if you have these facilities.

  2) In my USE variable, I start with "-*" which turns off all flags,
and then I enter the ones I want/need.  Gentoo combines your USE
variable with information from a few other locations to determine the
final set of flags to use for builds.  There are some flags specified in
"make.defaults" which take effect *UNLESS YOU SPECIFICALLY TURN THEM
OFF*.  That's what I use "-*" for.  For example, when the developers, in
their infinite wisdom, decided to include "ipv6" as a default, the 95%
of people who weren't using IPV6 found apps building with IPV6 support.
That's bad simply from the point of view of bloat.  What was really
annoying was that apps would first try a URL or hostname via IPV6, sit
for a minute until the IPV6 lookup timed out, and then finally get
around to trying IPV4.  *NOT FUN*.  "-*" in USE should protect you
against such surprises in future.  The whole point of Gentoo is that
*YOU* are in control.

  3) Avoid framebuffer unless you need it (non X86 architectures, etc)

  4) If you insist on framebuffer *PLEASE* avoid bootsplash, at least
until you have a functional system.  Yes, it's "cute" to see a penguin
graphic at bootup, or a smiling paperclip if you're weird.  But
bootsplash problems seem to pop up a lot on the Gentoo mailing list.
Worry about it after you have your system up and running.

  5) Have you used pam previously and know how to handle it?  Good, use
it in Gentoo.  If you aren't familiar with pam, don't use it now.  Gentoo
has its own steep learning curve.  So does pam.  Trying to learn *BOTH*
of them at once turns a steep learning curve into trying to climb up the
side of a cliff.  Once you've got Gentoo up and running, if you wish you
can start reading up on pam, and use it next time you install Gentoo.

  6) You have an internal PCI modem that you know should work under
Gentoo but your system can't even see it?  Here's the scoop.  Internal
PCI modems do *NOT* work on the first 4 com ports, ttyS0-through-ttyS3
(COM1: through COM4: in DOS).  They work on ttyS4 (COM5: in DOS) and
higher.  If you've built your kernel to only support 4 serial ports, PCI
modems will not work.  To enable ttyS4 and higher, you'll have to
rebuild your kernel with support for 5 (or more) serial ports.  Here's
the hierarchy in "make menuconfig"

    Device Drivers  --->
    Character devices  --->
    Serial drivers  --->
<*> 8250/16550 and compatible serial support
(5)   Maximum number of non-legacy 8250/16550 serial ports

    The (5) allows for 1 PCI modem.  If you have 2 PCI modems, you need
to set the number of ports to at least (6), etc.
========================================================================


-- 
Walter Dnes <waltdnes@××××××××.org>
My musings on technology and security at http://tech_sec.blog.ca
-- 
gentoo-user@g.o mailing list