TANGO source code release V5.5.0 - README ========================================= Jens Meyer (meyer@esrf.fr) ------------------------i------- 14/08/2006 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, ELETTRA, ALBA and SOLEIL synchrotron radiation sources. This source code release is based on the latest version of TANGO 5.5.0 and is intended for Unix platforms. A binary version for Windows of TANGO is available. 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 library and application jar files (2) The Tango database device server source files (using mysql) and the MySql configuration files. (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 (9) The atkpanel application as a generic test client (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 (13) The atkmoni application to monitor scalar attribute values in time (14) The jdraw synoptic editor to create synoptic applications (15) The synopticAppli to run and test synoptics created with jdraw 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/computing/cs/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/computing/cs/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/computing/cs/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 available from http://sourceforge.net/projects/omniorb (version >= 4.0.5) (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 options "--with-mysql-admin" and "--with-mysql-admin-password" allow you to select which MySql user configure will use. The default is "root" without a password. 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-doxygen" 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.5/suse82 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.5/solaris9_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 ----------------------------------------- Starting with release 4, Tango needs the event table in its MySQL database. If you are upgrading from release 4 or older, create first the event table in your MySql database. You can find the event table definition in /share/tango/db/create_db.sql. Updating from other releases of Tango 5, you should update the corrected indexing of the database tables. Compare with the file /share/tango/db/create_db.sql. Correcting the indexing and installing a cache for MySQL will speed-up requests on a growing database. An example file for the MySql set-up is available at /share/tango/db/my.cnf 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) Configure the TANGO_HOST environment variable with the hostname the database server is running on and the port number used. setenv TANGO_HOST hostname:10000 (3) start the test device server tangoTest : TANGO_INSTALL_DIR/bin/TangoTest test -v (4) start jive by typing for example : TANGO_INSTALL_DIR/bin/jive (See chapter 4 java sub-chapter to check the jive script) (5) test your device using the test device in jive (6) 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.5.pdf) ! 9 - REMARKS ----------- The new version of the database server has increased the limit of open file descriptors from 256 to 1024 (for UNIX platforms!). The command line option "-maxFile" allows to change this configuration. The new version of the starter server implements a better sequencing for starting Tango server processes and introduces a MOVING state to indicate the running start-up sequence. The included version of the Astor application handles this new state. When using events with Tango, two diagnostic tools are available. The astor application allows to configure and test the available events. Under the view menu open the Device Browser. Choose and open your device. Right click on an attribute to subscribe and configure events for this attribute. The atkpanel applications offers under the view menu a diagnostic panel which shows the availability of events and some statistics. 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 ------------ 14/08/2006 - Updated to tango CPP release 5.5.0 ---------------------------------- - Stopped the automatic polling startup of attributes at event subscription. All polling has be be configured manually! Subscription to events is only possible if the event properties for an attribute are properly configured and the polling is started! - An exception during initialisation of memorized attributes will no longer result in an exit of the server. - Memorized attributes can be used in two ways now. 1) The setpoint gets initialised during a server startup. No write happens on the attribute. 2.) The setpoint gets initialised during a server startup and is written to the attribute. The initialisation mode can be triggered by Attr::set_memorized_init(bool write_on_init) method during attribute creation. The two options are supported by Pogo. - The archive event behavior has changed. The archive period is no longer set to 10 seconds as default. If no period is specified, no periodic archive event is send. - Change and archive Events can be pushed manually from the code now without polling. Two ways are possible: 1.) Push events but check the event configuration (as the polling thread). Events are fired exactly under the same conditions as with the polling. 2.) Push events without configuration check. The event is fired without any value checking. - The quality event was removed and integrated as filter "quality" to the change event. - The user event was adapted to follow the structure of pushing change or archive events. - Event reconnection will follow now when a server was moved to a different host. The connection will be rebuild to the new notifd. - Polling configuration for attributes and commands specified in the code with Pogo are written to the database at server start-up. The polling will start immediately and no longer on a first reading request. - The transparent reconnection is now the default reconnection mode. - Naming requests to the database are cached for a DeviceProxy. A reconnection request will be emitted only once a second for a DeviceProxy connection. The same feature is implemented in the Java api. - Debugging is now possible with the Linux 2.6 kernel. - Support of gcc 4.0 - Support of VC7 and VC8 under Windos. - Integration of code for device servers written in Python (PyTango 3.0) - Bug fixes: - Corrected the wrong archive period reading after a server restart. - Changed DServerClass::instance() to return an exception in the case of a not initialised object. The exit() killed the server during a startup when a client sends requests to early. - Changed the clean-up mechanism when shutting down the ORB. Destroy ORB when returning from run(). In 5.3 This was done in the main and when missing caused some threads to hang-up with the Linux kernel 2.4.x. - Avoid calling Device_3Impl::status2attr() during attribute reading when an error was detected. Avoids segmentation fault in status2attr(). - Corrected event priod handling for periodic events. - Corrected rounding errors when checking the conditions. of change and archive events. - Corrected constructor for the class GroupReply. Updated TangORB to release 4.9.2 Updated Database device server to release 2.6.0 + patches Updated Starter device server to release 3.4 Updated TangoTest device server to release 1.2 Updated LogViewer to release 1.2.1 Updated Atk to release 2.5.1 Updated AtkPanel to release 2.7 Updated DeviceTree to release 1.6 Updated Jive to release 3.3 Updated Pogo to release 4.5.6 Updated Astor to release 4.3.2 Updated AtkTuning to release 2.7 Added EventTester release 1.0.5 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)