INSTALL

Étoilé INSTALL
==============

**WARNING**: As it stands now, Etoile is more or less a development environment and not a desktop environment. We have no working theme since we are still in the process of migrating from our Camaelon theme engine to the new one bundled with GNUstep. User-oriented applications such as Melodie can fail to launch or behave correctly because their development have been put on hold. We advise you not to use the session support built into Étoilé, but rather write Étoilé code inside another environment such as GNOME or KDE.

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

 * LLVM/Clang 3.7 is required to build Etoile

LLVM/Clang 3.7 binaries can be downloaded [here](http://llvm.org/releases/download.html#3.7).

GCC is not supported, although it can be used to build some modules within the repository (especially GCC 4.6 which supports the main Objective-C 2 features). 

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.6.6 or 2.6.7 (the latest version 2.6.8 is unsupported currently)
 * gnustep-base trunk 1.24.7 or higher
 * gnustep-gui 0.25 or higher
 * gnustep-back 0.25 or higher
 * libobjc2 1.8 or higher (other ObjC runtimes such as the one packaged with GCC won't work)

**Warning:** libobjc2 is also known as the GNUstep runtime. It's a new runtime unrelated to the GCC libobjc and the old GNUstep libobjc (which was a just patched GCC libobjc). Linux distributions such as Debian or Ubuntu include packages named libobjc2 or libobjc3 which are completely unrelated to the GNUstep runtime, and are just recent GCC libobjc packaged under a new name. More details in [GNUstep Objective-2 FAQ](http://wiki.gnustep.org/index.php/ObjC2_FAQ)

GNUstep source releases can be downloaded [here](http://wwwmain.gnustep.org/resources/downloads.php) and the libobjc2 source [here](http://download.gna.org/gnustep/).

Alternatively you can check out the latest GNUstep unstable (or trunk) as follows, but libobjc2 won't be included: 

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

**Note**: EtoileUI works best with the most recent GNUstep svn revision, many EtoileUI-related bug fixes or improvements are regularly being committed to the GNUstep repository.

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) (LanguageKit)
 * [Lemon](http://www.hwaci.com/sw/lemon/) (Smalltalk and EScript)
 * [GMP](http://gmplib.org/) (Smalltalk)
 * [libdispatch](https://libdispatch.macosforge.org/) (CoreObject)
 * [SQLite](http://www.sqlite.org) 3.7 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)
 * [Graphviz](http://www.graphviz.org/) (DocGenerator)
 * [Discount](http://www.pell.portland.or.us/~orc/Code/discount/) (DocGenerator)

For libdispatch, packaged versions on Linux or FreeBSD are not compatible with libobjc2. For now, we maintain our own libdispatch. To install it, check out and follow the libdispatch-objc2/INSTALL document (you must install libobjc2 first, see Build and Install GNUstep section):

	git clone https://github.com/etoile/libdispatch-objc2

If you are using LLVM/Clang and GNUstep packages rather than building them manually, 
you can jump directly to the section **Build and Install Etoile**.
Don't forget to check libobjc2 is installed, otherwise you have to install it as 
explained in the **Build and Install GNUstep** section.


Notation
--------

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


Build LLVM and Clang
--------------------

- First check out the projects

	svn co http://llvm.org/svn/llvm-project/llvm/trunk llvm
	cd llvm/tools
	svn co http://llvm.org/svn/llvm-project/cfe/trunk clang

- Build both projects but don't install them

It's a good idea to build LLVM in parallel, so use '-j' if you can

	cd .. # Back to llvm directory
	./configure [--enable-optimized] && make [-j4]

Both LLVM and Clang have been built in debug mode. 

Without --enable-optimized, Clang is quite slow, so it can be a good idea to pass this option. The downside is that it makes harder to debug LLVM/Clang issues, which might lead you to recompile LLVM/Clang without --enable-optimized later on.
For more detailed instructions, see http://clang.llvm.org/get_started.html

- Finally expose LLVM and Clang:

	export PATH=$PATH:$PWD/Debug/bin: # llvm/Debug/bin contains the clang binary
	export CC=clang # Make Clang the C/ObjC compiler rather than GCC

A good choice is put the two lines above in ~/.bashrc or similar and open a new shell. This way you won't have to export these variable every time you want to compile GNUstep or Etoile stuff.

- Check Clang is ready:

	clang -v


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

To build GNUstep with Clang:

- Check out GNUstep core modules and libobjc2:

	svn co http://svn.gna.org/svn/gnustep/modules/core
	git clone https://github.com/gnustep/libobjc2.git

- Install GNUstep Make a first time:

	cd core/make
	./configure --enable-debug-by-default --with-layout=gnustep [--prefix=/]
	make && sudo -E make install
	. /usr/GNUstep/System/Library/Makefiles/GNUstep.sh 
	# Or . /System/Library/Makefiles/GNUstep.sh if --prefix=/ was passed

A good choice is to put this last line above in ~/.bashrc or similar. This way you won't have to source GNUstep.sh every time you want to compile GNUstep or Etoile stuff.

If you omit --with-layout=gnustep, GNUstep will use the host system hierarchy and built applications/libraries will be installed in /usr/local/bin, /usr/local/lib etc. In this case, libobjc2 can be compiled directly without installing GNUstep Make first. If GNUstep.sh has been sourced, libobjc2 will install itself according to the filesystem layout used by GNUstep Make (either GNUstep or host system).

**Note**: If you use a C shell, you should source GNUstep.csh rather than GNUstep.sh.

- Build libobjc2

install/strip ensures you can debug ObjC code without stepping inside runtime functions each time a message is sent.

	cd ../../libobjc2
	mkdir Build
	cd Build
	cmake -DCMAKE_CXX_COMPILER=clang++ -DTESTS=FALSE ..
	make && sudo -E make install/strip 

A special sudo invocation for 'make install' will be required if sudo uses a secure PATH variable:

	make && sudo sh -c ". $GNUSTEP_MAKEFILES/GNUstep.sh; make install/strip

You can also edit /etc/sudoers using visudo and comment out the line 'Defaults secure_path=XXX'. Which means 'sudo -E' now inherits the PATH variable as customized by GNUstep.sh and the gnustep-config tool can be found (by the libobjc2 GNUmakefile). If the secure path support has been disabled, 'sudo -E make install' will work as is to install GNUstep and Etoile, in the next instructions.

**Warning**: The new runtime is the GNU runtime version 2 but its library version is libobjc.so.4. libobjc.so.2 corresponds to the GNU runtime version 1 which comes with GCC and is also available at http://svn.gna.org/svn/gnustep/dev-libs/libobjc.

- Install GNUstep Make a second time so it can detect the new ObjC runtime just installed:

	cd ../../../core/make
	./configure --enable-debug-by-default --enable-objc-nonfragile-abi --with-layout=gnustep [--prefix=/]
	make && sudo -E make install

- Build and Install GNUstep Base, Gui and Back:

	cd ../../core/base
	# For Linux e.g. Ubuntu, --with-ffi-include is usually required
	./configure --disable-mixedabi [--with-ffi-include=/usr/include/`gcc -dumpmachine`]
	make && sudo -E make install

	cd ../../core/gui
	./configure && make && sudo -E make install

	cd ../../core/back
	./configure && make && sudo -E make install

You can check you are really using Clang and not GCC with 'make messages=yes' instead of 'make' when building a GNUstep module.
You can switch back to GCC for a given project with 'make CC=gcc' (or alternatively './configure CC=gcc').

To get an overview of the build options per module, you can use './configure --help' in each module directory.

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


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

**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.

- Build and Install libdispatch (requires CMake 2.8 or higher)

	cd ../..
	git clone https://github.com/etoile/libdispatch-objc2
	# For more detailed instructions, see libdispatch-lobjc2/INSTALL
	mkdir libdispatch-objc2/Build
	cd libdispatch-objc2/Build
	cmake -DCMAKE_C_COMPILER=clang -DCMAKE_BUILD_TYPE=Release ..
	make && sudo -E make install

- Build and Install Etoile:

	# Go to the Etoile directory that contains this INSTALL document
	make # Don't use -j flag
	[sudo] [-E] make install

**Warning:** If *Smalltalk.h not found* is reported, then it is usually because the -j flag was passed to GNUstep Make. GNUstep Make sometimes doesn't track the dependencies correctly for compiling SmalltalkParser.


Uninstall Etoile
----------------

	# Go to the Etoile directory that contains this INSTALL document
	[sudo] [-E] make uninstall


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.


Generate Documentation
----------------------

To build both the code and the documentation at the same time in any directory, type: 

	make documentation=yes

In addition, you can also generate the documentation without building the code per module. Move to a module directory (e.g. cd Languages/LanguageKit) and do:

	make doc

Every time you generate some documentation, a Documentation directory appears per module (e.g. Languages/LanguageKit/Documentation) and it gets consolidated in Developer/Documentation. You can browse the Developer/Documentation/index.html as a starting point.
If you are in a module directory, you can browse its documentation with Documentation/index.html (e.g. Languages/LanguageKit/Documentation/index.html)

To clean the generated documentation in the current module directory (will also clean the content copied in Developer/Documentation):

	make clean-doc

Finally to remove all the generated documentation, you can use in any directory:

	make distclean

which also discards the code previously built.


Trouble
-------

Give us feedback! Tell us what you like; tell us what you think
could be better. Send bug reports and patches to <https://github.com/etoile/Etoile>.