gmp 4.1.4 build on 32 bit sparc8 misconfigures build as 64 bit for sparc9

[Torbjorn Granlund]

Axel Simon <A.Simon at kent.ac.uk> writes:

  Following this rather heated discussion I checked INSTALL and looked at
  the info-page. I have to say I agree with Graham. To take a bit of heat
  out of the discussion, I attached new INSTALL instructions to this mail.
  
I too agree with Graham.  I think ABI issues should be covered in
the Installing GMP chapter.  And it is.  I think machine specific
issues should be covered in the Installing GMP chapter.  And it
is.

  - The document should be self-contained, as far as this is possible. It
  should be enough for 95% of all people installing gmp, not only for the
  impatient. Many people will not actually use gmp but are merely told to
  install it, hence the introduction to programming gmp in INSTALL is out
  of place.

I disagree.  The INSTALL document really says what it is: a guide
for the impatient.  But 99.9% of the people will actually not
need to read anything but this, and a novice user will get a
trivial example of how to use the library.  This is how I'd like
documentation for all libs to be!  :-)

  The example code makes INSTALL too long to be for the
  impatient. Hence, I would not blame anyone for not reading to
  the end.

Then I'd challenge you to contribute to this Free Software
project to communicate the same information in less text.

The current text has been carefully thought out to be as helpful
as possible.  But since you don't like it, you should write
something better.

  If anything should be in INSTALL then it is common problems of
  building gmp, especially issues that are specific to gmp, like
  the ABI variable.

The "ABI variable" is most certainly not a common problem.

Note that this started as a bug report that GMP incorrectly
identified a purported 32-bit computer as being a 64-bit
computer.  It was indeed a 64-bit computer.  What could have been
done better in the GMP docs to avoid that misunderstanding?

  I've been bitten by this before, so I can say I lacked the
  crucial information the first time I built gmp.
  
Before the chapter Installing GMP, in "How to use this manual",
we write:

 Everyone should read @ref{GMP Basics}.  If you need to install
 the library yourself, then read @ref{Installing GMP}.  If you
 have a system with multiple ABIs, then read @ref{ABI and ISA},
 for the compiler options that must be used on applications.

If you miss *that*, and further assume that you should skip the
ABI and ISA section just because you don't know what ABI is, then
it is a challenge to improve the manual to placate you.  Just
because you run into a specific problem that is really based in
lack of knowledge about your own computer, you cannot assume it
is common and should be on page 1 in the manual.

  - A lot of the installation section is structured for people who now
  what they are looking for. Since I didn't know about ABIs and ISAs, I
  did not read the ABI section so solve my linking problems.

If you read "ABI and ISA" in the chapter on how to install GMP,
and don't know what it is, shouldn't you be reading exactly
*that* text???  It seems safe to assume it is important (in
particular as we point to it from even more prominent parts of
the manual).

Rather than skipping what you don't understand, I think the
opposite approach is better; read what you don't understand and
skip what you already know.

  Furthermore, the platform specific notes for Sparc start off
  performance of sparcv8 vs. superspace and 'Sparc App Regs'. The
  latter begins by talking about registers being clobbered. This
  information can be at the end of the paragraph in parenthesis
  (for the curious); the paragraph should start off by describing
  the symptom of the problem. I concur with Graham that there is
  nothing on Sparc and the ABI in the platform specific section
  (version 4.1.4 of gmp). I think the writers of the install
  section should consider splitting this section into a FAQ for
  building problems and advice on improving performance.
  
Alas, I think the author of these parts of the manual did a great
job.  (I didn't write most of it, in spite of that my name is on
it, so I am not bragging...  The principal author does not want
to be mentioned as author.)

Complaints such as the ones from Graham are hard to deal with,
since it is clear he didn't bother to really read ever the first
few pages of what we've written.  And he didn't say "this is not
good in my opinion, perhaps do it like this and that instead".

ABI issues are very complex, and the details are clearly beyond
the scope of the GMP documentation.  If anybody expects the GNP
manual to clarify ABI issues to some detail, they are expecting
too much from us.  We try to focus on the most important things
in the most prominent places, but we clearly don't please
everyone.

--
Torbjörn