
                                 GARNOME!

   GARNOME is a build utility that allows users to build the GNOME Desktop.

   Based on the GAR ports system developed by Nick Moffitt. It downloads,
   builds and installs the GNOME Desktop from the latest tarball releases.
   It also includes extra GNOME software to provide users with a comfortable
   and complete desktop environment.

What do I need to install GARNOME?
----------------------------------

   Please refer to the DEPS-LIST file for a complete list of dependencies.

How do I configure GARNOME?
---------------------------

   All the local settings are kept in gar.conf.mk. Here are the most
   useful ones:

   GARCHIVEDIR: If you've downloaded the tarball collection already,
   point this to the directory where your tarballs are. Example:

     GARCHIVEDIR = /home/gnome/download

   main_prefix: Currently the default install location is $HOME/garnome.
   If you'd prefer to install GARNOME elsewhere, change this entry.
   
   IMPORTANT NOTE: It is NOT advised, or supported to install GARNOME
   as the 'root' user on your system.

   If you would like to build GARNOME so that all of your users can
   use it, please set main_prefix to something sane like  '/opt',
   '/opt/gnome-$VERSION' or '/usr/local/garnome' and then adapt the
   configuration accordingly. Use a dedicated 'build' user rather than
   the root account, who should own this directory. This is the *only*
   step that needs root privileges.
   
   Support questions about installing GARNOME as the 'root' user will
   be discarded.

How do I use GARNOME?
---------------------

   Unpack the tarball, and optionally tweak the settings to your liking.
   The defaults should work without problems, then just:

   cd garnome-x.xx.xx/desktop
   make paranoid-install

   That's all there is to it! GARNOME will begin to build and install the
   GNOME Desktop release, and everything it needs immediately.

   If you want to build other meta directories or individual modules, just
   change to the appropriate directory and type 'make paranoid-install' or
   'make install' respectively.

   'paranoid-install' is only available for meta garballs and will stop
   building on the first error. Running 'make install' for a meta garball will
   continue building on errors, trying to build other packages.

   There are a lot of packages included in GARNOME that are not built
   as part of the standard desktop. These packages can be built as either
   individual modules by entering their directories and typing 'make install'
   or as complete meta directories which can be built with
   'make paranoid-install'.

   admin/        Administrative Tools

   bindings/     GNOME platform bindings collection

   bootstrap/    Bootstrap related

   fifth-toe/    A collection of high quality third-party programs designed
                 for your desktop, including Multimedia, Graphics and Internet
                 applications.

   freedesktop/  Freedesktop.org projects

   geektoys/     Various extensions to GARNOME that can enhance the usability
                 of your desktop, including new desktop themes and applets
                 that fit into an existing installation.

   hacker-tools/ Debuggers, Interface Designers and Hex Editors

   mono/         Mono(tm)

   office/       Parts of the proposed 'GNOME Office' suite, including a
                 spreadsheet application, word processor and the Evolution
                 PIM / Groupware suite.

How do I start GARNOME once it is installed?
--------------------------------------------

   To use GARNOME you will first need to start the DBus, HAL, and Avahi
   daemons. You can use the script below to do this:

   Note: To use Avahi you must make sure that you do not have any
   mDNS/Zeroconf daemons (i.e. Howl, mDNSResponder, etc.) running. For
   example to turn off mDNSResponder in Fedora 4, edit
   /etc/sysconfig/network and add:

NOZEROCONF=yes

   Then either kill mDNSResponder or reboot your system.

#!/bin/bash

GARNOME=$HOME/garnome

## Use GARNOME's DBus, HAL, and Avahi

## Fedora users should uncomment this section
#if [ `grep "<user>messagebus</user>" $GARNOME/etc/dbus-1/system.conf` ]; then
#       cat $GARNOME/etc/dbus-1/system.conf | \
#       sed 's,<user>messagebus</user>,<user>dbus</user>,' > \
#       $GARNOME/etc/dbus-1/system.conf;
#fi

su -c "pkill dbus; \
       pkill avahi-daemon; \
       pkill avahi-dnsconfd; \
       pkill hald; \
       rm -rf $GARNOME/var/run/messagebus.pid; \
       rm -rf $GARNOME/var/run/avahi-daemon/pid; \
       rm -rf $GARNOME/var/run/haldaemon.pid; \
       $GARNOME/bin/dbus-daemon --system; \
       $GARNOME/sbin/avahi-daemon -D; \
       $GARNOME/sbin/avahi-dnsconfd -D; \
       $GARNOME/sbin/hald"

   Once the DBus, HAL, and Avahi daemons are running you must create a
   garnome-session script to start GARNOME. An example startup script
   would look like:

#!/bin/bash

GARNOME=$HOME/garnome

