This page is Outdated.
[Chema Celorio, Dec 2002]

Compiling GNOME projects from sources FAQ.

This is an attempt to write a FAQ for compilation questions
for GNOME projects. What i plan to do is compile the answers to
the compilation questions asked in irc or mailing lists over here.

1 - Basic compilation questions
3 - gnome-config, pkg-config and foo-config scripts.
4 - Developer info
5 - Specific problems and possible solutions

I have written this FAQ from my experience and might very well be wrong
or could be missing some information, please send any comments/fixes to

Basic compilation questions

1.1- How can i compile a project from a tarball ?

After getting the tarball you need to untar it. If the tarball ends in .tar.gz
you want to do something like :

tar xzvf some_project-0.1.2.tar.gz

If the tarball ends in .tar.bz2 you need to do :

tar xvjf some_project-0.1.2.tar.bz2
(this will work with recent versions of GNU tar only)

This will unpack "some_project" version 0.1.2 into a directory named "some_project-0.1.2".
Go inside that directory and type.

./configure --prefix=/path/to/prefix

you should substitute /path/to/prefix with the prefix into which you want to install
the project. See question 2.1 regarding the PREFIX location and what is it used for.

Then type make to compile the project and make install to install the project.

So in short you need to :
a) tar xzvf some_project-0.1.2.tar.gz
b) ./configure --prefix=/path/to/prefix
c) make
d) make install

Note : many GNOME packages depend on GNU make, so if you are building on Solaris, BSD,
etc, you need to make sure that GNU make is in your PATH before the system make, or have
it installed as gmake and say "gmake" and "gmake install" instead of just make.

1.2- How can i compile a project from CVS ?

First you need to get the sources from cvs (see question 1.3). After having gotten
the sources, go inside the project directory and do :

a)./ --prefix=/path/to/prefix
b) make
c) make install

For GNOME 2.x or any later version use jhbuild
get jhbuild from cvs and read the README.

1.3- How can i get the source for a project from CVS ?

If you don't have a CVS account on the GNOME CVS you need to use anoncvs. Take a 
look at : for more info.

You might want to change your anoncvs from to a specific server.
The anoncvs are a set of servers with Round Robin DNS resolution, by adding a particular
server, you will always be updating form the same server. The servers are :, etc. So your CVSROOT might contain something like :

rather than :

1.4- How can i install the GNOME 2.0 platform ?

The easiest way to install the GNOME 2.0 platform from CVS is to use the vicious-build-scripts.
Get the "vicious-build-scripts" from cvs and read the README file inside it.

jhbuild is an improved version of the vicious-build-scripts. Works a lot better.

2. Prefix

2.1 Prefix ?

blah blah ... (explain what a prefix is and what each directory is used for bin,lib,include,share ..)

2.2 I want to install all the development code in a separate prefix inside my HOME
directory. What enviromental variables should i set to be able to compile and run
binaries and libraries from a different prefix ?

For example, to install into $HOME/gnome you need to set :
export GNOME_PATH=$HOME/gnome
export PATH=$HOME/gnome/bin:$PATH
export PKG_CONFIG_PATH=$HOME/gnome/lib/pkgconfig
export ACLOCAL_FLAGS="-I /home/$user/gnome/share/aclocal"
export ACLOCAL_AMFLAGS="-I /home/$user/gnome/share/aclocal"

and autogen/configure the projects with --prefix=$HOME/gnome	

3. Helper scripts

3.1- What are the gnome-config, pkg-config and the other -config scripts used for ?

The -config scripts are used for two things, for querying the system for the installed
version of a library and for getting the compile and link lines needed for compiling an
application that intends to use the library.

They are invaluable for debuging compilation problems since this is how the
scripts usualy query the system to know the installed version of a library and to fetch
the compile & link lines needed to compile it. It is required to have different compile
lines because the libraries are installed in a different path in each system.

There are 3 types of -config scripts, they pretty much work in the same way.

A) Library specific scripts, like gtk-config, xml-config (for libxml), glib-config, etc.

This scripts are installed by a specific library. You should avoid using this scripts
whenever possible and use a generic -config script like pkg-config. It is important to
note that the library specific scripts are beeing deprecated so some libraries may no
longer ship them.

