INSTALL

These are instructions for the configuration, building, and installation
of the Fresco windowing system.



Prerequisites
=============

Fresco uses a number of third party libraries, which you will need to
have installed before you can proceed. Please see at

http://www.fresco.org/dependencies.html

for a complete list. Unfortunately, quite a number of them are still
in heavy development, so you may need to get the sources and compile
them yourself. Respective rpm and deb packages may *not* be enough!

You might want to try those packages first. There are even some debian
packages of Fresco, you might want to try those instead of building
it yourself.

YOU WILL NEED G++ VERSION 3.2 OR LATER to build Fresco. G++ 2.95.x will
not suffice. We are using ANSI C++ which is not supported well enough
on old GCC compilers.



Downloading
===========

There are currently three ways to download Fresco. You can check out the
sources directly from cvs, in which case you find instructions at

  http://download.fresco.org/cvs.html

or you can download a nightly snapshot from

  http://download.fresco.org/snapshots/

or you can get release packages at

  http://download.fresco.org/releases.html



Configuration and Building
===========================

In case you use the cvs version, you have to prepare the source tree
by stepping into the toplevel source directory ('Fresco'), and call 
./autogen.sh, to generate configure scripts and helper files.

autogen.sh assumes you are using autoconf 2.53. You might experience
problems with earlier versions.

Decide where to build Fresco, our implementation of the Fresco interfaces,
either inside the source tree (let's refer to this as $fresco-src), or (the
recomended way), in a separate build directory ($fresco-build).
Step into the build directory, and run the toplevel configure script:

> cd $fresco-build
> $fresco-src/configure

You may want to provide some arguments, here is a list of the available options:

  --prefix               Set the prefix into which Fresco will get installed.
                         [defaults to /usr/local and can be overridden later
			  in case you should happen to forget to specify]

  --sysconfdir           Set the directory for Fresco's configuration file(s).
  			 [defaults to $prefix/etc]

  --enable-tracer        Compile with tracer support
                         This produces tons of debugging output: A big help
                         if you want to debug the server or report
                         bugs. [disabled by default]

  --with-orb		 Select the CORBA ORB used by Fresco. This can be
  			 either omniORB or TAO for now. [defaults to omniORB]

  --with-omniorb-prefix  Prefix for omniORB
                         Only needed if omniORB is not found automatically.

  --with-omniorb-version omniORB version (3 and 4 supported)
                         Only needed if your ORB version is not autodetected.

  --with-colocation-optimization Make Fresco use colocation optimization if
                         this is supported by the ORB you selected.

  --enable-optimization  Make the compiler use optimization. This might
                         mess up debugging etc.

  --with-freetype-prefix Prefix where freetype is installed (optional)
                         Only needed if freetype is not found automatically.

  --with-ggi-prefix      Prefix for GGI
                         This is only needed if you want the GGI console and
                         the GGI libraries are not found automatically.

  --with-sdl-prefix      Prefix where SDL is installed (optional)
                         This is only needed if you want the SDL console and
                         the SDL libraries are not found automatically.

  --with-directfb-prefix Prefix for DirectFb
                         This is only needed if you want the DirectFB console
                         and the DirectFB libraries are not found automatically.

  --with-art-prefix=PFX  Prefix for libArt
                         This is only needed if you want the libArt DrawingKit
                         and libArt is not found automatically.

  --with-ggimesa-prefix  Prefix for GGIMesa
                         This is only needed if you want to run the GLDrawingKit
                         on GGI (no acceleration!) and GGIMesa is not found
                         automatically.

  --with-mesa-prefix     Prefix for Mesa
                         Only needed if you want to build the GLDrawingKit and
                         have your GL library is not found automatically.

  --enable-jprof   	 enable profiling with the jprof tool
                         This is only needed for people wanting to improve
                         the performance of the server. [disabled by default]

  --enable-lclog   	 enable lifecycle logging
                         Another debugging option. [disabled by default]

For a more up to date list of arguments, try running 
  > $fresco-src/configure --help=recursive
(Depending on the version of autoconf used to generate configure, you might
need to instead do
  > cd $fresco-src
  > ./configure --help=recursive
to get the full list.)

Because of an autoconf limitation, if you don't want to use SDL, or GGI,
you have to pass "--disable-sdl" or "--disable-ggi" explicitly; otherwise
configure will error out.

Afterwards you can install Fresco with 'make install'. You do not need to
install to run it: You only need to make sure that the libraries are found.
You can even override the configured path at this stage using
'make install prefix=path'. Use with care as you will need to provide the
path to the configuration file 'berlinrc' using the -r option of the server.



Instead of using this toplevel Makefile you can manually build everything with
a sequence of commands like this:

> mkdir $(package)
> cd $(package)
> $(fresco-src)/$(package)/configure --with-some-options
> make && make install

Please note the interdependencies of the subpackages. Babylon needs Prague,
Fresco needs Babylon, Berlin needs Prague, Babylon, and Fresco, GGI needs
Berlin, SDL needs Berlin, Clients-C++ needs Prague, Babylon, Fresco, and
Berlin (the latter dependency will be removed, I promize), Clients-Python
needs Fresco.

You can specify paths to lookup any of these packages if you have installed
them elsewhere with --with-<package>-prefix.


Testing and First Steps
=======================

You should now find some libraries in $prefix/lib, modules in
$prefix/lib/Fresco/module, and binaries in $prefix/bin. If you have choosen a
non-standard prefix (anything but /usr/local/) you will need to tell
the loader where to look for the libraries, and, in case you use the
python environment, tell python where to find the Fresco modules:

