
                                 GARNOME!

   GARNOME -- the bad-ass, bleeding edge GNOME distribution for testers
   and tweakers everywhere -- is finally released unto the teeming masses.
   If you're dying to test the latest GNOME code, but don't want to fall
   into the depraved addictions and co-dependencies of testing from
   anonymous CVS, then GARNOME is for you.

What is GARNOME?
----------------

   It's a bad-ass, bleeding edge GNOME distribution for testers and
   tweakers everywhere. Those not paying attention can stay after class.

   GARNOME is a distribution of GNOME, based on the [1]GAR ports system
   by Nick Moffitt. It builds the latest GNOME Desktop tarball releases,
   and includes extra GNOME 2.x software to provide testers with a
   comfortable desktop environment.

   Join our [2]mailing list! Read the [3]archives!

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 your tarballs are in. Example:

     GARCHIVEDIR = /home/pd/src/garnome/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, but please refer to the
   'configuration' portion of this document for tips. 

An IMPORTANT note about building as root!
-----------------------------------------
   
   Seriously, 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 using 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.

An IMPORTANT note 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
   
   Note from Paul: Often, I 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.
   
   [ this has been a public service announcement from Paul's sanity ]
   
   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 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)

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


An IMPORTANT note about 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.12.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.10 (or later) kernel, and 
    compile 'bootstrap/dbus' and 'bootstrap/hal'

Building GARNOME
----------------

   Once you have determined if you need bootstrap/, simply return to the main
   GARNOME directory and type:

   cd 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 is a lot of packages included in GARNOME that is not built as part of
   the desktop/ category, including:

   bindings/		GNOME platform bindings collection

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

   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, oh my.

   mono/		Mono(tm)

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

   Two other categories, which GARNOME depends upon internally, contain:
   
   bootstrap/		A collection of libraries/sources that are required to
			build parts of the GNOME desktop, but are not found on
			some older platforms.
			
   freedesktop/		Includes the freedesktop XDG specification, as well as
			sources from other freedesktop.org projects that GNOME
			uses to increase functionality / usability of it's
			product.

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

   The easiest way is to create a garnome-session script, and use the
   standard method your distribution provides to launch it when you start
   X. Here's what the script should look like:

     #!/bin/sh
     GARNOME=$HOME/garnome
     PATH=$GARNOME/bin:$GARNOME/sbin:$PATH
     LD_LIBRARY_PATH=$GARNOME/lib:$LD_LIBRARY_PATH
     PYTHONPATH=$GARNOME/lib/python2.4/site-packages
     PKG_CONFIG_PATH=$GARNOME/lib/pkgconfig:/usr/lib/pkgconfig
     XDG_DATA_DIRS=$GARNOME/share
     XDG_CONFIG_DIRS=$GARNOME/etc/xdg
     GDK_USE_XFT=1
     export PATH LD_LIBRARY_PATH PYTHONPATH PKG_CONFIG_PATH GDK_USE_XFT XDG_DATA_DIRS XDG_CONFIG_DIRS
     exec $GARNOME/bin/gnome-session

   Just set the GARNOME variable at the top to wherever you installed
   GARNOME. It will usually be $HOME/garnome, as above.

   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/sh
     exec garnome-session

   My own startup script is a little bit funkier:

     #!/bin/sh
     xset -solid black
     if [ -e /home/pd/.fonts ]; then
     xset fp+ /home/pd/.fonts/
     xset fp rehash
     fi
     exec /usr/bin/ssh-agent /home/pd/garnome/bin/garnome-session & wmpid=$!
     wait $wmpid

   This sets the background to black so I don't have to look at the ugly
   grey default for very long, sets up old X programs to use all the
   fonts I have in my .fonts directory, and runs garnome-session under
   ssh-agent (very useful if you use ssh keys) and then sits in the
   background waiting for the session to conclude (useful for multiuser
   and terminal based setups).
