VOClient v1.0 -- VO Interfaces and Applications
	     -----------------------------------------------

		        Last Revised 12/27/13



	The VOClient package is a collection of programming APIs and
command-line tools that provide a user-ready VO software distribution for
both scientists and developers.  The initial release of the package is
intended primarily to distribute the completed CLI tools, additional tasks
are planned as new functionality is added to the libraries and as new
standards come on-line in the VO.  

	Although the underlying libraries are included in this release 
and are fully functional, they lack the documentation and multi-language
interfaces we have planned for the final vision of the package.  We 
expect a release that better supports developers will be available in
mid-2013.  Later releases will contain additional interfaces and tasks
as needed.


    README		- This file
    TODO		- ToDo list

    Makefile		- Top-level makefile
    configure		- pseudo autonf package configuration script
    install_env		- package installation environment defs

    bin			- application binaries
    doc			- documentation, design notes, etc
    include		- library include files
    lib			- libraries

    common		- shared dependency library codes
    libsamp		- SAMP interface
    libvo		- VOTable parser
    libvoclient		- Client side service code
    libvotable		- VOTable parser

    voapps		- CLI application source code
    voclient		- Java VOClient Daemon source code

    test-data		- sample test data files
    testscripts		- sample task test scripts


NOTE:   The 'test-data' directory may contain some files that are used by
	the task unit tests, but are generally of no interest to most users.
	Users who are developing applications using the various interface
	libraries may find the sample files in this directory useful when
	testing new applications, however these are not meant to be a
	complete collection of sample data available from the VO.
   

Contents:

    1)  CLI Task Summary
    2)  Client-Side Libraries
    3)  Using Pre-Built Binaries
    4)  Building VOClient from Source
      4.1)  Specifying the Install Directory
    5)  Supported Platforms
      5.1)  Platform Dependencies
    6)  Revision History
    7)  Help and Contact Info


===============================================================================


1)  CLI Task Summary
--------------------

	The VOClient package includes a number of command-line utilities
built from the underlying interfaces.  These tasks can be scripted from any
number of environments or used in a standalone manner.  

Tasks distributed as part of this release include:

  DATA ACCESS UTILITIES

        voatlas - Query the SkyView Image service for an all-sky image
      vocatalog - Query VO catalog services for data
         vodata - query and access VO data services
        voimage - Query VO image services for data
      votiminfo - Print/Get information about a FITS file's structure
      vospectra - Query VO spectral services for data
        votopic - Query for data from resources specified by topic keyword

  DESKTOP MESSAGING UTILITIES

         vosamp - Commandline SAMP utility

  NAME RESOLUTION UTILITIES

       vosesame - call the Sesame name resolver service

  REGISTRY UTILITIES

     voregistry - VO Registry search client

  VOTABLE UTILITIES

         votcnv - Convert from VOTable to another format
         votget - Download URLs or access references in a VOTable
        votinfo - Get information about a VOTable
         votpos - Extract the main positional columns from a VOTable
        votsort - Extract the main positional columns from a VOTable
        votstat - Compute statistics for numeric columns of a VOTable.


    Additional tasks will be added as interfaces are expanded and new
capabilities are added to the system.


2)  Client-Side Libraries
-------------------------

    The VOClient provides a number of APIs to support developers building
science applications of their own, or for use in other environments. These
libraries are implemented in C and provide additional bindings for a number
of VO supported languages.  Each interface is fully documented and higher-
level "User's Guide" documentation is planned for each interface.


  libVOApps         High-level interface to application functionality.
                    Tasks are built on these routines to provide the
                    cmdline user interface, but are encapsulated in an
                    API to provide this functionality to other environ-
                    ments easily (as opposed to having that functionality
                    be re-implemented using the low-level interfaces).

  libVOTable        A VOTable parser library.  The interface provides
                    both read (lax parsing) and write (strict compliance)
                    capabilities.  Reference is VOTable v1.2.

  libVOClient       A VO Service interface library.  This interface uses
                    the VOClient Daemon to access a variety of VO web
                    services (Registry, Sesame, DAL services, etc) which
                    then communicate to the API to pass information back
                    to the application.

  libsamp           Client-side SAMP interface library.  This interface
                    allows an application to send and receive SAMP
                    messages but does NOT (at this time) provide a local
                    Hub implementation.  Applications can register their
                    own functions to be used as callbacks in response to
                    a message, the API provides only the middle-ware needed
                    to handle the SAMP protocol.

  libVO       	    A combined library containing the above interfaces and
		    their dependent system libraries (e.g. cURL, eXpat, etc).
		    This is a convenience library to allow simplified linking
		    of applications and is used primarily in the IRAF/VO
		    task interface.


