GARNOME FAQ
-----------

    BASIC QUESTIONS:
    ----------------
    
    1. Can I install GARNOME without breaking my current GNOME setup?

       Sure, that's part of what GARNOME is for! By default, it will
       install to ~/garnome/ and not effect any of your existing GNOME
       packages. It may affect your configuration files though, so you
       ought to back them up or use a totally different user to run
       GARNOME.

    2. Can I install GARNOME over the top of my existing GNOME setup?
    
       You could, but you shouldn't! (and we won't support you if you do)
       
       GARNOME isn't a package based setup, it installs from GNOME tarballs
       with patches. If you install GARNOME into /usr (for example), you will
       overwrite your system setup with the software we provide.
       
       All of your configuration will be overwritten, all of your settings
       could vanish, all of the development libraries will be installed and
       you will destroy any knowledge your packaging software (RPM, dpkg, etc)
       has about your setup.
       
    3. How long does GARNOME take to build?

       On a Pentium III 1800, 512MB RAM system, building the GARNOME
       2.8.0 desktop/ directory with time(1) returns:
       real 93m26.111s
       user 48m10.224s
       sys 9m6.119s

       On a Celeron 666 with 128MB RAM, the same install takes:
       real 341m40.180s
       user 225m11.216s
       sys 35m1.111s

    4. Can I speed up my GARNOME build?
    
       Yes.
       
       You can use ccache to speed up your GARNOME builds, although this 
       procedure requires additional disc space in your GARNOME build 
       directory.
       
       Using ccache is a three step task, first you need to install 
       'bootstrap/ccache', then set your cache sizes, then configure your 
       gar.conf.mk file to use the cache.
       
       GARNOME will require a different size cache depending on what parts 
       of it you choose to build, however, for best results -- setting your 
       cache size to 2GB by typing:
       
       ccache -M 2G
       
       Will be sufficently large to build all of the standard platform/ and 
       desktop/ garballs.
       
       Once you have installed the software and set your cache size correctly, 
       open the gar.conf.mk file in the main GARNOME directory and uncomment 
       the lines relating to building with ccache.
       
       note: If you are building bootstrap/mozilla, we recommend you make your 
       cache size 3GB -- otherwise, your cache may resize itself during the 
       build, which may evict some of the more important components of your 
       cache, slowing your build down.

    5. Can I optimize my GARNOME build?
    
       Yes.
       
       Open the gar.conf.mk file in the main GARNOME directory and
       look for the CC, CXX and CFLAGS lines -- uncomment these and
       specify the flags that you need.
       
       note: the best way to get a set of CFLAGS that will work with
       your configuration is to use the cpucaps[7] program from the prompt,
       you should see a line that says:
       
       "Recommended gcc (version) target"
       
       Uncomment and replace the CFLAGS line with the suggestions from that
       line and restart your GARNOME build.
       
    5. How much space does GARNOME require to build?

       On an x86 system, GARNOME 2.12.0 (desktop category and its dependencies)
       requires 2.5GB as build space (plus an additional 1GB if you are
       building bootstrap/), however it only occupies 650MB once installed.
    
    PRE-CONFIGURATION QUESTIONS:
    ----------------------------
    
    1. GARNOME always fails on the checksums, are my tarballs broken?

    Are you using GNU tools? Sometimes Sun's md5sum doesn't agree with
    GARNOME's stored md5sums.
    
    You can change the program used to calculate the md5sum's by editing
    your gar.conf.mk file and altering the $(MD5) variable.

    2. What is bootstrap/ for?

    Please press 'Page Up' a few times and read the section entitled:
    'An IMPORTANT note about bootstrap/'
       
    BUILD QUESTIONS:
    ----------------
    
    1. My build fails with:
    
	"checking mach-o/dyld.h usability... no
	 checking mach-o/dyld.h presence... no
	 checking for mach-o/dyld.h... no
	 configure: error: No dyld.h found, can not continue
	 make[1]: *** [configure-work/main.d/dlcompat-20030629/configure] Error 1"

    You are trying to compile dlcompat from bootstrap/ when you shouldn't be.

    Please press 'Page Up' a few times and read the section entitled:
    'An IMPORTANT note about bootstrap/' -- then type 'make install' from the
    desktop/ directory.

    2. My build fails in platform/glib with:

	"gconvert.c:47:2: #error GNU libiconv not in use but included iconv.h 
	is from libiconv"

    You are trying to compile libiconv from bootstrap/ when you shouldn't be.

    Aside from pressing 'Page Up' a few times and reading the section
    entitled: 'An IMPORTANT note about bootstrap/' -- you have three options:
    
    a) delete iconv.h from your GARNOME prefix and continue your install
    b) ensure your system includes path is before your GARNOME includes path
       (usually not a good idea)
    c) uncomment the libiconv dependancy in the platform/glib Makefile, 
       and 'make clean; make install' (only worth doing if you're on non-GNU
       systems)

    3. My build fails in desktop/control-center with:
    
	"/home/ubuntu/garnome/lib/libgtk-x11-2.0.so: undefined reference to `g_key_file_get_integer'
	/home/ubuntu/garnome/lib/libgnomevfs-2.so: undefined reference to `g_key_file_load_from_file'
	/home/ubuntu/garnome/lib/libgtk-x11-2.0.so: undefined reference to `g_file_set_contents'"
	
    You are trying to compile on a system that includes pesky .la files.
    
    Some distributions install helper files with their development packages
    (Debian, Ubuntu, Arch Linux, earlier Slackware's) that have hardcoded
    references to libraries in system directories. 
    
    Libtool then may choose to use the information from these files instead of
    probing your system for the correct location of your files, which can cause
    some parts of the GNOME build to link against libraries that have been
    supplied with your system, rather than those that work with GARNOME.
    
    A workaround for this issue has been included with 2.12.0, however -- if
    you find that the problem still comes up, please report it as a bug to
    your distribution.
    
    You can also see: 
    
    http://mail.gnome.org/archives/gtk-devel-list/2003-November/msg00107.html
    and: 
    http://lists.x.org/archives/xorg-modular/2005-April/000063.html 
    
    for more information on this issue.
    
    4. My build fails in platform/libgnomeprint with:

	"checking for libgnomecups-1.0 >= 0.1.0... 
	Package libgnomecups-1.0 was not found in the pkg-config search path.
        Perhaps you should add the directory containing `libgnomecups-1.0.pc'
        to the PKG_CONFIG_PATH environment variable
        No package 'libgnomecups-1.0' found"

    If you have CUPS installed as the printing environment on your machine, you
    should install the geektoys/libgnomecups package, which will solve this 
    problem.

    5. My build fails in desktop/epiphany with:

	"configure: error: Library requirements (mozilla-gtkmozembed) not met; 
	consider adjusting the PKG_CONFIG_PATH environment variable if your 
	libraries are in a nonstandard prefix so pkg-config can find them."

    You don't have a suitable version of Mozilla installed on your system, 
    Epiphany and Galeon need Mozilla 1.7 or later to install correctly.

    To solve this issue, you have two options:

    a) install the relevant mozilla development packages for your system and 
       continue your install
    b) uncomment the bootstrap/mozilla dependancy in the desktop/epiphany 
       Makefile, then run 'make clean; make install'

    If you choose option b), then you need to add the mozilla libraries
    installed in $GARNOME/lib/mozilla-<version> to your LD_LIBRARY_PATH,
    otherwise Gaim and Evolution will not compile for you.

    6. My build fails in desktop/nautilus with:
    
        "nautilus-image-properties-view.c:134:96: macro "exif_content_get_value" passed 4 arguments, but takes just 2
	nautilus-image-properties-view.c: In function `exif_content_callback':
	nautilus-image-properties-view.c:134: `exif_content_get_value' undeclared (first use in this function)
	nautilus-image-properties-view.c:134: (Each undeclared identifier is reported only once
	nautilus-image-properties-view.c:134: for each function it appears in.)
	make[6]: *** [nautilus-image-properties-view.lo] Error 1"

    You are probably trying to compile nautilus with the libexif 0.6.x specific 
    patch.

    You should edit the desktop/nautilus Makefile and comment out the PATCHFILES 
    line, before running 'make clean; make install' in the nautilus directory.
 
    7. My build fails in desktop/gnome-games with:
    
        "/usr/bin/ld: cannot find -lguile-ltdl
	collect2: ld returned 1 exit status"
	
	or:
	
	"cscmi.o(.text+0x2b8): In function `add_slot':
	: undefined reference to `SCM_CHARS'
	cscmi.o(.text+0x2de): In function `add_slot':
	: undefined reference to `SCM_CHARS'
	collect2: ld returned 1 exit status"
	
    You are probably trying to compile gnome-games with either a 1.7.x
    'preview release' version of guile, or a version of 1.6.x that has been
    compiled with the '--disable-depreciated' flag.
    
    As stated by the upstream bug[5], to fix this, you will either need to 
    obtain a fixed version of guile from your upstream vendor, or download 
    and compile guile from CVS yourself.
 
    8. My build fails with: 
    
	"/usr/bin/install: cannot stat `./html/index.sgml': No such file 
	or directory"
    
    There are two solutions, in order of "most correct" to "quickest":

    a) Find out why gtkdoc-mkdb is failing. It's usually a b0rked or
       non-existant docbook-dsssl install.
    b) In gnome/category.mk, change --enable-gtk-doc to
       --disable-gtk-doc. Run make clean and make install again.

    If you install the correct software however, or help port our
    documentation from SGML to XML, you will never have this problem
    again. They have to be the best solutions, really. :-)

    9. Scrollkeeper seems to hang when running scrollkeeper-update.

    Yes, it's okay. You just have to wait a while for it to finish
    processing (sometimes a long while). Nothing to be alarmed about.

    10. My gnome-session and Nautilus segfault immediately, what's wrong?

    See [6]bug 70351 at bugzilla.gnome.org.

    11. GARNOME fails to build [insert failure here] on Debian Potato
    
    Mostly, these errors are due to GCC 2.95 incompatibilities.
    
    Again, ranging from "most correct" to "quickest" -- your solutions are:
    
    a) File a bug against the package in question and make sure the 
       [2]Mailing List is on the CC list so that we can pick up any patches
       that may appear.

    b) Install GCC 3.2.3 or later from Debian Testing
    
    12. GARNOME fails to build [insert failure here] on Red Hat 7.3, 8, 9, EL3
    
    There are some components that fail to build in Red Hat, the two main
    issues are:
    
    * OpenSSL / Kerberos
    
    These packages are both affected by Red Hat's packaging of OpenSSL and the
    Kerberos 5 libraries. According to [7]this post -- Red Hat's opinion seems
    to be a need to have these packages require pkg-config. Unfortunately, 
    some earlier OpenSSL installations don't have the .pc support for
    pkg-config niceness, so hacking the GARNOME makefiles to support .pc files
    _might_ work, but you may need to do post-OpenSSL-buggery if your
    distribution is RH7.3, 8 or an unpatched version of 9.
    
    Thus, none of the solutions are particularly "clean" -- but in a pinch:
    
    a) exporting a PKG_CONFIG_PATH variable that points to your GARNOME install
    _before_ the system path ('PKG_CONFIG_PATH=/home/pd/lib/pkgconfig:/usr/lib')
    
    b) Adding the krb5 directory (--with-krb5=/usr/kerberos) 
    to the configure arguments in the Makefile in both the 'office/evolution',
    'office/ximian-connector' and 'fifth-toe/gaim' directories.

    * Binutils (RH9 only)
    
    Red Hat 9 refuses to build 'ghex' because the ghex build doesn't recognize
    'libbfd-2.13.90.0.18.so' as a valid linkable library. Adding a symlink
    from '/usr/lib/libbfd-2.13.90.0.18.so' to '/usr/lib/libbfd.so' is the
    easiest fix for this issue.

    POST-INSTALL QUESTIONS:
    -----------------------

    1. I can see icons on my desktop, but no fonts?
    
    You will need to build freetype, xrender and xft from the bootstrap/
    directory, then restart your GARNOME session to have fonts displayed
    correctly.
    
    2. I can see fonts on my desktop, but no icons?

    You need to build hicolor-icon-theme and shared-mime-info from the
    bootstrap/ directory and add (if it doesn't exist) the XDG_CONFIG_DIRS
    line to your GARNOME startup script.
    
    Note: as of GARNOME 2.10, you need to run some additional commands to
    get this to work as expected -- after adding the required lines,
    run (from the prompt):
	  
    $GARNOME/bin/update-desktop-database
    
    and then:
    
    $GARNOME/bin/update-mime-database $GARNOME/share/mime
    
    Then restart your GARNOME session to get your icons and associations
    back on track.
    
    3. How do I use anti-aliased fonts?

    Set the GDK_USE_XFT environment variable. eg.: export GDK_USE_XFT=1

    4. Where did my evolution/ directory go?

    As part of the upgrade to Evolution 2.2, the import wizard will copy
    your Evolution directory to ~/.evolution.
    
    The GARNOME maintainers recommend you keep a copy of your existing
    ~/evolution directory (if it exists), until you decide that you
    no longer need it.

    5. Who do I talk to about GARNOME?

    Join our [2]mailing list, or visit #garnome on irc.gnome.org.

References
----------

   1. http://www.lnx-bbc.org/garchitecture.html
   2. http://mail.gnome.org/mailman/listinfo/garnome-list
   3. http://mail.gnome.org/archives/garnome-list/
   4. http://cipherfunk.org/garnome/
   5. http://bugzilla.gnome.org/show_bug.cgi?id=164522
   6. http://bugzilla.gnome.org/show_bug.cgi?id=70351
   7. http://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=82369
   8. http://members.jcom.home.ne.jp/jacobi/linux/softwares.html