Typing in a console :
foo-config --version (where foo equals glib, gtk, xml, etc)
will return the version of the library installed in the system. For example :

[chema@saracuatro chema]$ gtk-config --version

returns the installed version on my system, which in my case is : "1.2.10"

If you want to get the compiler string needed to compile an app with gtk, you can run the
script with --cflags as such :

[chema@saracuatro chema]$ gtk-config --cflags 
-I/usr/include/gtk-1.2 -I/usr/include/glib-1.2 -I/usr/lib/glib/include -I/usr/X11R6/include
[chema@saracuatro chema]$

Compiling a small .c file can be done in the console with :
gcc `gtk-config --cflags` -c main.c

The --libs flag works like the --cflags one with the difference that it returns the link
string needed rather than the compile string. Running gtk-confign --libs returns :
"-L/usr/lib -L/usr/X11R6/lib -lgtk -lgdk -rdynamic -lgmodule -lglib -ldl -lXi -lXext -lX11 -lm"
in my system.

You could compile and link
 a small .c file with :
gcc `gtk-config --cflags` main.c `gtk-config --libs`

which will expand in the shell to something like :
gcc -I/usr/include/gtk-1.2 -I/usr/include/glib-1.2 -I/usr/lib/glib/include -I/usr/X11R6/include main.c -L/usr/lib -L/usr/X11R6/lib -lgtk -lgdk -rdynamic -lgmodule -lglib -ldl -lXi -lXext -lX11 -lm

Summing up, each -config script should take at least 3 arguments
  --version : to fetch the version of the library 
  --cflags  : to fetch the compile string, used so that the compiler can find the #include files
  --libs    : used to fetch the link line so that the linker can link the application with the shared libraries

b) The gnome-config script. The gnome-config script which ships with gnome-libs 1.x was the first attempt
to create a generic config script. It works like the library specific strings but since it is generic,
you need to pass the library name you are interested in.

Running :
gnome-config --modversion foo
returns the installed verion of the "foo" library.

For example :
[chema@saracuatro borrar]$ gnome-config --modversion print
[chema@saracuatro borrar]$

The same holds true for the --cflags and the --libs parameters, they work like the library specific
scripts (see above). However gnome-config allows me to fetch the compile and link lines of multiple
libraries with one command. Running :

gnome-config --libs print libglade vfs

will return the compile string needed to compile an application which is linking with gnome-print
libglade and gnome-vfs.

The way gnome-config determines which compile/link lines and version of a library is installed is
by means of the files. This files are installed in $prefix/lib. Take a look at one of
this files if you want to know more about how gnome-config works internally. For example, bonobo
will install a $prefix/lib/ file.

See gnome-config --help for more info.

c) The pkg-config is the next generation of gnome-config script, it solves some problems we
found with gnome-config and also installs a set of .m4 macros that can be used in a
files in a semi-standard way.

[FIXME, talk about :
- diferences with gnome-config
- the .pc files]

4. Developer info
4.1- How should my application check for the presence and version of a shared library ?

4.2- How should my application generate the compile and link lines ? What changes should i do
to my build files in order to use a shared library ?

4.3- How can my shared library install a .pc file for pkg-config to pick it up so that
other applications can use it ?

5. Specific problems and posible solutions

5.1- I get an error message that looks like :
"aclocal: 86: macro `AM_PATH_FOO' not found in library".
What does it mean ? How can i fix this ? (Where FOO is a package name)

This means that the configure script for the package that you are trying to compile
has a reference for a m4 macro that it can't find. This macros are installed in 
$PREFIX/share/aclocal. If the error message is something like :
... macro `AM_PATH_GLIB` it means that the project you are trying to compile is trying
to call a macro that is installed with glib. You need to install the developement
package for glib, either by getting the glib-devel rpm (or .deb) or by installing glib
from sources, installing a package is recommended. The -devel packages are also
sometimes refered as SDK's.

So if you get an error for a macro :
AM_PATH_GLIB - means that you need the glib development package
AM_PATH_LIBGLADE - means that you need the libglade-gnome-devel package
AM_PATH_GTK - means that you need the gtk+-devel package
and so on ...

