TACO SOURCE CODE RELEASE 2.9 - README ====================================== ANDY GOTZ (10/01/2001) -------------------- 1. INTRODUCTION This README describes how to use the source code release of the TACO object oriented control system. TACO has been developed at the ESRF about 10 years ago but has only recently been started to be 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 basically a copy of the source code development tree maintained at the ESRF. In order to make a quick release 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.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-guacamole@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/computing/cs/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. Still only using Solaris 5. Port to Solaris 7 will be undertaken shortly. (o) HP-UX 10.20 using native compiler - another standard console operating system used at the ESRF. (o) HP-UX 9.x using native compiler - precurser to HP-UX 10.20 which will eventually be faded out. (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. Recently all the libraries were ported to VxWorks on x86 and 68k. 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 intended only for Unix platforms. If you need the Windows port which uses Visual C++ then refer to the web page http://www.esrf.fr/computing/cs/taco/dsapiNT/readme.html where you can find a source code distribution for Windows (based on DSAPI V5.15). 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. The main difference between TACO and TANGO is the client API. Client applications will have to be rewritten or use a gateway to continue running. TANGO will be available late 1999 for external users.