		TANGO source code release V5.3.0 - README
		=========================================
			Jens Meyer (meyer@esrf.fr)
			------------------------i-------
			        30/09/2005


TABLE OF CONTENTS
-----------------

 1 - Introduction
 2 - What's inside
 3 - Prerequisites
 4 - Installing
 5 - Compiling
 6 - Updating from previous Tango releases
 7 - Running
 8 - Documentation
 9 - Remarks
10 - Questions
11 - URL
12 - Changes


1 - INTRODUCTION
----------------
This is the README for the TANGO source code release. TANGO is a
toolkit for building object oriented control systems based on CORBA. 
TANGO is a joint effort of the ESRF and Soleil synchrotron radiation
source institutes.

This source code release is based on the latest version of TANGO 5.3.0
and is intended for Unix platforms. A binary version for Windows of TANGO 
will be appearing shortly. The source code contained in this package 
runs on Windows but the Makefile don't.

2 - WHAT'S INSIDE
-----------------

This source code release contains :

(1) Tango C++ library source files and java package source files

(2) The Tango database device server source files (using mysql)

(3) The Jive application. 

(4) The Astor application and its associated Starter device server source files.

(5) The Pogo application.

(6) The tg_devtest application

(7) A test device server called TangoTest with its source files

(8) The atk graphical toolkit for writing tango applications in java
    Please,note that the ATK toolkit does not support yet some of the
    new features added in Tango V5 (some attribute data types are still missing)
    This will be done in a near future. An update will be
    available when ATK will be updated.

(9) The atkpanel application as example of using atk