Now, if you have already installed the devel package or the library from source 
look for the .m4 macro at $PREFIX/share/aclocal. If you find it there you can set
your ACLOCAL_FLAGS eviromental varible to include add a path to the search path for
.m4 files like so :

export ACLOCAL_FLAGS "-I $prefix/share/aclocal"
(where $prefix is your actual prefix).

If you are still having problems after following this steps, grep for the macro 
you are looking for in the $prefix/share/aclocal dir to make sure the macro is there
and make sure "env | grep ACLOCAL_FLAGS" returns the correct directory.

5.2- I get an error message that looks like :
"./configure: line 5321: syntax error near unexpected token `PKG_CHECK_MODULES(FOO,'
./configure: line 5321: `PKG_CHECK_MODULES(FOO, somelib1 somelib2 ... somelibx)'"
What does it mean ? How can i fix this ?

This usualy means that you have pkgconfig installed in a non standard prefix and
the app you are trying to compile is attempting to use a macro provided by pkgconfig.

First, check that you have pkgconfig installed with :
"which pkg-config"
If pkg-config is not there get pkgconfig from :
and let the app maintainer know that the script should be checking
for pkg-config if he is using pkg-config macros.

If you do have pkg-config installed, set your ACLOCAL_FLAGS with :
export ACLOCAL_FLAGS="-I $prefix/share/aclocal"
where prefix is the prefix where pkg-config was installed
for example :
export ACLOCAL_FLAGS="-I /home/chema/gnome/share/aclocal"

5.3- I get an error message that looks like :
"Package libfoo was not found in the pkg-config search path.
perhaps you should add the directory containing `libfoo.pc'
to the PKG_CONFIG_PATH environment variable
No package 'libfoo' found."
What does it mean ? How can i fix this ?

pkg-config is a utility that allows the configure scripts to check for the presence
of a certain library in the system. This error message means that pkg-config could
not find libfoo installed. If libfoo is in fact installed, you need to let pkg-config
where to look for .pc files. The .pc files have the information needed by pkg-config
about the library. 

If you have the library installed in a non-standard prefix set PKG_CONFIG_PATH to
point to the location of the .pc files with :
export PKG_CONFIG_PATH=$prefix/lib/pkgconfig 
for example :
export PKG_CONFIG_PATH="/home/chema/lib/pkgconfig"