PATH=$GARNOME/bin:$PATH
LD_LIBRARY_PATH=$GARNOME/lib:$LD_LIBRARY_PATH
PYTHONPATH=$GARNOME/lib/python2.4/site-packages:$GARNOME/lib/python2.4/site-packages/gtk-2.0
PKG_CONFIG_PATH=$GARNOME/lib/pkgconfig:/usr/lib/pkgconfig
GDK_USE_XFT=1
XDG_DATA_DIRS=$GARNOME/share
XDG_CONFIG_DIRS=$GARNOME/etc/xdg
MANPATH=$GARNOME/man:$MANPATH
DBUS_LAUNCH="$GARNOME/bin/dbus-launch --exit-with-session"

export PATH LD_LIBRARY_PATH PYTHONPATH PKG_CONFIG_PATH \
       GDK_USE_XFT XDG_DATA_DIRS XDG_CONFIG_DIRS MANPATH DBUS_LAUNCH

exec $DBUS_LAUNCH $GARNOME/bin/gnome-session

   You can then use the standard method your distribution provides to
   launch it when you start X.

   Note: If you have altered the install path in gar.conf.mk, remember to set
   the GARNOME variable at the top of your script to point to the correct
   directory.

   If you start X with the startx command you should launch this in
   ~/.xinitrc. If you use the Xsession menu choice in GDM, you should
   launch this in ~/.xsession. Assuming the garnome-session script is
   in your path, both files should look like this:

#!/bin/bash
exec garnome-session

Adding GARNOME to GDM (Fedora)
------------------------------

   If you would like to add GARNOME to your GDM you can do the following:

   First chmod the garnome-session file.

chmod a+x garnome-session

   Then just copy it to /usr/bin and setup the GDM Sessions file.

cp garnome-session /usr/bin
cd /usr/share/xsessions
sed -e 's/GNOME/GARNOME/g' -e 's/Exec=gnome-session/Exec=garnome-session/' < gnome.desktop > garnome.desktop

   Note: This example shows how things are setup on Fedora but your GDM
   configuration might be different depending on your distribution.
   Consult your distribution's documentation for the specific changes
   that are required.

===============
Important Notes
===============

Building as root!
-----------------

   Building a desktop like GNOME as the root user isn't a good idea.
   
   If your intention is to have all the users on a multiple
   user system be able to use the new desktop, create a dedicated 'build'
   user who owns the directory you specified for main_prefix in the
   gar.conf.mk file. (see the section entitled "How do I configure GARNOME?"
   for more information on how to do this)

   Heed the warning above, it's simpler and quicker to type 'man useradd'
   than it is to re-install your box after a rogue program breaks it.

   You should never build the entire GARNOME tree as 'root', unless you
   really do know what you are doing and there is absolutely no way to
   avoid it.

About bootstrap/
----------------

   The number one question we get asked on the GARNOME list is about the
   contents of the bootstrap/ directory.  For those who don't know, this
   directory contains programs that may or may not be present as part of an
   installed system, but have garballs included for compatibility reasons.
   
   The bootstrap/ directory is for things that fit into three categories:
   
   a) things that your distribution does not ship native packages of
   b) things that your distribution does ship, but ships broken variations
   c) things that are required to run the most recent versions of GNOME
   
   Often we get asked: "Can you ship a kernel/gcc/glibc/X in bootstrap/?"
   The answer to this is ALWAYS GOING TO BE NO!
   
   X, for example -- affects the whole of your system, not just GNOME --
   shipping x.org because users would like to have transparent windows in 
   their sessions is not an adequate reason to make the distribution ten
   times the size and further increase it's maintainence overhead. If you'd
   like transparent windowing, i'd suggest upgrading to a distribution that
   already contains x.org, then building GARNOME on that.
   
   The following systems _need_ things from bootstrap/

   System Type          Requires
   -----------          --------
   Debian <= sid        libiconv
   Mandrake <= 9.0      libiconv
   Mac OS X             dlcompat, libiconv

   The bootstrap/ directory works slightly differently to other directories,
   to use it you need to enter each sub directory you need and type

make install

   For example, to compile on Mac OS X -- you would type:

cd bootstrap/dlcompat/
make install

   Then repeat the process for the other packages you need.

   The general rule of thumb to use is: 
   
   Unless you know you need something in bootstrap/, you don't!

Linux, 2.6 kernels and GARNOME features
---------------------------------------

    Since the release of GNOME 2.8.0, a number of features have been added to 
    the core GNOME desktop that allows enhanced filesystem features, 
    device-management and more.

    The GNOME 2.14.0 release includes even more functionality which relies on
    a recent kernel and associated libraries being in place. In fact
    vast areas of the desktop are now controlled by special daemons that allows
    everything from fine grained access control to network discovery to
    multimedia functionality.

    The downside to this, is some portions of GNOME now depend on a 2.6.x or 
    newer kernel, as well as 'hal', 'dbus' and several other components. 

    If you are running an older distribution, this may mean that random 
    portions of the GARNOME desktop/ directory may not build.

    To fix this, you will need to upgrade to a 2.6.13 (or newer) kernel, and 
    udev 071 (or newer).
