			TACO SOURCE CODE RELEASE 2.12 - README
                        ======================================
			
				 ANDY GOTZ (14/04/2002)
				 --------------------


1. INTRODUCTION

This README describes how to use the source code release of the TACO 
object oriented distributed control system.

TACO has been developed at the ESRF for 10 years ago and is 
now being used by groups external to the ESRF. 
It is obvious that to give these external groups as much autonomy
as possible they need access to the source code. To satisfy this
request the TACO source code release has been prepared.
It is a copy of the source code development tree maintained
at the ESRF. In order to make releases quickly not much effort has
gone into changing up the directory tree structure and source code.
What you have on your disk is a copy of the latest release of the Unix
development tree. The main aim is to allow external users to have access 
to the source code and (re)compile for whatever (Unix) platform they 
need to. For Windows compilation look under WINDOWS.

2. GETTING STARTED

2.0 GNU make -

The release is organised with a main Makefile which calls the underlying
Makefiles for compiling the different packages. All the underlying Makefiles
are based on the GNU Make which supports conditional statements. Before
trying to compile anything you must have a version of GNU make which
is accessible from your $PATH environment when you type "make". GNU
make is standard with Linux. For other platforms you can find a release
of GNU make in the directory "gmake" with this release. Configure,
compile and install it for your platform if you don't have it.

2.1 configure -

In order to simplify compilation + installation a simple script called 
"configure" is povided which prompts for what platform you want to
compile on. Run configure by typing "./configure" and answer the
questions. Before running configure set the environment variable DSHOME
It will also prompt for the TACO home directory ($DSHOME) 
where you plan to keep all the TACO libraries and include files. 
This could be anywhere. At the ESRF we normally have a user account
"dserver" which we use as home directory for TACO.

If you need the TACO libraries to be compiled with additional CFLAGS 
(e.g.) -D_REENTRANT) for your system then it is possible to set and environment
variable EXTRACFLAGS before calling configure. This will be added
to CFLAGS during compilation of all libraries (DSAPI, DSXDR, DBAPI).
The configure script prompts for this flag.

2.2 make all -

Once you have configured the platform you can call "make all" to make
all the libraries and system processes.

2.3 make install -

Will copy the libraries and include files to $DSHOME/lib/$OS and
$DSHOME/include. Some of the libraries and incldue files are copied
when you do "make all" as part of the TACO boot-strapping process.
Will also remake dsapi and dsapi++ because of the "make clean" rule
in the makefile.

2.4 make test -

Will fill the TACO database up with some default resources, start
a TACO Manager and then start a test device server (Inst_verify) and 
client (Inst_verify_menu).

2.5 make clean -

Will remove all object files.

2.6 make clobber -

Will do a clean and remove all libraries. It is a good idea to do a
clobber before compiling on a new platform to avoid mixing object
files and/or libraries.

3. LIBRARIES

The TACO system has three fundamental libraries - DSAPI, DSXDR and DBAPI.
These libraries are fundemental to creating any TACO server or client.
The source code release contains all the source code for them and Makefiles
for generating archive and shared library versions. They can be found
in the following directories :

DSAPI - ./dserver/system/api/apilib/src
		./dserver/classes/main/src
		./dserver/classes++/device/src

	DSXDR - ./dserver/system/xdr/src

	DBAPI - ./dbase/src

The libraries are installed in :

	./lib/$OS

The corresponding include files in :

	./include
	./include/private

4. SYSTEM PROCESSES

TACO requires three system process to run - the Manager, Database and
Message servers. The source code release contains the source code and
Makefiles to generate them. They can be found in :

	MANAGER - ./dserver/system/manager/src

	DBSRVR - ./dbase/server/src

	MSGSRVR - ./dserver/system/msg/src

Once compiled they are installed in :

	./system/bin/$OS

TACO also supports a data collector. The data collector is a distributed
memory for caching device responses so that they can be retrieved quickly
either singly or in grouped calls. The data collector improves the performance
of clients in large systems (> 1000 devices). The source code relase now 
contains the system processes + tools necessary to install and run the
data collector. Refer to the manual for more information about the data
collector.

5. DATABASE TOOLS

TACO supports a very simply database based on the GNU DBM library. DBM
is based on a single key and one file per table. Some tools are provided
for analysing the contents of the database. They can be found in :

	DBTOOLS - ./dbase/tools/src

Once compiled they are installed in :

	./system/bin/$OS

6. CHANGES

6.13 Changes from V2.11 to V2.12 (14/4/2002)

(o) includes latest releases of DSAPI V8.40 which supports running
    TACO device server and clients without the database (TACO-lite)
    This can be useful for very small projects or embedded servers.

(o) the new DSAPI library is not backwards compatible for device
    servers compiled with the old include files (pre-V8.40) and
    libraries because of an extra field in the commands list
    (needed by TACO-lite), therefore
    
(o) a MAJOR change has been made to the versioning of SHARED LIBRARIES. 
    Previously TACO shared libraries did not include the version
    number as part of their internal name. Now the shared libraries
    include the version number as part of their name e.g. "libdsapig++.8.40.so"
    instead of simply "libdsapig++.so". This prevents newly compiled
    device servers from using the old shared libraries (which are
    incompatible). This also means all clients and servers who want
    to use the new version of the shared libraries must be recompiled.