Now, if this does not fixes the problem this means that the library that we are trying
to meet the depenency for does not install a .pc file with it. In this case, pkg-config
will call the legacy config scripts to see if it can find the information it needs about
the library. If this dependency is a core GNOME library, most likely it is installing a
config file for gnome-config. Look in $prefix/lib for a file name (for example
libart installs, bonobo installs If this file is there make
sure you have your GNOME path set to the prefix you are installing to.

All libraries should install either a .pc file or a file. pkg-config looks for the
.pc file in $prefix/lib/pkgconfig and you can add a search path by setting PKG_CONFIG_PATH.
gnome-config looks for the file in $prefix/lib and it uses GNOME_PATH to search
for it.

5.4- I get an error message that looks like :
"./ltconfig: ./ltconfig: No such file or directory
configure: error: libtool configure failed"
What does it mean ? How can i fix this ?

This problem usually happens when you have upgraded to a libtool 1.4 and you still have
an older automake version, if you do have 1.4 versions of both libtool and automake this might
be caused by a inconsisten intstallation. The easiest solution is to upgrade to automake and
make sure the installation is consistent.

Upgrading to automake 1.4

Upgrading to automake 1.4 should take care of the problem. If it does solve the problem
it means that you have a problem with your installation, which usually happens when you
are installing either of this packages in a different prefix than where the older versions
where installed.

Even when the 1.4 version of the automake binary is installed and in the path, aclocal migth
still be using and old version of libtool.m4 to build aclocal.m4. Make sure that ACLOCAL_FLAGS
has the path of the .m4 macros installed by the 1.4 version of libtool and automake.

5.5- I get an error message that looks like :
"zh_TW.po:517: illegal control sequence
zh_TW.po:2010: illegal control sequence
zh_TW.po:2258: illegal control sequence"
while compiling an application inside the /po directory
What does it mean ? How can i fix this ?

It means that either you have an older gettext version than what the app requires or the .po files
where created for a older version of gettext than what you have.

The problem is that the format for .po files was changed between version 0.10.35 and 0.10.39.
So this error will occur when the application's .po file was created for a pre .35 version and
you have a post .35 version or the other way around.

An easy work around when you don't want to mess with your setup is to do:
echo "" > po/xx_XX.po for the file that is not cooperating.

5.6- I get an error message that looks like :
"/usr/bin/install: cannot stat `./html/index.sgml': No such file"
What does it mean ? How can i fix this ?

This problem is very of annoying because it is a failure in the make phase but is reported
in the make install phase. The short answer is that your doc-book installation is not complete.
If you are using debian "apt-get install gtk-doc-tools" should do it.

To fix it ..

1. Find a way to test our installation

First you need a way to test if the bug is still there as you are going to be fixing your setup.
Go to the directory where the make install problem is occuring and do a make clean and then make
again. The documentation creation process should fail, check which line is failing. For example
in glib it could be:

[chema@trunk glib]$ make
... [ More stuff that builds fine ] ....
"*** Building HTML ***
rm -rf ./html 
mkdir ./html
cd ./html && gtkdoc-mkhtml glib ../glib-docs.sgml
/usr/bin/openjade:../glib-docs.sgml:1:59:W: cannot generate system identifier for public text "-//Davenport//DTD DocBook V3.0//EN"
/usr/bin/openjade:../glib-docs.sgml:61:0:E: reference to entity "BOOK" for which no system identifier could be generated
/usr/bin/openjade:../glib-docs.sgml:1:0: entity was defined here
/usr/bin/openjade:../glib-docs.sgml:61:0:E: DTD did not contain element declaration for document type name
... [ More error follows ] ...

[You will see a lot of text scrolling in the terminal.]

The main problem here is that "gtkdoc-mkhtml glib" is not returning an error even when the
documentaion was not built. But gtkdoc-mkhtml can't generate the HTML documents, the important
error that we want to solve is the first one, the one about "system identifier for ..."

2. SGML catalogs

Most of this errors are caused by missing DTD's required to build the documentation. In the
example above the DTD with id: "-//Davenport//DTD DocBook V3.0//EN" could not be found. The
way that the templates are found is by a list of catalogs. You can set the catalog with
the SGML_CATALOG enviromental variable too, but fixing the config files is the way to go.

The way DTDs are found is by means of cascaded catalogs. It most systems (this can change) you
start off in /etc/sgml/catalog. For example, the contents of my /etc/sgml/catalog are:

CATALOG /etc/sgml/
CATALOG /etc/sgml/
CATALOG /etc/sgml/
CATALOG /etc/sgml/

This catalog does not contain any definitions for DTD but contains other catalogs. Catalog files
can contain both DTD definitions or point to other catalogs. My /etc/sgml/ file
(referenced by /etc/sgml/catalog) contains:

CATALOG /usr/share/sgml/sgml-iso-entities-8879.1986/catalog
CATALOG /usr/share/sgml/docbook/sgml-dtd-3.0/catalog
CATALOG /usr/share/sgml/openjade-1.3/catalog
CATALOG /usr/share/sgml/docbook/dsssl-stylesheets-1.64/catalog

And my /usr/share/sgml/docbook/sgml-dtd-3.0/catalog contains among lots of other
things a line that specifies where the ID that we are looking for can be found,
as such:

PUBLIC "-//Davenport//DTD DocBook V3.0//EN" "docbook.dtd"

Because the id we where looking for can be found by looking at this catalog, jade is going to be
able to build the documentation correctly.

3. Where DTD's are installed

You might allready have the necesary DTD's in your system. They are dropped all over the
place, I have been unable to figure why they are in different locations. Check /usr/share/sgml and /usr/lib/sgml to find it.

4. Getting the files needed

Jade will look in /etc/sgml/catalog and then cascade thru the list of catalogs until it
can find the definition that the documentation is referencing. If you don't have those
DTD's installed, grab the dockbook-dsssl tarball, make sure your catalogs reference it
and rejoice.

The dockbook-dssl tarball can be found here:

If after installing this files and making sure they contain the DTD's that you need you
still can't make it work, check which DTD's are needed that you are lacking and google for them.

Last update : Mon Jul 29 14:51:48 CDT 2002
Valid HTML 4.01!