Etoile INSTALL
==============

Required software
-----------------

You need to have the GNUstep core libraries installed in order to
compile and use Etoile. The core packages are, at a minimum:

 * gnustep-make 2.00 or higher
 * gnustep-base 1.15.3 or higher with an odd number as minor version
 * gnustep-gui 0.13.2 or higher with an odd number as minor version
 * gnustep-back 0.13.2 or higher with an odd number as minor version

Alternatively you can check out GNUstep unstable (or trunk) as follows: 

	svn co http://svn.gna.org/svn/gnustep/devmodules/core

**WARNING**: GNUstep releases with an even number as minor version, such as 
gnustep-base 1.16.z or gnustep-gui 1.14.z, are stable releases that don't 
contain all the features Etoile relies on. Etoile requires the unstable releases 
so currently base 1.15.z and gui/back 0.13.z. The next unstable GNUstep releases 
(not yet out) that should work fine will be base 1.17.z and gui/back 0.15.z. For 
a detailed explanation of this numbering scheme, see 
[GNUstep release policy](http://wiki.gnustep.org/index.php/GNUstep_release_policy)

See [GNUstep](http://www.gnustep.org/) for further information.

You need some extra libraries if you intend to build a complete Etoile
environment or the whole repository:

 * libpng (IconKit)
 * [zlib](http://www.zlib.net/) (LuceneKit)
 * [OniGuruma](http://www.geocities.jp/kosako3/oniguruma/) 5.0 or higher (OgreKit)
 * [D-Bus](http://www.freedesktop.org/wiki/Software_2fdbus) 1.0 or higher (System)
 * [HAL](http://www.freedesktop.org/wiki/Software_2fhal) (System)
 * [startup-notification](http://www.freedesktop.org/wiki/Software_2fstartup_2dnotification) (Azalea)
 * [Xcursor](http://www.freedesktop.org/wiki/Software_2fxlibs) (Azalea)
 * [XScreenSaver](http://www.jwz.org/xscreensaver/) (Idle)
 * [LLVM](http://www.llvm.org) (Smalltalk)
 * [Lemon](http://www.hwaci.com/sw/lemon/) (Smalltalk)
 * [GMP](http://gmplib.org/) (Smalltalk)
 * [PostgreSQL](http://www.postgresql.org) 8.3 or higher (CoreObject)
 * [libavcodec and libavformat](http://ffmpeg.mplayerhq.hu/) (MediaKit)
 * [OSS](http://www.opensound.com/) (MediaKit)
 * [TagLib](http://developer.kde.org/~wheeler/taglib.html) (Melodie)
 * [libmp4v2](http://www.mpeg4ip.net/) (Melodie)

For now, before building Etoile you should configure, compile and install LLVM either by downloading LLVM 2.4 release sources or by checking out the Subversion development trunk available at: <http://llvm.org/svn/llvm-project/llvm/trunk>.


Notation
--------
In the following text, square brackets "[ ]" are used to indicate an
optional parameter.


Build and Install
-----------------

**WARNING:** If you don't run setup.sh script, Etoile environment won't be fully 
installed.

**WARNING:** setup.sh is currently unsupported on platforms other than Linux. 
So the set up process has been to be done manually on systems such as FreeBSD.

**WARNING:** For stable, both setup.sh and setdown.sh will log various warnings 
about missing elements or failures. This is expected because these scripts have 
been written for trunk initially and have not yet been adjusted for the stable 
branch. They also don't report and handle errors in a very user-friendly way, 
only the error output of the shell commands that failed will be logged.

**Note:** If you encounter path related error, you can source GNUstep.sh or 
GNUstep.csh in your shell, read the GNUstep documentation to know more about 
this topic.


Steps to build:

	make
	[sudo] [-E] make install
	./setup.sh
	Frameworks/CoreObject/setup-coreobject.sh

setup.sh script takes care of various operations mandatory to have a ready to 
use environment that includes:

 * Nesedah theme
 * Horizontal menu bar

This involves to copy or link various elements and set several preferences 
(called 'defaults' in GNUstep terminology). 
The script will ask you whether you want to set up the environment for the 
current user only or for the whole machine.

Read CoreObject INSTALL documentation to learn about setup-coreobject.sh.


Uninstall
---------

Steps to uninstall:

	[sudo] [-E] make uninstall
	./setdown.sh
	Frameworks/CoreObject/uninstall-coreobject.sh

setdown.sh script allows to get rid of what has been installed or configured by 
setup.sh. In other words, it reverts the effect of setup.sh script. 

Take note, you can use it alone without running 'make uninstall' first. This is 
useful when you want to disable temporarily Etoile theme, horizontal menu etc. 
and get back to the GNUstep look & feel. Then you can return to the usual 
Etoile look & feel by running setup.sh again.

However it's important to note that setdown.sh doesn't disable only Camaelon 
(theme engine) and WildMenus (horizontal menu engine). You won't be able
to log in from KDM or GDM once setdown.sh has been run, and Etoile specific 
applications may fail because of missing elements or daemons not launched.

Read CoreObject INSTALL documentation to learn about uninstall-coreobject.sh.


Custom Build and Install
------------------------
In order to build and install the whole project (with the exception of
developers tools like UnitKit), you can just type in the root directory (named
Etoile):

	make
	[sudo] [-E] make install

You can choose to build only custom set of modules. Add a 'modules.make' file in 
the root directory named 'Etoile' that contains Frameworks, Services and so on. 
In this file, to turn on the module CoreObject and off the module UnitKit, write:

export coreobject = yes
export unitkit = no

Be careful to have no trailing spaces after 'yes' or 'no'. 
Take also note by declaring these variables, you only determine whether these 
specific modules are built or not, but the build system won't automatically 
resolve and turn on and off dependencies in relation to those modules. So you 
must keep track by yourself of the dependencies to be enabled or disabled. These 
dependencies are usually documented in Frameworks/GNUmakefile and similar 
directories. They can also always be found by looking at the linker flags for 
each module GNUmakefile.

You can use the 'make' command with all the available options from every
projects directory.

You can also build test bundles for any specified modules by adding an option
'test=yes', in future you should be able to run every test bundles with 'make
check' but this is not implemented currently.


Trouble
-------
Give us feedback! Tell us what you like; tell us what you think
could be better. Send bug reports and patches to <etoile-track@gna.org>.
