Re: GNUstep Build Guide and other documents

[Richard Stonehouse]

Hello Dennis,

> > Checking the version numbers of installed software, I couldn't get some
> > of the more complex tests to work (the ones that do "strings `gcc
> > --print-file-name=...").
> 
> What is the problem? Doesn't the Red Hat compiler return the right files
> when doing gcc --print-file-name=...
> Or are there problems in getting the version-numbers from the
> libraries...?

Taking the command verbatim from the build guide:

    $ strings `gcc --print-file-name=libgmp.so` | grep -e
\^[[:digit:]].[[:digit:]].[[:digit:]]$

I get:
    
    strings: libgmp.so: No such file or directory
    
But if I do:
    
    $ locate libgmp.so
    
I get:
    
    /usr/lib/libgmp.so.3.3.0
    /usr/lib/libgmp.so.3

So then I try:
    
    $ strings `gcc --print-file-name=/usr/lib/libgmp.so.3` | grep -e
\^[[:digit:]].[[:digit:]].[[:digit:]]$

and

    $ strings `gcc --print-file-name=/usr/lib/libgmp.so.3.3.0` | grep -e
\^[[:digit:]].[[:digit:]].[[:digit:]]$

both of which produce no output - just come straight back to a shell prompt.

> > On an RPM-based system such as Red Hat, an alternative way of getting
> > version numbers is (e.g.):

<snip>
 
> Yep, I know, but that I am trying to find a generic way of detecting a
> library version that works on every system. Even the ones that have
> installed libraries from source.

This was just a suggestion, not a big thing. Probably an issue to me
because of the apparent complexity of the methods suggested, from a
user's (not a developer's) point of view. I can imagine other naive
users of Red Hat, Mandrake, Suse etc saying "what are these strange
incantations? Why can't we just do it the way we're used to?" Perhaps
worth considering a "note to RPM users".

> >  - the web-site pages tell a slightly different
> >    story from the build guide; they ought to be
> >    brought into line.
> 
> There are always various ways that lead to a solution.

This is more significant and I'll try to explain why - the reasons
underlie some of my other points too.

Although my recent GNUstep build went smoothly, the previous one - back
in the summer - was fairly horrendous. The problem was almost entirely
in finding a set of software that would build together successfully.
Even on this recent occasion, it took over half an hour of online
connect time to pull together the list of software I needed (this
doesn't include the download time).

Both then and now, I read both the Build Guide and the GNUstep web-site
pages (the ones that list pre-requisites, GNUstep core etc). I also
referred to the ftp site indexes. This was because the Build Guide:

  - only covers the unstable versions but,
    as a non-developer, I feel safer going for
    the stable versions; and
  
  - doesn't cater for the mirror sites - see
    below for why I wanted to use them.

Also, of course, if alternative sources of information are available,
one tends to go through them all as a double-check.

Correlating information from these three sources, I found:

  - the required versions of software differ, for
    example the build guide specifies gcc 3.2 but
    the web pages still only require gcc >= 2.8.0
    (and, as I found to my cost in the summer, give
    no hint of the compatibility problems between
    versions of gcc, binutils and other things!);
  
  - some of the terminology differs, with different
    names being used for the same things - this may
    seem trivial but it can be very confusing for
    the novice;
  
  - the categories used are different - for example
    the Build Guide has a "Building Extensions"
    section, which refers to items found on three
    different pages of the web-site - another
    example is ffcall; and
  
  - within categories, the sequence of items differs
    (minor problem).

So making sure you've identified everything you need, and found out
where it is, gets a bit messy and time-consuming.

What I'd suggest is to bring the web-site pages into line with the Build
Guide, as shown in the example referred to below.

> >  - it will be very hard to keep the build guide
> >    up-to-date with changing versions of software;
> >    suggest version numbers should be removed from
> >    the build guide and reference made to a
> >    summary table in the web pages.
> 
> 
> What do you mean by this. One single chapter that sums every package and
> its download source?

What I had in mind was a separate, short page, linked to from the Build
Guide. This would give the version numbers - possibly as a table. When
they changed, you would just need to update that rather than trawling
right through the Build Guide and updating it.

Another way would be to have the version numbers in a database, and use
a CGI script to insert them in the Build Guide when the user opens it.
Not sure how to do CGI scripts though!

> >  - it got a bit confusing trying to correlate
> >    information from different web pages; would
> >    be better if all the version and download
> >    information (pre-requisites, GNUstep core,
> >    applications etc) were on a single page,
> >    albeit a long one.
> 
> See above.

This ties in with the last point but one.

> >  - I also got a bit confused between stable and
> >    unstable versions, which are listed in the
> >    same column of the tables; might be better to
> >    have two columns side by side, one for the
> >    stable and one for the unstable versions.
> 
> I totaly agree and am still thinking about a good way to solve this. I
> might have figured it out, but I need some time to implement it and see
> if it makes things more clear. But it is a good and valid point.

The example below shows a possible two-column approach.

> >  - I got lost looking for mirror sites and found
> >    myself trawling through the GNU mirrors instead
> >    of the GNUstep mirrors; there seems to be a
> >    misleading reference somewhere.
> 
> 
> I don't understand this one. I try to always supply the direct source,
> never mentioning any mirrors...

I use mirrors because:

  - it's presumably better to use a local mirror than
    a distant direct source;
  
  - US-based servers are often congested when I do my
    downloads - generally the evening (UK time) which
    is daytime in the USA;
  
  - the GNUstep server is rather slow and/or congested.

> > Don't know if the above makes sense; if it would help, I could put
> > together a mock-up of the sort of thing I have in mind and put it up on
> > the web.
> 
> Might be an idea. Maybe it would help me in detecting where you want
> more or better or clearer information.

For a mock-up of some possible approaches, see:

    <URL:http://www.rstonehouse.co.uk/extras/gs-versions.html>

What I've done is take the existing web-site pages, merge them and
revise them to match the Build Guide:

  - The division into categories, and the
    order within categories, follows that
    of the Build Guide.

  - The items in the "Sources" column provide
    links to the relevant entries in the Build
    Guide. No links the other way - this would
    be hard to do if this document were to be
    generated by a CGI script (see below).
  
  - Versions required for "Stable" and "Unstable"
    builds are shown side-by-side, and colour-coded.
    (Presumably this is worth doing even for
    pre-requisites, as "Stable" and "Unstable"
    could require different versions of e.g. gcc
    if a newer version breaks backward compatibility?)
  
  - These versions are also links to the software
    items to download (not sure about this - it
    may be overloading them too much!).
  
  - URLs of GNUstep items are relative and so
    can be changed globally to a mirror site,
    simply by changing the '<base href=...>'
    tag in the page header. This could be done
    by a CGI script invoked from a "select
    mirror site" page.

This is simply an illustration, not a polished product!

-- 

    Richard Stonehouse