(o) minor bug fixes to makefile for Solaris.

6.12 Changes from V2.9 to V2.10 (12/11/2001)

(o) includes latest release of DSAPI V8.30 and DSXDR V5.21 which have 
    been updated for Windows 95/98/NT/2000.

6.11 Changes from V2.8 to V2.9

(o) includes latest release of DSAPI V8.20 which has two important patches

    (1) patch by Bjoern Pedersen (FRM II) which adds support to query a
	server for what events it supports.

    (2) patch by Jonathon Quick (HartRAO) which adds support for double
        arrays as resources in the TACO database.

6.10 Changes from V2.7 to V2.8

(o) added data collector server and tools 

(o) removed TACO manual from source code release. It can be dowloaded 
    separately from ftp://ftp.esrf.fr/pub/cs/taco/TACO.pdf

6.9 Changes from V2.6 to V2.7

(o) latest version of DSAPI (V8.18) supports dynamic error messages for device
    servers.

(o) TACO manual (in pdf format) included.

6.8 Changes from V2.5 to V2.6

(o) included dcapi in source code distribution. The dcapi is a library for
    accessing the TACO data collector - a distributed cache which is filled
    by polling device servers. The data collector is particularly useful for
    large ( > 1000 devices) TACO systems. But can be interesting for small
    systems too as a means of sharing data between servers and clients.

6.7 Changes from V2.4 to V2.5

Added patches supplied by Bjoern Pedersen (FRM II project) to do the following :

(o) added support for D_USHORT_TYPE and D_ULONG_TYPE resources to database

(o) fixed bug in event_api.c and asyn_api.c which caused servers and clients 
    to crash if dev_event_unlisten() was called before dev_event_listen()
    or after a server had been restarted.

6.6 Changes from V2.3.1 to V2.4

(o) new release of DSAPI (V8.13) which improves the event interface,
    adds a call to change the import timeout, provides support for 
    importing TANGO devices from TACO

(o) extra compile flag support added (EXTRACFLAGS).

6.5 Changes from V2.3 to V2.3.1

(o) new release of DSAPI (V7.10) which fixes problem with gettransient 
    prototype. Removed all fprintf(stderr) for C++.

(o) fixed problem with Makefile++ for DSAPI C++.

(o) make test now compiles and starts the AGPowerSupply C++ device
    server.

6.4 Changes from V2.2 to V2.3

(o) included all patches from M.Diehl (FRM II). These fix a number of
    problems including (o) race condition when starting TACO manager
    and message and database servers which led to portmap forking
    (under Linux), (o) improved more efficient algorithm for getting
    device server transient program numbers, (o) bug in security
    api.

(o) fixes a major bug in the event api which was causing multiple event
    clients to crash

(o) new release of DSAPI (V7.9) includes new g++ support for Solaris

(o) latest versions of manager, message and database servers

(o) included C++ example device servers for AGPowerSupply and SerialLine

(o) tested on Mandrake 6.1, SuSE 6.1 and SuSE 6.2 Linux distributions

(o) includes source code for xdevmenu graphical client, greta graphical
    database editor and source code, documentation and example for
    TACO signals (normalised data types).

6.3 Changes from V2.1 to V2.2

(o) included gdbm source code package (to avoid problems with ndbm
    on various platform)

(o) added missing Linux support in Manager

(o) new make target test will start a mini TACO control system

(o) new release of DSAPI (V7.4) includes patch from M.Diehl

(o) new release of DBAPI (V6.9) includes patch from J.Quick

(o) new release of DSXDR (V5.18)

6.2 Changes from V2.0 to V2.1 

(o) cleanup of RCS and binary files in source code release. Now
    the entire TACO source code release fits on a 1.4 MB floppy
    with room to spare !

(o) bug fixes in Makefile for Solaris

6.1 Changes from V1.0 to V2.0 

In the second release of the source code the following changes
can be noted -

(o) DSAPI V7.x includes user events (implemented in event_api.c)
    for the first time. For documentation on how to use events
    refer to http://www.esrf.fr/computing/cs/taco/doc/events.html
    for online documentation. DSAPI V7.2 also includes a number
    of bug fixes w.r.t. to the last version.

(o) DBAPI V6.x includes new client calls required by GRETA.

(o) Database server and tools have been rewritten in C++ and
    include support for GRETA.

(o) GRETA is a GRaphical Resource editor for TAco which is
    written using Motif. It requires the database server in
    this release to run. It has been bundled with this release for 
    those who want to play around with it. All the source code and
    include files + makefile are in ./dbase/greta. It is not
    part of the "make all" targets because Motif is not part
    of the standard installations. If you want to use it modify
    the Makefile to point to the right areas for Motif and
    run make. GRETA is a useful tool for editing TACO resources.

(o) fixes compile problem for Linux which caused rpc programs to 
    bomb on RedHat distributions.

7. TESTING

