________________________________________________________________________

        * * * README & INSTALL file for XCRYSDEN * * *
________________________________________________________________________


XCrySDen web site is http://www.xcrysden.org/. The code can be
downloaded either as source or compiled package.

The source package is available in two flavors. One contains only
XCrySDen sources, while the other contains also the necessary external
libraries (Tcl, Tk, and Mesa).

The compiled package, at least for Linux, is also available in two
flavors, named as shared and semishared. Both packages use dynamic
(i.e. shared) libraries, the difference being that the semishared
package has all the needed shared libraries included within the
package, thus hopefully diminishing any software requirements.



________________________________________________________________________

INSTALLATION INSTRUCTIONS
________________________________________________________________________
  
   1. Installing the pre-compiled package
   2. Installing the source package



________________________________________________________________________

1.) HOW TO INSTALL THE pre-COMPILED PACKAGE
________________________________________________________________________


The pre-compiled package does not require the compilation, hence its
installation is fairly simple.

--
FOR IMPATIENT: minimal installation instructions
--

   1. unpack the *.tar.gz package file.
   2. cd into the so-created directory
   3. launch the program as "xcrysden" or "./xcrysden"

Starting from XCrySDen 1.6, the XCRYSDEN_TOPDIR and XCRYSDEN_SCRATCH
environmental variables variables are not mandatory anymore;
nevertheless it is recommended to define the two variables:
      
   * XCRYSDEN_TOPDIR defines the location of the XCrySDen
     (i.e. its root directory)
   * XCRYSDEN_SCRATCH defines the directory for writing temporary files
      
   BEWARE: if you have an older version of XCrySDen installed, then
           XCRYSDEN_TOPDIR variable is defined and points to the
           location of the old-version; you should update the variable
           accordingly.

--
A BIT LONGER INSTALLATION INSTRUCTIONS
--

After unpacking the *.tar.gz archive-file, it is recommended that user
defines two environmental variables: XCRYSDEN_TOPDIR and
XCRYSDEN_SCRATCH. This can be facilitated by the "xcConfigure"; from
XCRYSDEN's root directory execute (dollar-sign stands for shell
prompt):

        $ ./xcConfigure

The "xcConfigure" script modifies your profile (either .bashrc,
.profile or .cshrc, depending on the shell), defines the two
environmental variables (XCRYSDEN_TOPDIR and XCRYSDEN_SCRATCH), and
modifies the PATH variable by including the $XCRYSDEN_TOPDIR to the
path. Then you should source the corresponding profile in order to
load the newly-added definitions. 

For bash-shell execute:
   
	$ . ~/.bashrc

For csh- or tcsh-shell execute:

        $ source ~/.cshrc

For for sh-shell execute:


BEWARE: If an older XCRYSDEN version is already installed, then you
should manually update the XCRYSDEN_TOPDIR variable definition in your
profile to point to the new place !!!

What "xcConfigure" does?

It creates the $HOME/.xcrysden/custom-definitions file, which is used
for setting some custom definitions, like the location of CRYSTAL
package, custom atomic colors and radii, etc.


________________________________________________________________________

2.) HOW TO INSTALL THE SOURCE PACKAGE
________________________________________________________________________


SOFTWARE REQUIREMENTS: The compilation of XCRYSDEN requires the
following software: Tcl/Tk >= 8.4, and OpelGL (or Mesa). The
compilation requires not just the Tcl/Tk + OpenGL library-files, but
also their header files !!!

Tcl/Tk can be downloaded from: http://www.tcl.tk/software/tcltk/download.html 
Mesa can be downloaded from    http://sourceforge.net/projects/mesa3d/
	
To compile the source package the file Make.sys should be present in
the package root directory. Templates can be find in ./system/
subdirectory. Copy an appropriate template file: 

	$ cp ./system/Make.MY-SISTEM Make.sys

Now edit the file Make.sys to suit your needs. Then if you are
impatient simply try:

        $ make all
        $ ./xcConfigure

See also "HOW TO INSTALL THE pre-COMPILED PACKAGE" section for the
description of xcConfigure script. The xcConfigure will modify your
profile (.bashrc or .profile or .cshrc, depending on the shell). Then
you should source the corresponding profile in order to load the
newly-added definitions.


TROUBLE SHOOTING:

If the installation has failed for some reason, then read a few hints
that are described below.

First, please read carefully the instructions inside Make.sys and edit
the file according to your needs. Basically you have two possibilities
in Make.sys:

    (i)  To use your own libraries. In this case the flag
         COMPILE_TCLTK and COMPILE_MESA set to "no".

    (ii) To use the included sources of external libraries, i.e., Tcl,
         Tk, Mesa (for xc1.X.Ysource-all.tar.gz package only). In this
         case flags COMPILE_TCLTK and COMPILE_MESA must be set to
         "yes", which will enable the compilation of the libraries.

If you are using the xc1.X.Ysource-all.tar.gz package, which contains
also the required external libraries (Tcl, Tk, Mesa), then check if
the error occurred during the compilation of external libraries. If
this is the case, try to compile these libraries manually, i.e., do
"cd external/src/LIB", where LIB is the corresponding library
directory, and read the installation instructions therein.

If you are using the xc1.X.Ysource-nolibs.tar.gz package this means
that the error occurred during the XCRYSDEN compilation.  Possibly you
can correct the error by editing the ./Make.sys file.