(10 The atktuning application for tuning attributes in a device

(11) The logviewer application for visualising logging messages

(12) The DeviceTree application to display tango device attribute and/or command

The Jive application is a Tango database browsing tool written in Java. It also
allows device testing. Its documentation is at

	http://www.esrf.fr/tango/tango_doc/tools_doc/jive_doc/index.html
	
The Astor application is also a Java application. With the help of the Tango
starter device server, it allows full remote Tango control system administration.
Its documentation is at :

	http://www.esrf.fr/tango/tango_doc/tools_doc/astor_doc/index.html
	
The Pogo application is a graphical Tango device server code generator.
Its documentation is at :

	http://www.esrf.fr/tango/tango_doc/tools_doc/pogo_doc/index.html
	
tg_devtest is a device testing application for device server which do not
use the database. It is a sub-part of Jive. 

3 - PREREQUISITES
-----------------

Before compiling and installing TANGO you need to install :

(1) omniORB 4.0.5 available from http://sourceforge.net/projects/omniorb

(2) mysql available from http://mysql.org (version > 3.22)

(3) omniNotify release 2.1 available from http://omninotify.sourceforge.net/nfy_download.html
    
    Remark : omniNotify is an implementation of the CORBA Notification
             Service. It is not mandatory to run Tango and therefore
	     it's installation is not checked by the "configure" script.
	     If you don't install it, it will not be possible to communicate
	     between client applications and devices using the Tango event
	     system. Only the synchronous and asynchronous way of communication
	     will be possible.
	     
(4) doxygen available from http://www.doxygen.org

    Remark : doxygen is not mandatory to run Tango. It is just used by our code
             generator (called Pogo) to automatically generates some part of 
	     the Tango device server documentation. If you don't install it,
	     this part of the documenetaion will simply not be generated.
	     But in all cases, some HTML pages documenting Tango device server
	     will allways be generated.

Also check the tools you are using

(1) If you are using gcc, you need to have gcc release 3.1.0 or above. You can
    download gcc from http://gcc/gnu.org

(2) Only java release 1.4.0 or above is supported, you can download java from
    http://java.sun.com/j2se (See chapter 4, Java sub-chapter)

4 - INSTALLING
--------------

Once you have installed the packages in prerequisites you can think
about configuring and compiling TANGO. 

To configure TANGO you need to tell it where to find omniORB and
mysql (if it is in a non-standard place) and where to install
TANGO.

mysql
-----
Make sure mysql is running before doing configure.
Also check that the mysql client (called mysql) is in your path.
If you are not running the configure script on the same host
where the mysql server is running, use the "--with-mysql-ho" configure
option. The configure script will try to connect to the
MySql database. Make sure that privileges are granted to
the user used by configure running on the host where you
run configure. The configure option "--with-mysql-admin"
allows you to select which MySql user configure will use.
The default is "root".

Database server, mysql and libz
-------------------------------
Depending on how MySql has been installed, the Tango database
server may need the compress/uncompress library (called "libz").
By default, configure try to find this compress/uncompress stuff.
If you don't need it, use the configure "--without-zlib".

Java
----
Tango arrives with many Java applications. Each java applications has
its own script (in $prefix/bin) where the CLASSPATH is set before 
starting the java interpreter. These scripts will be modified by the
configure script to set a correct path to the java interpreter found in
your PATH when configure was run. You can also used the "--with-java=xxx"
to define a path to the java interpreter.
It is not mandatory to find the java interpreter in your PATH or to use the
"--with-java" configure option to build Tango. This will only prevent
a correct substitution in scripts. In such a case, you will have to
manually do the substitution in scripts located in $prefix/bin.

doxygen
-------
Doxygen is a documentation generator from C++ source files. It is used by the
Tango code generator (called Pogo) to generate Tango device server documentation.
The script used to start Pogo will be modified bt the configure script to set
a correct path to the doxygen command found in your PATH when configure was
run. You can also used the "--with-doxygen=xxx" to define a path to the
doxygen command.
It is not mandatory to find the doxygen command in your PATH or to use the
"--with-java" configure option to build and run Tango. This will only prevent
some part of Tango device server documentation to be generated by Pogo.


You can type "configure --help" to get a print of all the options
supported by the configure script.

Here is an example of running configure for TANGO telling it where
to install (--prefix) TANGO and where omniORB is installed :

cd $directory_where_tango_has_been_installed
mkdir build
cd build
export CC=gcc
export CXX=g++
../configure --prefix=/home/tango/release/install_dir_linux \
	--with-omni=/segfs/tango/ORB/omniORB4.0.1/suse72

Here is an example running configure on Solaris telling it where
to install TANGO, where omniORB is installed and where mysql is
installed :

cd $directory_where_tango_has_been_installed
mkdir build
cd build
export CC=/opt/SUNWspro/bin/cc
export CXX=/opt/SUNWspro/bin/CC
./configure --prefix=/users/tango/release/install_dir_sol \
	--with-omni=/segfs/tango/ORB/omniORB4.0.1/solaris7_CC \
	--with-mysqlclient-include=/segfs/tango/database/solaris7/include/mysql \
	--with-mysqlclient-lib=/segfs/tango/database/solaris7/lib/mysql
	

5 - COMPILING
-------------

Once configure has run successfully you can compile and install the
executables, include files, libraries and scripts. Do this by typing :

make all

make install

6 - UPDATING FROM PREVIOUS TANGO RELEASES
-----------------------------------------

Staring with release 4, Tango needs a new table in its MySQL database.
If you already have a running Tango release 4 system, a SQL script called
"create_event_table.sql" in the <install_dir>/share/tango/db
directory will only create this new table. Run it with
a command like 

	mysql -u <tango_user> -p <tango_user_passwd> -h <tango_db_host> <create_event_table.sql

7 - RUNNING
-----------

To test wether the TANGO build worked do the following :

(1) start the database on port 10000 by typing :

    TANGO_INSTALL_DIR/bin/DataBaseds 2 -ORBendPoint giop:tcp::10000 -v
    
    By default, the database server connects to mysql using the mysql
    "root" login. You can change this behaviour by setting the following
    environment variables :
    
    	- MYSQL_USER to specify the mysql login name
	- MYSQL_PASSWORD to specify the password

(2) start the test device server tangoTest :

    TANGO_INSTALL_DIR/bin/TangoTest test -v

(3) start jive by typing for example :

    TANGO_INSTALL_DIR/bin/jive
    
    (See chapter 4 java sub-chapter to check the jive script) 

(4) test your device using the test device in jive

(5) write new device servers using pogo :

    TANGO_INSTALL_DIR/bin/pogo

    (See chapter 4 java sub-chapter to check the jive script) 


8 - DOCUMENTATION
-----------------

Don't forget to READ THE MANUAL (in doc/tango_5_3.pdf) !

9 - REMARKS
-----------

(1) Due to a limitation of the Solaris CPP compiler (at least in its release
    5.4), we had to modify the Database device server in order to make it run
    on all our supported platforms. These changes regards the namespace name
    in which the Database class is written.
    The drawback of these changes is that database server sources are now 
    incompatble with the Pogo software.

10 - QUESTIONS
--------------

You will definitely have some ! Send questions to tango@esrf.fr.

11 - URL
--------

Visit the TANGO website http://www.esrf.fr/tango


12 - CHANGES
------------
30/09/2005 - Updated to tango CPP release 5.3.0
	     Which uses the hostname as fully qualified domain name.
	     The device creation wizard is integrated.

	     Updated TangORB to release 4.6.3
	     Updated Database device server to release 2.6.0
	     Updated Starter device server to release 2.2.0
	     Updated TangoTest device server to release 1.2
	     Updated LogViewer to release 1.2.1
	     Updated Atk to release 2.1.26
	     Updated AtkPanel to release 1.16
	     Updated DeviceTree to release 1.3
	     Updated Jive to release 2.6e
	     Updated Pogo to release 4.4.1a
	     Updated Astor to release 4.0.3
	     Updated AtkTuning to release 2.7

30/03/2005 - Fix bug in create_db.sql script
	   - Package generated with automake 1.9.2

19/01/2005 - Updated to tango CPP release 5.1.0
	     Updated TangORB to release 4.3.3
	     Updated Database device server to release 2.5.0
	     Updated Starter device server to release 2.1.0
	     Updated TangoTest device server to release 1.2
	     Updated LogViewer to release 1.2.1
	     Updated Atk to release 1.10.2
	     Updated AtkPanel to release 1.14
	     Updated DeviceTree to release 1.2
	     Updated Jive to release 2.5a
	     Updated Pogo to release 4.0.6
	     Updated Astor to release 3.7.4
	     Updated AtkTuning to release 2.6


10/07/2004 - Updated to tango CPP release 4.3.0 which includes bug fixes and
             full reconnection between clients/servers and CORBA notification
	     service daemon
	     Update TangORB release to 4.0.1 (Java servers with polling thread
	     and Java events)
	     Update Jive to Jive 2.3 c (bug fixes)
	     Update ATK to its release 1.6.7
	     Update to Astor 3.7.0
	     Update database device server to its release 2.3.0
	     Update starter device server to its release 2.0.0
	     Configure now checks gcc release (if gcc is used) and also checks
	     java release if one java interpreter is found
	     Configure also checks if doxygen is in the user PATH (for pogo)
	     Change templates/pogo/cpp/Makefile that it takes the install
	     diectory into account
	     Change in litool.m4 in oder to have libtool generating correct
	     lib names!
	     
04/05/2004 - Updated to tango 4.1.0 which includes event and group.
             Replaced devTest device server by TangoTest device server.
             Remove the include directory
             Add the notifd2db utility
	     Add the possibility to build in a separate directory
	     Fix miscellaneous small bugs
	     Updated all device servers and java jar files to their
             latest release

19/08/2003 - updated to tango 3.0.2, this fixes a memory leak in the
             attributes, added the atktuning application, updated
	     starter, pogo and TangORB.

05/06/2003 - updated to tango 3.0.1, added atk and logviewer

19/05/2003 - added templates for pogo and fixed more bugs in startup scripts

10/04/2003 - fixed bug in Java startup scripts (pogo, jive, astor)
