________________________________________________________________________

        * * * 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 pre-compiled package is available in two flavors for GNU/Linux,
named as shared and semishared. Both packages use dynamic
(i.e. shared) libraries, the difference being that the semishared
package has several needed shared libraries included within itself
(i.e. Tcl/Tk, Togl, Mesa, Glu. and FFTW), thus hopefully diminishing
the software requirements.

XCRYSDEN may be included in several OS distributions, hence you may
first check if it exists for your distribution. If it does then it is
recommended to use it (e.g. on GNU/Linux Debian based system you can
install xcrysden as: sudo apt install xcrysden). If xcrysden is not
available for your distribution, then read below instructions how to
compile the source package.



________________________________________________________________________

INSTALLATION INSTRUCTIONS
________________________________________________________________________

   1. Installing the compiled package
   2. User customization
   3. Compiling the source package


________________________________________________________________________

1.) HOW TO INSTALL THE COMPILED PACKAGE
________________________________________________________________________


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

--
FOR IMPATIENT: minimal installation instructions
--

   1. unpack the xc-VERSION.tar.gz package file
         e.g., as: tar zxvf xc-VERSION.tar.gz
               or: gunzip -c xc-VERSION.tar.gz | tar xvf -

   2. cd into the so-created directory (i.e., cd xcrysden-VERSION/)

   3. launch the program as "./xcrysden"

Starting from XCrySDen-1.5, the use of XCRYSDEN_TOPDIR environmental
variable is deprecated, because it was a source of confusion for many
users. Consider to unset it in case it was defined during the
installation of previous versions.

Optionally, XCRYSDEN_SCRATCH environmental variable can be defined.
It is the place where XCrySDen writes scratch (temporary) files. If
the variable is not defined the /tmp/ directory will be used.

BEWARE: If an older XCrySDen version is already installed and
XCRYSDEN_TOPDIR variable defined then you need to manually unset (or
update) the XCRYSDEN_TOPDIR variable definition in your profile !!!


________________________________________________________________________

2.) USER CUSTOMIZATION
________________________________________________________________________


XCrySDen can be user-customized manually. For this reason create
$HOME/.xcrysden/ directory and copy the "Tcl/custom-definitions" and
optionally "Tcl/Xcrysden_resources" there (the Tcl/ is a subdirectory
in the XCrySDen root directory). These can be then modified according
to user preference.

Starting from XCrySDen-1.5, the use of './xcConfigure' is deprecated
(it has caused more problems than advantages).

For more info about customization, see: http://www.xcrysden.org/doc/custom.html


________________________________________________________________________

3.) HOW TO COMPILE THE SOURCE PACKAGE
________________________________________________________________________


3.1 SOFTWARE REQUIREMENTS:

XCrySDen depends on several libraries, in particular:
	 - Tcl/Tk
	 - OpenGL (e.g., Mesa and Glu)
         - Togl (2.0 or later)
	 - FFTW3
	 - BWidget

The compilation of XCrySDen requires the development versions of these
and other libraries (see system/README), because not only the library
files, but also their header files are required.  To aid at easier
compilation, these libraries will be automatically downloaded from the
web if so instructed (see below). Alternatively, these can be download
from:

Tcl/Tk:   http://prdownloads.sourceforge.net/tcl/
Mesa:     ftp://ftp.freedesktop.org/pub/mesa/
Togl:     https://sourceforge.net/projects/togl/files/Togl/2.0/
FFTW:     http://www.fftw.org/download.html
BWidget:  http://sourceforge.net/projects/tcllib/files/BWidget/

In addition to these libraries, also the X11 libraries are needed for
compilation.

[ NOTICE: during the compilation the required BWidget package (small
size) will be always automatically donwloaded from:
http://sourceforge.net/projects/tcllib/files/BWidget/ ]


3.2 COMPILATION:

First read the system/README file. It is the easiest to compile the
shared version of xcrysden (because it is more easy to install
software dependencies with a package manager system, such as apt or
dnf, then to compile needed libraries from sources).

To compile XCrySDen sources the "Make.sys" file must exist in the
package root directory. Templates can be find in system/
sub-directory. Copy an appropriate template file as, e.g.:

	$ cp ./system/Make.sys-shared Make.sys

and edit the "Make.sys" to suit your needs.

If you want the compilation to automatically download and compile the
external library sources (Tcl/Tk, Mesa, Togl, FFTW) define
"COMPILE_ALL = yes" (see system/Make.sys-semishared for more details).

Then compile as:

        $ make all

If everything went well and compilation was fully successful, you have
a usable xcrysden. Try: ./xcrysden; if it works that's it.

To make xcrysden loadable from a terminal, you can create an alias
(e.g. alias xcrysden=$XCRYSDEN_TOPDIR/xcrysden) or make a symbolic
link so that xcrysden will be on your PATH
(e.g. ln -s $XCRYSDEN_TOPDIR/xcrysden /usr/local/bin), where
$XCRYSDEN_TOPDIR is the root directory of xcrysden.


3.3 INSTALLING SYSTEM WIDE (shared flavor only):

XCrySDen (shared-flavor of compilation only) can be installed
system-wide as:

	$ make install

By default this will install the package into /usr/local/. The
installation directory can be changed by invoking "make install" as:

        $ prefix=/MY/INSTALLATION/DIR  make install

where /MY/INSTALLATION/DIR stands for installation directory. This will
install the package into ($prefix/bin/xcrysden, $prefix/lib/xcrysden/,
$prefix/share/xcrysden/).


3.4 TROUBLE SHOOTING:

If the installation has failed for some reason then read the printed
error message.

Also read carefully the instructions inside the "Make.sys" and edit
the file according to your needs.

The most often cause of failure is that either some header files were
not found or that there are some missing references, which means that
the code will have to be linked against additional libraries.

If the failure appeared in compilation of external library, then try
to compile this library manually, i.e., do "cd external/src/LIB",
where LIB is the corresponding library directory, and read the
installation instructions therein.

In case of unsolvable problems, first google for help and only then
ask for help on XCrySDen mailing list (xcrysden@democritos.it,
http://www.democritos.it/mailman/listinfo/xcrysden).


--
Anton Kokalj (tone.kokalj@ijs.si), Thu Aug 8 2019

________________________________________________________________________

        * * * README for running XCRYSDEN under CYGWIN * * *
________________________________________________________________________


1. SOFTWARE REQUIREMENTS

To run XCrySDen (pre-compiled) package under CYGWIN you will need the
following cygwin packages:

	  * tcl-tk
          * tcl-togl
	  * fftw3
	  * libGL1
	  * libGLU1
	  * xorg-server
	  * bash
	  * bc
	  * coreutils
	  * gawk
	  * grep
	  * gzip
	  * ImageMagick
          * openbabel
	  * less
	  * util-linux

BEWARE: the cygwin version of xcrysden requires running X-server !
                                                ^^^^^^^^^^^^^^^^

A very convenient tool for installing cygwin packages is apt-cyg
(https://github.com/transcode-open/apt-cyg). Using "apt-cyg" the above
packages can be installed as:

apt-cyg install tcl-tk fftw3 libGL1 libGLU1 xorg-server bash bc coreutils gawk grep gzip less util-linux ImageMagick openbabel