[GRASSLIST:4252] Re: compiling Grass5pre5 on Cygwin

[Glynn Clements]

Thomas Dewez wrote:

> By the way, what is the difference between a header file (which is what the
> include is all about, right?) and the library proper. What sort of file
> should the include and library folder contain?

An include (aka header) file is a text file, containing C souce code,
which is intended to be merged into a C source file with the #include
directive. Such files normally have names ending in ".h", and
typically reside in a directory named "include", or a subdirectory
thereof.

A library is a binary file, containing machine code and/or data. 
Libraries typically have names ending in ".a" ("archive"), ".so"
("shared object"), ".sa" ("shared archive"), or ".dylib" ("dynamic
library"), and typically reside in a directory named "lib", or a
subdirectory thereof.

The library is the actual code. The header files contain declarations
and definitions which are required in order for other code to make use
of the functions which the library provides.

Note that, if a program uses dynamic (aka shared) libraries, the
libraries must be installed in order to actually run the program. 
OTOH, headers and static libraries are only needed to compile the
program. Consequently, headers and static libraries are often packaged
separately from dynamic libraries. E.g. for RedHat Linux, the shared
PNG library is in the "libpng" RPM, while the headers are in the
"libpng-devel" RPM.

> > Use the appropriate --with-<package>-includes and/or
> > --with-<package>-libs switches.
> 
> Is it the same thing to do
> --with-<package>=no
> and
> --without-<package>
> 
> In english, it sounds very much the same but it may not be the same in
> "computer" language.

Yes; "--without-<package>" is equivalent to "--with-<package>=no", and
"--with-<package>" is equivalent to "--with-<package>=yes".

> > Note that the "assumed" paths are those which are assumed by the
> > compiler (for includes) and linker (for libraries). The exact paths
> > depend upon the compiler or linker; however, includes which are in
> > /usr/include and libraries which are in /lib or /usr/lib should be
> > found automatically. Files which are in any other directories won't
> > normally be found without the addition of the appropriate switch.
> 
> Is there a way to be systematic about checking the default paths? Are they
> listed somewhere? Would this be a good idea to have such look-up file setup
> so that the ./configure command does not span 10 lines and take ages to
> adjust? I say this innocently, not knowing how effort is necessary.

The problem is that the locations vary so much. The only thing of
which you can be sure is that a file is wherever somebody decided to
put it, which doesn't tell you anything.

If you build a package from source, you normally get to choose where
the files go. There is normally a default location, but this can vary
between versions, and the person performing the build can (and often
will) override it.

If you obtain a pre-compiled package from your OS vendor, the files
will be wherever the vendor thinks that they ought to go, and
different vendors have different ideas about what makes sense.

Example: my configure command uses the following path switches:

	--with-dbm-includes=/usr/include/gdbm
	--with-postgres-includes=/usr/include/pgsql
	--with-freetype-includes=/usr/X11R6/include/freetype2
	--with-freetype-libs=/usr/X11R6/lib
	--with-gd-includes=/usr/local/include
	--with-gd-libs=/usr/local/lib

1. The DBM headers are in /usr/include/gdbm rather than in
/usr/include. This is because the various *dbm libraries (dbm, ndbm,
gdbm) all try to be backward compatible with previous versions, while
adding new functionality. The result is that it's not uncommon to have
multiple files called dbm.h, and they can't all live in /usr/include.

2. The PostgreSQL includes are in /usr/include/pgsql because there are
quite a lot of them, and some of them have names which are somewhat
generic (e.g. config.h), and so could conflict with similarly-named
headers from other packages.

Ideally, when a package has lots of public header files, it makes the
directory part of the "official" name of that header. E.g. for X
headers, the "X11" directory is part of the name, i.e.

	#include <X11/Object.h>

The same principle applies to sub-packages, e.g. the Athena widget set
is in the "X11/Xaw" subdirectory, so headers are accessed using:

	#include <X11/Xaw/Scrollbar.h>

This way, so long as the X11 subdirectory is itself in a standard
directory (most distributions have a symlink from /usr/include/X11 to
/usr/X11R6/include/X11), all X headers are accessible without any
additional switches.

Unfortunately, the PostgreSQL developers haven't done this. It isn't
something that GRASS can do, because:

a) The name of the subdirectory isn't standardised. RedHat 6.2. calls
it "pgsql", Cygwin calls it "postgresql".

b) Some PostgreSQL headers include other PostgreSQL headers, and they
don't include the subdirectory. E.g. libpq-fe.h contains:

	#include "postgres_ext.h"

which will only work if postgres_ext.h can be found in the compiler's
include path. Which means that, if these files aren't directly in
/usr/include, then whatever subdirectory the package supplier chose
has to be explicitly added to the compiler's include path.

3. My copy of the FreeType2 library is the one which is bundled with
XFree86 4.x, so it's under /usr/X11R6. If an OS vendor supplies a
distinct FreeType2 package, it would normally live in the standard
places (headers in /usr/include, library in /usr/lib), so no switches
would be necessary.

4. The --with-gd-{includes,libs} switches are necessary because I want
to use the (beta) GD 2.0.1 library which I've compiled and installed
in /usr/local/{include,lib}, rather than the GD 1.3 library which came
with RedHat 6.2 and is installed in /usr/{include,lib}.

Case 4 provides an illustration of one reason why configure sometimes
has to be explicitly told where to find headers and libraries. If it
looked in /usr/{include,lib}, it would find GD headers and a library. 
If it looked in /usr/local/{include,lib}, it would find also GD
headers and a library. But there's no way that it could decide for
itself which copy to use.

Another situation is that a system could include commercial libraries
with a restrictive license regarding their use. In such a situation,
you wouldn't want configure to find them.

A major part of the problem is that it's *much* simpler to start with
a minimal search path and allow the user to explicitly expand it than
to start with a more "promiscuous" search path and force the user to
add switches (maybe lots of switches) to say "don't look in directory
X for package Y".

The net result is that most users have to add a few switches for
specific libraries, but nobody gets totally stuffed. The previous
misguided attempt at guessing paths saved a small amount of effort for
a lot of single-user-Linux-PC systems, at the price of totally
stuffing some users; IIRC, mostly either academic institutions (which
are relatively more important than a single end-user), or developers
(which are also relatively more important than a single end-user).

Path guessing is basically a form of DWIM ("do what I mean", as
opposed to "do what I say"). DWIM is one of those things that often
seems like a good idea at the time but, in practice, actually tends to
result in people screaming "that's *not* what I meant" at their
monitors.

> Finally, I seem to be turning a lot of options off where the compiler cannot
> find them. Recently, Markus (I think) mentioned where fftw was used. Would
> it be a good idea (unless it exists already somewhere) to have systematic a
> list of modules that use such and such libraries so the user can decide
> whether it is clever to turn them on or off?

REQUIREMENTS.html gives most of the details, but it isn't entirely
accurate (e.g. for FFTW, it mentions i.fft/i.ifft, but not i.zc,
r.surf.fractal or i.shape).

-- 
Glynn Clements <glynn.clements at virgin.net>