3)  Using Pre-Built Binaries
----------------------------

	Pre-built binary distributions are available containg both source
and binaries for a specific platform.  These distribution names are of the
form
	voclient-<version>-bin.<arch>.tar.gz

They may be unpacked with the command

	tar zxf /<path>/voclient-<version>-bin.<arch>.tar.gz

This will produce a 'voclient' subdirectory containing the unpacked
distribution.  Within that directory you'll find the following important
directories needed to install the package on the system:

	bin/		Task binaries
        doc/            Task man pages, HTML and PDF
	lib/		API library files
	include/	Program header files

The contents of these directories should be copied to some system directory
available in the normal user paths.  For example, to install in /usr/local

	% cd /<path>/voclient
	% sudo cp bin/* /usr/local/bin
	% sudo cp lib/* /usr/local/lib
	% sudo cp include/* /usr/local/include
	% sudo cp doc/* /usr/local/man/man1

When compiling new applications the appropriate '-I' and '-L' flags will
need to be set to find the libraries and include files needed.  The binary
installation directory should be some directory in the normal $PATH
environment setting.


4)  Building VOClient from Source
---------------------------------

    The source distribution of the release is contained in the file

	voclient-src.tar.gz

It may be unpacked with the command

	tar zxf /<path>/voclient-src.tar.gz

This will produce a 'voclient' subdirectory containing the unpacked
distribution.  A standard build sequence then consists of the commands:

	% ./configure
	% make 
	% make install

By default, this sequence will install the voclient package under
/usr/local.  That is, "make install" will copy files into the following
subdirectories of /usr/local:

        bin/            Task binaries
        lib/            API library files
        include/        Program header files
        man/man1/       Task man pages

Thus, you need to run at least "make install" as root.  If these
directories do not exist, they will be created automatically if you run
"configure" as root as well.


4.1)  Specifying the Install Directory
--------------------------------------

To specify an alternate install directory, the 'configure' script may be used
as:
	./configure [ <opts>=<val> | <opt> <val> ]
 
Where options include:

	    -h  -help    --help         print a help summary
            -p  -prefix  --prefix       set global path prefix
            -b  -bindir  --bindir       task bin directory
            -i  -incdir  --incdir       include file directory
            -l  -libdir  --libdir       library directory
            -m  -mandir  --mandir       man page directory
 
For example, the following commands are all equivalent for setting the global
install path prefix to /opt/local:
 
        % ./configure --p /opt/local
        % ./configure -prefix /opt/local
        % ./configure --prefix /opt/local
        % ./configure -p=/opt/local
        % ./configure -prefix=/opt/local
        % ./configure --prefix=/opt/local

The individual path options to the configure script may be used to specify 
paths for each component of the install.

Note:  	The 'configure' command in this case is not a true autoconf script,
       	but simply a utility to provide a familiar interface.  The script
	writes the file "install_env" in the voclient source directory to
	specify the paths used in the 'make install' command, it is possible
	to edit this file by hand to specify the paths.


5)  Supported Platforms
-----------------------

    This release currently supports the following platforms:

    Mac OSX		32-bit and 64-bit Intel, OSX 10.6 and later
    Linux 32-bit	32-bit Linux systems (Fedora, Redhat, Ubuntu, etc)
    Linux 64-bit	64-bit Linux systems (Fedora, Redhat, Ubuntu, etc)

Additional platforms will be added as needed.

    Compilation flags are used to provide compatibility for OSX 10.4 on
32-bit systems, and OSX 10.5 on 64-bit systems, however these have not been
verified to work.  Linux support should be reasonably independent of platform
and has been tested on the most common distributions released within the
last few years.

5.1)  Platform Dependencies
----------------------------

	The 'voclientd' process used in the initial release requires that
Java is available on the machine (Java 1.5 or later).  On recent OSX 10.9
(Mavericks) systems, and perhaps with some Linux distributions as well, 
Java must be installed separately before the tasks can be used.



6)  Revision History
--------------------

12/27/13	    Initial Release v1.0


7)  Help and Contact Info
-------------------------

    For help, questions or suggestions please feel free to contact 
Mike Fitzpatrick ([email protected]) or the VAO Help Desk at

	http://www.usvao.org/contact-connect/

Questions may also be posted the VAO forums at

	http://astrobabel.net