This is version 1.0.10 of the Condor Classad library, released on 2011-04-08.

===== What is it? =====

Classified Advertisements (or ClassAds) are the lingua franca of
Condor. (You can learn more about Condor at our web page:
<http://www.cs.wisc.edu/condor/>.) They are used for describing jobs,
workstations, and other resources. They are exchanged by Condor
processes to schedule jobs. They are logged to files for statistical
and debugging purposes. They are used to enquire about current state
of the system.

A ClassAd is a mapping from attribute names to expressions. In the
simplest cases, the expressions are simple constants (integer,
floating point, or string). A ClassAd is thus a form of property
list. Attribute expressions can also be more complicated. There is a
protocol for evaluating an attribute expression of a ClassAd vis a vis
another ad. For example, the expression "other.size > 3" in one ad
evaluates to true if the other ad has an attribute named size and the
value of that attribute is (or evaluates to) an integer greater than
three. Two ClassAds match if each ad has an attribute requirements
that evaluates to true in the context of the other ad. ClassAd
matching is used by the Condor central manager to determine the
compatibility of jobs and workstations where they may be run.

Although ClassAds are used extensively within the Condor project, they
are a general-purpose mechanism. This library is being distributed in
the hope that you will find it useful for your own purposes.

===== Credits =====
This version of the ClassAd library was written by Rajesh Raman. Small
contributions and bug fixes where contributed by Su Zhang, Nick
Coleman, Alain Roy, Dan Bradley and Jaime Frey, but really, Rajesh did
all of the real work. Jaime Frey is currently responsible for
maintaining the code.

The original ClassAd library (still in the process of being phased out
and replaced by this new implementation within Condor itself)
was written by various members of the Condor team, with ideas and
inspiration from Miron Livny and Marvin Solomon. Although nary a wisp
of that original code exists in this new implementation, the
everyday use and experience with the original code provided much of the
guidance and inspiration for this version.

===== Status ===== 
Please see the CHANGELOG for information about this and previous
versions.

===== Documentation and Help =====
There is some documentation online at: 

    http://www.cs.wisc.edu/condor/classad/

Also examine "sample.cpp", which is a small sample program that should
help you get started.

If you encounter problems that are not solved by the online
documentation or your own perseverance (you do have the source code!),
you have two options:

1) We encourage you to subscribe to the ClassAd mailing list. This
list is for discussion among all ClassAd users, and for occasional
announcements related to ClassAds. To subscribe, send an email to
"majordomo@cs.wisc.edu" with 

subscribe classad-users

in the body of your email. You will be required to confirm your
registration. At least one of the ClassAd developers reads this
mailing list. 

2) If you are unable to resolve your problems on your own or through
the ClassAd mailing list, please email the developers:
condor-admin@cs.wisc.edu. Please make sure that "ClassAd" is in your
subject line. We will do the best we can to answer questions, but
please realize that it sometimes takes a while to do so.

===== License ===== 
The Condor ClassAd library is an open source release, under the terms
of the Apache License, Version 2.0. Please see the LICENSE-2.0.txt file
for more information.

===== Building ===== 
We have built the ClassAd library on Linux, Mac OS X, Solaris and Windows.
Hopefully it will build on other systems. If you are trying to build on
Windows, you can skip the following section and proceed to the next
section entitled, "Building on Windows".

Building is a two step process: configure and make. The configure
script is generated from autoconf and has the usual arguments.

Note: On old version of gcc you may need to add CC=g++ to configure.

  ./configure --enable-namespace CC=g++

After the configuration step, build and install ClassAds with:

  make
  make check (optional)
  make install

Notice that when the library builds, there are a number of programs to
test Classads. You can run them with "make check". You might find
these programs useful as examples.

===== Building on Windows =====
In order to build on Windows, you must have Microsoft Visual Studio 6.0
installed. It is possible that Microsoft Visual Studio.NET will import
the project files and work as well, but we haven't verified this to be
true.

You must also have STLport (www.stlport.org) installed, since the
STL implementation included with Microsoft Visual Studio is inadequate
for building the ClassAd library.

Note that we assume most developers are building with a new (February,
2001 or newer) Microsoft Platform SDK. If this is not the case, you must
remove the line

#define _STL_NEW_PLATFORM_SDK

in common.h.

We have included files that allow you to build the library from both
the command line and from within Visual Studio.

If you wish to build from the command line, you must edit make.bat
(in the win32 directory) to reflect the location of the STLport header
files. You must also make sure that the command line tools are installed
(such as nmake.exe and vcvars32.bat ) and in your PATH. Finally, just type
'make' (or 'make debug' for a debug build).

If you prefer to build the library from within Visual Studio, you can
simply load the classad_dist.dsw workspace file, and hit F7 to build. You
may also have to add the STLport header files to your include path for
Visual Studio. To do this, go to Tools->Options, select the Directories
tab, and then select Include files. Then add the path to your STLport
header files.

Once the build is complete, the ClassAd library should be located
./Release.

===== Using the ClassAd library =====
Once the ClassAd library has been used, you can use it in your C++
programs. You need to include a single file, "classad_distribution.h",
and link with a single library, "libclassad.a". 

===== Feedback =====
Please provide us with feedback. Your feedback will help us make
future versions the best they can be. If you find bugs, missing
features, or signs of insanity, please let us know by contacting us at:
condor-admin@cs.wisc.edu. Please include "ClassAd" in your subject
line. 
