A new FAQ (maybe)

["Dale K. Hawkins" <dhawkins teton Mines EDU>]

I have taken it upon myself to start compiling a FAQ of problems which
people seem to be having in trying to get GNOME working.  This is the very
first draft, and is not even close to being comprehensive.  But since I am
late for lunch, I fling it your general direction.  Please send me
feedback so that I can include it in the document.  I have be wanting to
contribute the GNOME for a long time now, be just have not had the time.
I still don't but...

Anyway, enjoy, correct, and flame to hearts content.

-Dale K. Hawkins

To hack, is to live.
-- DKH

With the mochas, he was strong.

Beer is proof that God loves us and wants us to be happy.
-- Benjamin Franklin

   Dale K. Hawkins        ||   Your work, no matter how brilliant,
   dhawkins@Mines.EDU     ||   becomes valuable to others only in
   To Hack, is to Live!   ||   so far as you communicate it to them.

The GNOME-CVS compile FAQ
Dale K. Hawkins (dhawkins@mines.edu)
Version: 0.0.0

0.0  Abstract
This document list some of the most common challenges to getting GNOME
to compile.  It is a compilation of my experiances plus problems which
I have seen on the mailing list.  The purpose of this document
(forgive me if I am too blunt) is to reduce the number of repeated
posting of the same problems over and over, which is flooding the list 
with more traffic than I can possibly read.  Please read, correct,
contribute, mangle, deface, and ridicule this document as you see
fit.  My intent was just to get the ball rolling, not to write the
definitive guide.

NOTE 1: I am not an expert when it comes to GNOME/GTK or any other part
of the real work, I just wrote this out of sympathy for people trying
to get GNOME to compile.  (I have been fighting to compile programs on
strange platforms for years, GNOME was relatively easy thanks in part
to the use of the auto* utilities and the patients of those on the
mailing list.)

NOTE 2:  This document should be re-written in docbook,
the standard GNOME documentation format.  I have written some things
in linux-doc (using the sgml-tools package) but do not have access to
docbook (yet).

NOTE 3:  Much of the credit for this document should go to the people
who have been kind enough to answer everyone's questions in the
mailing list.  I have just been lurking around collecting answers.

1.0  Introduction

GNOME is cool!  This is the most important thing to remember when
trying to get the sucker to compile.  Just keep that thought in mind
when you become frustrated, confused, etc.  GNOME is worth it.

The second thought to keep in mind is that GNOME is in development.
Thus you should not be surprised if something is broken or does not
even compile.   This is one of the disadvantages of the "Bazaar" methodology
<http://sagan.earthspace.net/~esr/writings/cathedral-bazaar/>.
Yet, this also means the latest and greatest versions are always at
your fingertips.  This balance is commonly know as the "bleeding
edge".  Proceed at you own aggravation.

2.0  Getting Started (with the CVS distribution of GNOME)

Step number one is to get yourself a piping hot copy of the CVS
repositiory.  (Careful not to smear the electrons before they've had a
chance to dry ;-) ).  You should refer to
<http://www.gnome.org/software/anoncvs.shtml> for the instructions on
this, but I have reiterated the key points here (actually, this is
pretty close to a verbatim copy):

---------8<----------

# tell cvs where to find the files (this points to a cvs server)
export CVSROOT=':pserver:anonymous@cvs.gimp.org:/debian/home/gnomecvs'

# login to the cvs server (when prompted for a passwd just hit return)
cvs login

# checkout a fresh copy (you should only need to do this once for each
# module.  After that use "update" instead.
# Note the '-z9' option.  This turns on compression to reduce the
# required bandwidth.
cvs -z9 checkout gnome-core

# update a directory which has been previously checkout
cvs -z9 update -d

--------->8----------

2.1  Deciding on which modules to get

Here is the break down on modules and the dependancy as near as I can
figure out (praise-be-unto-xemacs and especially picture mode!):

		 libgr           gtk+
		   |              |
		    \-----\ /----/ \----\
		           |    	 |
		         imlib           |
       	       	       	   |            mico
		       gnome-libs        |
			   |         	 |
			    \------\ /---/
			            |
			        gnome-core

(This is just a start on the full diagram.  Please send me more info
on what goes where. -DKH)

2.2  Where to get the external packages

(This section will list where packages which are needed by GNOME but
not part of GNOME can be found, e.g., libpng, guile, etc.  I think
that most of this is address at www.gnome.org, but it should be here
to make the document complete.- DKH)

3.0  Preventative Medicine

(This section should attempt to prevent many of the pitfalls described
later on, such as how to compile mico correctly the first time, i.e.,
"-with-gtk" instead letting people compile it wrong the first time.
-DKH)

4.0  Common problems

This is the meat of this document.  This is a list of problems which
plagued me and seem to be shared by a number of individuals.

4.1  Compiling Problems

Please make sure that your libraries are up to date before attempting
to compile GNOME.

4.1.0  Common problems

+ With some Red-Hat distributions /usr/X11R6/lib/libz.a seems to cause 
  problems.  The fixes are:
  - preceed "-L/usr/X11R6/lib" with "-L/usr/local/lib" for the
    packages which fail, or
  - remove that library (can someone confirm this, as I do not use Red 
    Hat - DKH)

4.1.1  gnome-libs

+ Problem: Apparently missing po/gnome-libs.pot.

  Cause: This file is created using the xgettext program.  You
  xgettext is broken or missing.

  Solution:  A) install xgettext, or 
    B) ./configure --with-included-dgettext (is this correct? - DKH)

+ Problem: Undefined reference to 'argp_state_help' when compiling
  libgnome.

  Cause: Not linking with the all the necessary libraries.

  Solution: This needs to be linked with libgnomesupport (but I am not 
  sure of the best fix for this situation).

+ Problem: autogen is complaining about AM_PATH_GTK.

  Cause: you used different --prefix values when installing GTK+ and
  automake.

  Solution: link gtk.m4 to the real aclocal directory
  (<prefix>/share/aclocal/). 

4.1.2  gnome-core

+ Problem: The linker complains about not finding the mico libraries,
  but it seems to be looking for the wrong version.

  Cause: The version for mico is hardcoded in panel/Makefile.am.  This
  causes problems when trying to link.

  Solution: for now just change the verion variable (MICO_VER) to be
  the same as your library.

+ Problem: When linking the panel, there are undefined references to
  the iostream functions, etc.

  Cause: This is because libtool is using gcc to link C++ code which
  prevents linking with the C++ libraries.

  Solution: The quick fix is the change the LINK variable to force
  libtool to use CXX instead of CC.

4.2  Runtime Problems

+ Problem: the infamous *Bad Match* error.

  Cause: the is a bug(?) in early version of gdk_imlib when dealing
  with multi-depth displays (?).

  Solution: checkout a new imlib from the CVS repository.