This release assumes you have a running TACO installation and know
a bit about TACO. If this is your case all you need to do is point
your shared library path ($LD_LIBRARY_PATH on Linux/Solaris) to the
directory where you have created the shared libraries and restart
your device server/client. Alternatively you can recompile you
device server/client if you are using archive libraries. The main
advantage of the source code release is you will be able to modify
and generate new versions of the TACO libraries at will now.

If you have never used TACO before then you better send an email
to "taco-guacamole@esrf.fr" or "goetz@esrf.fr" for more detailed
instructions. In brief you have to start setup a database, start
the Manager and then start as many device server/clients as necessary.
Device server/clients which know about your hardware will have
to be written. An example for C++ can be found in dserver/classes++/powersupply.
It consists of a superclass PowerSupply.cpp and the subclass AGPowersupply.cpp.
A second example of a real device server for controlling a serial line
under Linux can be found in dserver/classes++/serialline.
An example for C (using the Objects In C methodology) can be found
in dserver/classes/instverify.

8. PROBLEMS

Of course you will have some. Please report them to "taco@esrf.fr"
or "goetz@esrf.fr" and we will do our best to answer you and include
your problem in this section in the future.

Here is a (non-exhaustive) list of problems you can encounter :

(o) the database server does not compile correctly - the most likely reason
    is that you do not have the a version of the GNU C++ compiler which
    includes the standard C++ library. Make sure you have it. You can download
    it from the web for Solaris from http://www.sunfreeware.com. For Linux
    it comes packaged with the distributions SuSE 6.1 and RedHat 5.2. If
    you do not have one of these distributions you can download the egcs
    compiler (the new gcc) from http://egcs.cygnus.com.

9. DOCUMENTATION

Take a look at http://www.esrf.fr/taco/taco.html. If
you don't find what you are looking for there send an email.

10. PLATFORMS

At the ESRF TACO has been ported to over 10 platforms. Of these "only"
6 of them are maintained or updated regularly. The remaining ones
are done on request. The "configure" and "Makefile" included with
this release are the main Unix and Unix-like platforms. The platforms
concerned are -

	(o) Linux using gcc/egcs on 80x86 - more and more used
	    at the ESRF for controls it is one of the main development
	    platforms at the ESRF. Present projects include the PCI,
            CompactPCI and PC/104 based TacoBoxes e.g. for serial 
            lines. At the ESRF we use the SuSE 6.4 distribution 
            package for Linux but the source code should compile and 
            run on any (recent) Linux distribution. It has been
            tested on SuSE 6.1 and 6.4 and Mandrake 7.0.

	(o) Linux using gcc on 680x0 - is proposed as the future standard
	    frontend OS to replace OS9. Presently there are not many 
	    device servers running under Linux/m68k but porting is actively 
	    going on.  The exact same code is used for Linux/68k and Linux/x86.

	(o) Solaris using native compiler - one of the standard console
	    operating system used at the ESRF. Tested on Solaris 7.
	    The database server still needs g++.

	(o) HP-UX 10.20 using native compiler - another standard console
	    operating system used at the ESRF.

	(o) OS9 using Ultra-C cross compiler for 68k - the standard
	    frontend operating system used at the ESRF. Recently frozen
	    we are proposing to replace it with Linux.

	(o) VxWorks - used at the ESRF only for research purposes.
	    Libraries were ported to VxWorks on x86 and 68k in the past. 
	    No guarantees made about the present release.
	    But if you have problems send an email and we will try to
	    help you.

11. WINDOWS

This source code release is the same as for Windows. However if you
need the Windows port which uses Visual C++ then download the Windows
version ftp://www.esrf.fr/pub/cs/taco/Taco_win32_V8_29.zip where
you can find a source code distribution for Windows complete with
Visual C++ project files, and a version of ONCRPC for Windows 

12. TO DO

Many things ! The main improvements on the to do list are -

(o) use autoconfig to customize Makefiles 

(o) include all the good suggestions made by external users on 
    improvements to the source code

(o) test source code distribution on all platforms

13. TANGO

The next generation of TACO is called TANGO. It is based on CORBA, C++ 
and Java. The first version will be supported on Linux/x86, Linux/68k, 
Windows, HP-UX and Solaris. At the ESRF we are actively working on it.
Some of you might ask should I bother with TACO if TANGO is coming? The
answer is YES ! TANGO is based on the same concepts as TACO i.e. 
distributed objects served by device servers. One of the requirements 
of TANGO is to be able to take TACO device classes and serve them
from TANGO device servers with only minor changes. Therefore if you
are interested in TACO/TANGO you can start with TACO and migrate
to TANGO later on. TACO is also lightweight compared to TANGO
so if you have restrictions in terms of memory footprint and/or
speed then TACO can be for you. Client applications can use the TACO 
api to call TANGO devices and vice versa. Therefore it is possible to 
have a mixed TACO and TANGO system. For example TANGO can be used
for writing Java applications which talk to underlying TACO servers.
This is used at the ESRF. 

TANGO is now available for external users. Contact "tango@esrf.fr" 
for the source code.

