[BuildTools] Header files, Documentation

[Lou Hafer]

Kipp,

	I can take a stab at some of this; Ted and Stefan can fill in a bit
more.

> What happened to $(COINUTILSSRCDIR)????

	Answer on two levels. First, for the file you were looking at
(CoinUtils/test/Makefile.am), it makes sense to give a relative location
for the headers. If you're building in the test directory, the headers
are in ../src. If you're doing a VPATH build, you need to know where the
source directory is, then a relative path, hence $(srcdir)/../src. The
rule to remember is that srcdir is the source for the directory you're
building. When you're building the test directory, srcdir resolves to
the source for test.

	More generally, what happened to COINUTILSSRCDIR? A short but somewhat
misleading answer would be `It's been replaced by COINUTILS_CFLAGS'. But
a longer answer may give you a better perspective.

	It's been replaced by pkg-config, and a whole bunch of buildtools
macros that query pkg-config and deal with the situation when pkg-config
isn't available (I'll let Stefan speak to that). If you want to know the
header directories for CoinUtils, you ask

  pkg-config --cflags coinutils

and pkg-config consults coinutils.pc to give the answer (correct for my
particular configuration)

-I/devel/Coin/Split-FedGCC64/include/coin
-I/devel/Coin/Split-FedGCC64/include/coin/ThirdParty

These are the places to look for the installed headers for CoinUtils and
Glpk in my local build structure. Notice that pkg-config is helping me
here, keeping track of the fact that my CoinUtils build brings in glpk.
To get the libs needed to link against libCoinUtils,

  pkg-config --libs coinutils

gives

 -L/devel/Coin/Split-FedGCC64/lib/coin  
 -L/devel/Coin/Split-FedGCC64/lib/coin/ThirdParty -lCoinUtils -lbz2 
 -llapack -lblas -lm -lcoinglpk -ldl -lgmp -lz

So you can see why this simplifies things in the makefiles. When you're
building against uninstalled packages pkg-config needs to find
coinutils-uninstalled.pc. Again, the buildtools macros take care of
this, manipulating PKG_CONFIG_PATH so that pkg-config can find the
right .pc file.

You can ask for information about more than one package, e.g.,

  pkg-config --cflags coinutils osi cgl

and you'll get the combined information for all, duplicates removed:

  -I/devel/Coin/Split-FedGCC64/include/coin 
  -I/devel/Coin/Split-FedGCC64/include/coin/ThirdParty
  
If you're saying `but that's exactly the same as the previous answer',
you're exactly right. All the installed header files are in one place.
You don't get the same information repeated three times (for CoinUtils,
Osi, and Cgl). So when configure.ac uses

AC_COIN_HAS_PACKAGE(CoinDepend, [cgl osi coinutils = trunk], [CbcLib
CbcGeneric])

what will happen is that buildtools creates a variable,
COINDEPEND_CFLAGS, and this is set to the output of

  pkg-config --cflags cgl osi coinutils

(with some fussing to make sure it's the trunk of coinutils).
COINDEPEND_CFLAGS will be added to command lines when building CbcLib
and CbcGeneric.

	Hope this helps. There's nothing quite so frustrating as finding
yourself afloat in an unfamiliar sea.

						Lou