Contents of this Cougaar Release

This file documents the contents of this release and the general layout of Cougaar software modules. When you download a Cougaar release, there are several logical pieces.

BUILD ORGANIZATION

Cougaar is divided into modules, from the various cougaar.org projects that make up CougaarSE. This is a list of the various zip files available from releases.

cougaar.zip Cougaar runtime - all "lib/" (runtime jars) and "clib/" (build-time jars) jar files, run scripts ("bin/", configuration files ("configs/", including the usual configs/common directory), and minimum documentation ("doc/"). Additionally, most modules (see below) include directories with additional documentation and configuration files. Javadoc and source code is not included.
cougaar-support.zip Third-party supporting jar files. Unpacks into "sys/" subdirectory where the Cougaar Bootstrapper will find them, without modifying your CLASSPATH. Built from the "jars" module in the Cougaar core project.
cougaar-api.zip The Javadoc for all the main cougaar classes in one place. Unpacks to "/doc/api", putting the Javadoc with the module where the source originates.
cougaar-src.zip Source code for each "lib/" module. Unpacks to per-module directories, as in core/src/.... Often include JUnit tests in a "regress" sub-directory, and examples.
md5sums.txt MD5 checksums for all the above zips.
build.out Output of the build process
errors.out Error output of the build process, including deprecation warnings.

Notes:

You'll need cougaar.zip and cougaar-support.zip (the first time) to get a runnable system. The rest are extras. Furthermore, the cougaar-support contents do not change very often.

The zips are designed to be unpacked in the same directory, e.g. on UNIX:

       mkdir cougaar
       cd cougaar
       unzip /tmp/cougaar.zip
       unzip /tmp/cougaar-support.zip
       setenv COUGAAR_INSTALL_PATH `pwd`

The zips include version information in their respective "Manifest/" directories. The content looks something like:
```
       NAME=cougaar-support
       COMMENT=cougaar thirdparty jars
       REPOSITORY_TAG=V10_0                 # CVS branch
       REPOSITORY_TIME=1/28/2003 13:00:08   # CVS checkout time
       ARCHIVE_TIME=1/28/2003 13:29:27      # zip time
```
All your zips should have the same REPOSITORY_TAG and REPOSITORY_TIME. Each generated "lib/*.jar" file also contains its version information.

MODULE LIST

The Cougaar software distribution (cougaar.zip) contains a number of separate modules of related classes with supporting documentation and sources. The modules roughly correspond to separate Cougaarforge projects, though some projects contain multiple modules.

Each module typically produces a single Jar file in "lib/", as well as a directory "COUGAAR_INSTALL_PATH/" which contains data files, scripts, documentation, etc. Here is a list of those modules, in approximate order of compilation dependency or extra functionality. For detailed dependency information, see "build/data/default.build".

Module Cougarforge home Description

base http://cougaar.org/projects/util/ Provides "doc/" (these docs), "configs/" (basic config files), and "bin/" (base run scripts).
build http://cougaar.org/projects/build Release and build scripts, with code generators. Builds the Cougaar zips.
javaiopatch http://cougaar.org/projects/core/ Patch to jdk's java.io to support incremental persistence of Agents with Blackboards.
bootstrap http://cougaar.org/projects/util/ Class loader that scans "lib/*.jar" and "sys/*.jar", so Cougaar needs no CLASSPATH edits.
util http://cougaar.org/projects/util/ Utility code, including the Cougaar Component Model and Log4j logging facility.
core http://cougaar.org/projects/core/ Criticial Core Cougaar infrastructure (including Node, Agent, Blackboard, etc).
planning http://cougaar.org/projects/planning Planning domain for Tasks, Assets, etc.
contract http://cougaar.org/projects/util Experimental predicate language, used by /tasks servlet advanced queries.
mtsstd http://cougaar.org/projects/mts Standard Cougaar Message Transport System (threaded, many lanes, several protocols)
quo http://cougaar.org/projects/qos/ Quality of Objects support (metrics).
qos http://cougaar.org/projects/qos/ Quality of Service support (for MTS).
ping http://cougaar.org/projects/qos Ping application for simple performance testing.
yp http://cougaar.org/projects/yp Distributed hierarchical yellow pages directory service (UDDI).
tutorial http://cougaar.org/projects/tutorials The Cougaar tutorials.
webserver http://cougaar.org/projects/webserver/ Servlet service support excluding the server itself. itself.
webtomcat http://cougaar.org/projects/webserver/ Tomcat servlet server implementation for use by webserver module.
webaxis http://cougaar.org/projects/cws/ Web Services support for Cougaar: send and receive SOAP calls from Cougaar plugins, and use SOAP as an MTS protocol.
community http://cougaar.org/projects/community Agent peer group support.
servicediscovery http://cougaar.org/projects/servicediscovery Agent discovery & dynamic relationships using the yellow pages.
pizza http://cougaar.org/projects/tutorials Pizza Party sample application.
toolkit http://cougaar.org/projects/glm/ Collection of utilities for manipulating planning Tasks for logistics.
glm http://cougaar.org/projects/glm/ Generic Logistics Model domain. Defines "Organization".
aggagent http://cougaar.org/projects/aggagent Agent that aggregates data from multiple remote agents for scalable UIs.
vishnu http://cougaar.org/projects/vishnu Optimizing transportation scheduler.
albbn http://cougaar.org/projects/logistics Adaptive Logistics plugins and domain.
datagrabber http://cougaar.org/projects/logistics UI showing results of Adaptive Logistcs applications.
stoplight http://cougaar.org/projects/logistics Alerts on results of Adaptive Logistics applications.
csmart http://cougaar.org/projects/csmart A Cougaar configuration and experimentation UI. See CSMART Docs.
server http://cougaar.org/projects/util/ Application server (daemon) to launch Cougaar nodes.

Module	Cougarforge home	Description
base	http://cougaar.org/projects/util/	Provides "doc/" (these docs), "configs/" (basic config files), and "bin/" (base run scripts).
build	http://cougaar.org/projects/build	Release and build scripts, with code generators. Builds the Cougaar zips.
javaiopatch	http://cougaar.org/projects/core/	Patch to jdk's java.io to support incremental persistence of Agents with Blackboards.
bootstrap	http://cougaar.org/projects/util/	Class loader that scans "lib/.jar" and "sys/.jar", so Cougaar needs no CLASSPATH edits.
util	http://cougaar.org/projects/util/	Utility code, including the Cougaar Component Model and Log4j logging facility.
core	http://cougaar.org/projects/core/	Criticial Core Cougaar infrastructure (including Node, Agent, Blackboard, etc).
planning	http://cougaar.org/projects/planning	Planning domain for Tasks, Assets, etc.
contract	http://cougaar.org/projects/util	Experimental predicate language, used by /tasks servlet advanced queries.
mtsstd	http://cougaar.org/projects/mts	Standard Cougaar Message Transport System (threaded, many lanes, several protocols)
quo	http://cougaar.org/projects/qos/	Quality of Objects support (metrics).
qos	http://cougaar.org/projects/qos/	Quality of Service support (for MTS).
ping	http://cougaar.org/projects/qos	Ping application for simple performance testing.
yp	http://cougaar.org/projects/yp	Distributed hierarchical yellow pages directory service (UDDI).
tutorial	http://cougaar.org/projects/tutorials	The Cougaar tutorials.
webserver	http://cougaar.org/projects/webserver/	Servlet service support excluding the server itself. itself.
webtomcat	http://cougaar.org/projects/webserver/	Tomcat servlet server implementation for use by webserver module.
webaxis	http://cougaar.org/projects/cws/	Web Services support for Cougaar: send and receive SOAP calls from Cougaar plugins, and use SOAP as an MTS protocol.
community	http://cougaar.org/projects/community	Agent peer group support.
servicediscovery	http://cougaar.org/projects/servicediscovery	Agent discovery & dynamic relationships using the yellow pages.
pizza	http://cougaar.org/projects/tutorials	Pizza Party sample application.
toolkit	http://cougaar.org/projects/glm/	Collection of utilities for manipulating planning Tasks for logistics.
glm	http://cougaar.org/projects/glm/	Generic Logistics Model domain. Defines "Organization".
aggagent	http://cougaar.org/projects/aggagent	Agent that aggregates data from multiple remote agents for scalable UIs.
vishnu	http://cougaar.org/projects/vishnu	Optimizing transportation scheduler.
albbn	http://cougaar.org/projects/logistics	Adaptive Logistics plugins and domain.
datagrabber	http://cougaar.org/projects/logistics	UI showing results of Adaptive Logistcs applications.
stoplight	http://cougaar.org/projects/logistics	Alerts on results of Adaptive Logistics applications.
csmart	http://cougaar.org/projects/csmart	A Cougaar configuration and experimentation UI. See CSMART Docs.
server	http://cougaar.org/projects/util/	Application server (daemon) to launch Cougaar nodes.

INTRA-MODULE ORGANIZATION

Each module subdirectory is organized in a similar way in the source repository:

build.xml ANT compilation script (build-generated for CougaarSE modules).
src/ Head of java sources for module, arranged like javac would expect to see in a CLASSPATH.
bin/ Executables, scripts and support
data/ Arbitrary (static) data for runtime use.
doc/ Documentation, in text and html
configs/ Configuration directories. Usually contains only subdirectories, each is a valid configuration.
examples/ Like src, but is never shipped compiled. The build process should attempt to compile and regression-test anything in here, but generated class files are never actually shipped.
regress/ Unit test sources for this module. Will be compiled and run by build process, reporting on compile, runtime and test failures. produced binaries are never installed or packaged. test should be the root of a java package tree - consider following "junit" format conventions.
test/ For Cougaar integration team use. May contain additional regression tests and jigs. Suggested format for organizations submitting software to the cougaar maintainers is a mirror of the top directory, aimed at integrators. Eg:
src/ integration sources doc/ integrations notes, etc data/ configs/ ...
test will not be considered by autobuilds and will not be (re)distributed.

PACKAGE ORGANIZATION

Software intended to replace core functionality should match the below package layout (or provide detailed arguments why it should be changed).

Software intended to augment the core and/or provide optional core functionality, but is not intended to replace the "standard" software suite, should mirror the above layout rooted in a new "organization/project/product-specific" package rather than override the core's "org.cougaar" package names. For example, an alternate implementation of the agent base class

    core/org.cougaar.core.agent.AgentImpl

which was optimized for small devices might be delivered as part of company "foo"'s module as

    fooco/com.foo.cougaar.palmtop.agent.EmbeddedAgent

where:

    "fooco/" is the module
    "com.foo." is the company package prefix
    "cougaar.palmtop." is the project's root
    "agent" is the parallel to the core's package.
    "EmbeddedAgent" is the class name

None-core functionality should follow standard java package arrangement standards and so should not interset with any core packages. In particular, "org.cougaar" may only be used by core cougaar software.

cougaar.zip	Cougaar runtime - all "lib/" (runtime jars) and "clib/" (build-time jars) jar files, run scripts ("bin/", configuration files ("configs/", including the usual configs/common directory), and minimum documentation ("doc/"). Additionally, most modules (see below) include directories with additional documentation and configuration files. Javadoc and source code is not included.
cougaar-support.zip	Third-party supporting jar files. Unpacks into "sys/" subdirectory where the Cougaar Bootstrapper will find them, without modifying your CLASSPATH. Built from the "jars" module in the Cougaar core project.
cougaar-api.zip	The Javadoc for all the main cougaar classes in one place. Unpacks to "/doc/api", putting the Javadoc with the module where the source originates.
cougaar-src.zip	Source code for each "lib/" module. Unpacks to per-module directories, as in core/src/.... Often include JUnit tests in a "regress" sub-directory, and examples.
md5sums.txt	MD5 checksums for all the above zips.
build.out	Output of the build process
errors.out	Error output of the build process, including deprecation warnings.

build.xml	ANT compilation script (build-generated for CougaarSE modules).
src/	Head of java sources for module, arranged like javac would expect to see in a CLASSPATH.
bin/	Executables, scripts and support
data/	Arbitrary (static) data for runtime use.
doc/	Documentation, in text and html
configs/	Configuration directories. Usually contains only subdirectories, each is a valid configuration.
examples/	Like src, but is never shipped compiled. The build process should attempt to compile and regression-test anything in here, but generated class files are never actually shipped.
regress/	Unit test sources for this module. Will be compiled and run by build process, reporting on compile, runtime and test failures. produced binaries are never installed or packaged. test should be the root of a java package tree - consider following "junit" format conventions.
test/	For Cougaar integration team use. May contain additional regression tests and jigs. Suggested format for organizations submitting software to the cougaar maintainers is a mirror of the top directory, aimed at integrators. Eg: src/ integration sources doc/ integrations notes, etc data/ configs/ ... test will not be considered by autobuilds and will not be (re)distributed.