csh style:

> setenv LD_LIBRARY_PATH $prefix/lib:$LD_LIBRARY_PATH
> setenv PYTHONPATH $prefix/lib/python:$PYTHONPATH

bash-like style:

> export LD_LIBRARY_PATH=$prefix/lib:$LD_LIBRARY_PATH
> export PYTHONPATH=$prefix/lib/python:$PYTHONPATH

Of course $prefix is the --prefix option (it defaults to /usr/local)
you gave to configure when building.

The berlin server is in $prefix/bin, and now you should be
able to start it.

> $prefix/bin/berlin

and voila! that should start the server.

Of course a berlin server without clients is only a little bit more
exciting than a X server without clients (mainly because of the "I built
all this myself!" factor). To start a client with the server you need
to tell it its location (starting now the $fresco-build stuff will be
assumed) using the -e (execute) flag:

> $prefix/bin/berlin -e $prefix/bin/fresco-demo

The demo program is a set of small applications showing some fresco
possibilities (new demos are welcome!).

In order to run the other C++ demo available, demo3D, you need to pass
some more information to the server. First you need to use a console
with a GLContext extension. You have two options here, use the SDL
console built with 3D support or the GGI console with ggimesa support,
both actived in compile time (Note: installing ggimesa may break you
hardware accelerated 3D setup.  You've been warned). Then you need to
use a 3D capable DrawingKit. The default DrawingKit, LibArtDrawingKit
has no 3D support, so you have to tell Fresco to use another DrawingKit
(namely GLDrawingKit).

In short:

> $prefix/bin/berlin -e $prefix/bin/fresco-demo3D -c SDL -d GLDrawingKit

for SDL console or

> $prefix/bin/berlin -e $prefix/bin/fresco-demo3D -c GGI -d GLDrawingKit

for GGI console.

(Note: the GGI/Mesa console isn't hardware accelerated, so if you
have a good video card use the SDL console instead).

If you're brave you can check http://www.fresco.org/contributions.html to
find "real" applications to run under Fresco (they may be broken, or not,
contact their authors for more information).

Finally here are other options you may use when invoking the server:

  -l --logger [list of groups to log]: log messages (the special group
                                   'lifecycle' requires configuration
                                   with --enable-lclog)

  -t --tracer :                    trace method calls (requires configuration
                                   with --enable-tracer)

  -p --profiler :                  use jprof profiler (requires configuration
                                   with --enable-jprof)

  -r --resource path :             use the berlinrc file in path instead of the
                                   configured default location. You must use
				   this option if you did override the prefix
				   during make install!

  -R --export-ref (ior|corbaloc|nameserver) : 
                                   ior is the default, and stores the address
                                   of the server in the filesystem (see the
                                   -I option below). If you have a CORBA
                                   nameserver running you can use this option
                                   to make the server use that instead, making
                                   sure that you use the same option when
                                   running the clients.

  -I --ior-file-path path :        used in conjunction with '-R ior' to
                                   specify an alternate location for the file
                                   which stores the server address (IOR); the 
                                   default location is /tmp/fresco/. You can
                                   also use '-I stdout' to specify that the
                                   server should output the address (IOR) to
                                   the console on which you run the server.

  -i --server-id name :            set the id of the server, for those
                                   interested in running multiple servers. 
                                   It is possible to have the same id across
                                   different export methods, so try to
                                   avoid confusing yourself.

  -e --execute program :           run program in the server

  -d --drawing DrawingKit :        Use the given DrawingKit instead of the
                                   default LibArtDrawingKit.

  -c --console Console :           Use the specified Console (low level
                                   rendering backend), instead of the default
				   GGI Console.


Troubleshooting
===============

There are a couple of places which are frequently subject to problems.
Please consult the FAQ at

http://wiki.fresco.org/index.cgi/ProblemsWithRunningFresco
http://wiki.fresco.org/index.cgi/FAQ

Please be sure that third party libraries are correctly installed before
you post about a bug. For example, THE MOST FREQUENT PROBLEM reported
is a broken omniORB configuration.  This should be less common now that
"-R ior" is the default, but if you use "-R nameserver", You need to have
the nameserver configured and RUNNING. A good way to test the nameserver
is 'nameclt list'.  This should return no error message and terminate
immediatly.

Note that simply running berlin -e fresco-demo will work regardless of
which -R option you use.  When loading, the server also publishes its
initial reference into the environment under FRESCO_DISPLAY which the
client will try first when searching for the server. Because -e
program is executed as a child of the server, it inherits the
environment variable and will not attempt to use the nameserver or
filesystem.

Another common problem is that there are NO FONTS: Currently Fresco uses
the last font freetype can handle which does not necessarily need to
contain all the ASCII characters. To get around this problem try specifying
which default font the server is to use by setting the environment variable
'BERLIN_FONT_CHOOSER' to the empty string and reruning the server. On
startup, it should present you with a list of fonts to choose from on the
console from where you started up the server.

If you're running two servers together, one with the id "FrescoServer"
(as per default) and the other with the id "nested", then to start a
client in nested from the Terminal Demo in FrescoServer, run 
   fresco-demo -i nested
to bypass the server lookup from the environment.

Report a bug
============

Please visit http://issues.fresco.org/ to report bugs. Please check the
FAQs listed above before submitting. You do not need to register to file a
bug report, but if you do you will be keapt up to date with what is going
on with it via e-mail.


Contact
=======

You can get into contact with the developers via IRC (#fresco on
irc.freenode.net) and via mailinglists (see
http://www.fresco.org/mailinglists.html for details).



Good luck!

The Fresco Team